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

From: David Abrahams (abrahams_at_[hidden])
Date: 2001-03-11 16:20:14

----- Original Message -----
From: "Jeremy Siek" <jsiek_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Sunday, March 11, 2001 12:40 PM
Subject: Re: [boost] Re: Boost Documentation [was Iterator Adaptors]

>
> I'm definitely in favor of going in the XML direction with boost
> documentation. My group at ND has been looking at using XML to create
> "concept" descriptions, which are the basis of many forms of output: html
> docs, latex docs, C++ concept checking classes.
>
> Here's a few random thoughts on the subject:
>
> 1. The power of XML is in the ability to create *new* DTD's and define the
> semantic information contained... and how that should be mapped to other
> DTD's.
>
> 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
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.

> 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 "<".

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?

-Dave