RE: [boost] Re: Boost Documentation [was Iterator Adaptors]

From: Jeff Garland (jeff_at_[hidden])
Date: 2001-03-11 17:38:03

> > 2. Content should be separated from display, i.e. the xml tags used in a
> > document should describe *what* the content is, not *how* it should be
> > displayed. A separate stylesheet is then used to map the content-oriented
> > tags to the display-oriented tags. Hence, I envision boost docs having
> > their own DTD's, and then we will have a set of XSL stylesheets to convert
> > these to various other formats.
>
> Do we really need to invent our own DTDs for boost? It seems to me that

I would think that at most we would want to extend existing DTD's.  The main
excuse I can see for extending is a failure to cover generic programming or
other C++ specific concepts not available elsewhere.  From what I can see,
building a robust DTD that will cover everything needed by Boost would be a huge
undertaking.  Unfortunately, I think even using existing DTD's will take a lot
of research, experimentation, and learning....

> there ought to be appropriate DTDs for documenting C++ libraries
> somewhere... if we /do/ need to invent them here, at least we ought to try
> to get them standardized.

Another possible spec that we could use as a starting point is the OMG metadata
interchange format (XMI).  It is targeted at UML models and as such as detailed
specifications for handling standard modeling constructs.

On the downside, I'll bet it isn't too good for dealing with template stuff
(probably lacks template functions, etc).  I'm guessing a bit here b/c I don't
have time to look, but based on my UML experience it just doesn't deal with much
of what C++ can now do.  Anyway, you can have a look at

http://www.omg.org/technology/documents/formal/xml_metadata_interchange.htm

I recommend going directly to Appendix C and looking at the examples to get an
idea of what it can do without wading thru a ton of junk...

> > 3. Writing C++ code inside of an XML document is not easy due to the "<"
> > and ">" issues. I've been thinking about creating an alternative syntax
> > for XML that uses symbols other than "<" and ">", perhaps "@<" and "@>". A
> > simple translator could then convert our alternate-xml into real xml,
> > converting "<" to "&lt;" and "@<" to "<".

I think that this is only the tip of the Iceberg.  We really need to consider
using something like Doxygen to generate XML models from the actual code.
Otherwise, you will be typing everything you want to document twice, or
extracting your header file from your XML (screaming heard in the background!).
I use Doxygen for HTML output, but I believe there is an experimental XML output
available.

> FWIW, I have some nice elisp which can paste text as blockquoted and
> preformatted, adding the appropriate transformations for "&", "<", and ">".
> If anybody wants it, please let me know.
>
> > 4. XSL is good for *simple* transformations of XML documents... but it is
> > extremely verbose, and pure functional, which makes more complex
> > transformations hard to program. It would be nice to be able to write the
> > transformations in C++ instead. Perhaps we should define a generic "Tree"
> > concept, and write wrappers for some existing DOM implementation like
> > Xalan.
>
> Having only a passing familiarity with the /concept/ of XSL, and none with
> Xalan, I don't follow. Could you elaborate a bit?

XSL is an XML based language which allows for transformation of XML documents.
Xalan is the Apache open source implementation of an XSL processor. Essentially
it is an XML parser which can read a document tree, read the XSL translation
spec and output the transformed document.  The output document might be HTML,
plain text, or another XML document.

To get more concrete, the following is an example of an XSL stylesheet that
would be used to change an XML document with "title" and "author" elements into
an HTML document with the title in a Header 1 (H1) element and the author in a
header 2.

<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' >

<xsl:template match="/">
<H1><xsl:value-of select="//title"/></H1>
<H2><xsl:value-of select="//author"/></H2>
</xsl:template>
</xsl:stylesheet>

Of course this barely scratches the surface of XSL, but you get the idea.
Anyway, having spent some time using XSL, I (like Jeremy) find it ugly and
painful to say the least.  However, it is unimportant because as long as the
data is structured in the first place we can decide to use XSL, C++, Perl,
Python, our whatever to transform it....

Thoughts?

Jeff