Boost logo

Boost :

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 15:05:08

On Tuesday 29 October 2002 08:46 am, Maciej Sobczak wrote:
> AFAIK, the well-established way to write anything is to use LaTeX. It
> has all the characteristics you write, from "omnipresence" to
> possibility to convert to any format I've heard of.
> - XML is more trendy in this season.
> I'm really sorry if you find the second point offensive, but I just do
> not understand the motivation for the additional effort with XSLT. Note
> also that the description of the logical structure of the text is much
> more concise in LaTeX than in XML. At least I think so.

I'm not concerned at all with normal text. DocBook, LaTeX, Doxygen, or
reStructuredText will all do a fine job at formatting text for tutorials,
descriptions of classes, etc.

I'm concerned with the code part of reference documentation. If you take a
look at the C++ standard documentation style, there is a lot of repetition:

  The header synopsis gives C++ code containing essentially forward
declarations of every entity in the header.

  The documentation for each class (template) gives C++ code for the
definition of the class template, with declarations for associated member and
free functions.

  The documentation for each function (template) gives the declaration of the
function (template).

I don't want to type the same function (template) declaration 3 times, because
I'm going to make a mistake somewhere. I want to give "the tool" my
declaration and have it generate the synopsis sections automagically. The
questions are then:
  1) How do we represent the C++ structure
  2) How do we transform that C++ structure into consistent documentation

One solution set is {1->XML, 2->XSLT}. Another solution would be to write a
LaTeX macro package to do the transformation from C++ structure (perhaps
represented as macro invocations) into readable documentation.

For reference, here's the XML for a simple exception class:

<header name="boost/function.hpp">
<namespace name="boost">
    <inherit access="public" base="std::runtime_error"/>
      <effects>Constructs a <code>bad_function_call</code> exception

The XSLT stylesheet will:
  1) Add "class bad_function_call;" to the synopsis of header
<boost/function.hpp>, with a link from bad_function_call to its
  2) Create a section for bad_function_call and synthesize its definition in a
consistent way. All declarations have links to their documentation.
  3) Create a subsection for bad_function_call constructors, along with
detailed reference documentation for the constructor that is defined.

I'd be perfectly happy if we could have similar input as, e.g., LaTeX macro
invocations and then expand those macros to get the same effect. If you
haven't already, please look at the .xml input and the .html output for the
sample Boost.Function documentation. I've been using LaTeX to write
papers/homework/etc. for several years, and I'm not sure I'm up to the task
of writing such a transformation; I learned XML & XSLT two days ago and we
have a working prototype.

Just as we must not be fooled by the buzzword-speak of zealots, we cannot be
so defiant that we ignore any truth they utter.


[I'm going to try to pin down my set of requirements for Boost reference
documentation so that we can try to evaluate potential solutions more

Boost list run by bdawes at, gregod at, cpdaniel at, john at