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

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2001-03-11 12:40:18

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.

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

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.

5. It should be possible to do "literate programming" in XML. I've been
experimenting with this for our BGL book. One extremely handy technique is
to specify preconditions/postconditions in the docs using real C++
expressions, and then suck these expressions directly into the real test
code.

Cheers,
Jeremy

----------------------------------------------------------------------
 Jeremy Siek                        www: http://www.lsc.nd.edu/~jsiek/
 Ph.D. Candidate                  email: jsiek_at_[hidden]
 Univ. of Notre Dame         work phone: [phone]
----------------------------------------------------------------------