Re: [boost] Reference documentation: one approach

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">
  <class>
    <name>bad_function_call</name>
    <inherit access="public" base="std::runtime_error"/>
    <constructor>
      <effects>Constructs a <code>bad_function_call</code> exception 
object.</effects>
    </constructor>
  </class>
</namespace>
</header>

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

        Doug

[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 
objectively]