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

From: Jeff Garland (jeff_at_[hidden])
Date: 2001-03-09 19:46:03

One advantage of XML is that a technical publication standard called docbook
already exists.  I haven't used it so this isn't any sort of endorsement or deep
knowledge transfer.  However, what I have seen of it on the web it looks very
interesting.

The sites below are a good place to get started.

Home of Docbook:
http://www.oasis-open.org/docbook/intro.html

Online version of O'Rielly user book:
http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html

Norm Walsh site (he co-authored the book)
http://www.nwalsh.com/docbook/index.html

If you dig through some of the links you will find that the latest versions of
docbook support tags for highly specialized items such as classes, methods,
parameters, etc.  This is in addition to the basic constructs (titles, sections,
etc) for writing books and other publications.  Just as an example, the link
below describes the schema for the "constructor synopsis" tag:

http://www.oasis-open.org/docbook/documentation/reference/40update/constructorsy
nopsis.html

I'm going to guess that if boost adopted it there would need to be extensions
for generic programming constructs :)

Since everything is tagged with appropriate meta-data you can do sophisticated
processing of the information using standard XML tools such as XSL/XSLT.  Having
done some work with XSL scripts, I would prefer to write a perl script (or regex
program), but regardless, the data is structured and hence allows for easy
machine processing.

Hope this helps.

Jeff