Boost Documentation Format/Tasks

Consistency with DocBook (Difficulty: 2)

DocBook already contains elements for defining functions, classes, etc (e.g., ooclass, methodsynopsis). These elements are inadequate for C++ code (that's why we have C++XML), but we should strive to be consistent with these elements when possible. The task here is to study the C++XML structure and the DocBook structure, find differences between the two, and suggest specific changes to C++XML to rectify the differences. For bonus points, implement the changes to C++XML :) (Suggested by Bill Kempf)

C++ XML completeness (Difficulty: 2)

C++XML is very, very new and quite incomplete. The task is to find its weak spots (i.e., where it can't express certain C++ language features we need to express), report them and (hopefully!) suggest extensions or modifications to C++XML to accomodate these language features.

C++ XML DTD (Difficulty: 3)

C++XML has no DTD to specify its structure. A DTD would make it easier for developers to learn the C++XML markup, because it would be possible to validate C++XML documents.

[I will give it a try. --peter]

Concepts in XML (Difficulty: 3)

Boost libraries define and use many concepts, so concepts need to be a part of our documentation. We would like an XML format that describes the essence of concepts so that we can format concepts in the documentation. I've done a little bit of research into this already: there is a (possibly defunct) project called Caramel that used XML to specify concepts and then generate concept checkers, archetypes, and most importantly for us, consistent documentation. I'm currently in the process of obtaining permission to use parts of Caramel for our documentation project, and will report back when I can. There is a paper on Caramel here:

	http://citeseer.nj.nec.com/529212.html

Metafunctions in XML (Difficulty: 3)

Metafunctions are C++ class templates that are used throughout Boost. Unfortunately, documenting Metafunctions the same way as "normal" C++ class templates is unwieldy. We should have another XML sublanguage to express metafunctions, along with an XSLT stylesheet to produce documentation for them. This task also includes finding a good documentation output format for expressing metafunctions.

Scoped name lookup (Difficulty: 4)

Here's a nasty one. With the current prototype, we have the ability to write <classname>function</classname> and have it automatically create a link to the reference documentation for boost::function. However, what if we write <classname>boost::function</classname>? It should probably look only for classes named "function" within the "boost" namespace. Additionally, if a use writes <classname>python::function</classname>, then the scoped name lookup should find boost::python::function and not boost::function. Also, how to tell that <classname>function</classname> means boost::function in one instance, and boost::python::function in another? This will probably require some advanced knowledge of XSLT. For starters, the current (crude!) class name lookup is in reference-xsl/common/annotation.xsl in the prototype.

Update: Much improved name lookup is now available in common/lookup.xsl. The tags <methodname>, <functionname>, and <classname> can be used to mark references to methods, functions, and classes, respectively. These references can handle scoped names (e.g., python::function) and will perform lookups at global scope and within the current scope (i.e., when used inside <class> and <namespace> tags) and within scopes that have been imported via <using-namespace> or <using-class>. There is still no ambiguity resolution.

Autogeneration from Synopsis, Doxygen, etc. (Difficulty: 3?)

C++XML could be automatically generated from any tool that extracts documentation from C++ code. The task is to write a documentation backend for some of these tools so that Boost developers can write documentation in the source and still use the same back-end formatting that other developers use.

Doug Gregor and Jeff Garland have started to transform the Doxygen XML output into BoostBook?. The Doxygen XML format has several pitfalls that must be overcome to enable transformation into BoostBook? without losing information:

• C++ hierarchy should be represented in the XML hierarchy. For instance, a class "any" in namespace "boost" should be represented in XML with the "any" class enclosed inside the "boost" namespace's tag. We can rebuild this structure using the <innernamespace> and <innerclass> elements, but it is not a clean solution. The same problem occurs when determining which header file contains a particular entity: for classes we can match the <includes> element, but for functions or enumerations there is no such element.
• Doxygen XML output is not stable: it is broken in 1.2.17, 1.3-rc2, and current CVS. 1.2.18 seems to work
• Tags that should be empty (e.g., an empty briefdescription or detaileddescription) are not actually empty in the XML output. Instead, they are output with extra (significant!) whitespace as:

    <briefdescription>
    </briefdescription>

• Constructors and destructors aren't represented explicitly: we are forced to match the function name to the class name to identify them.

PS/PDF backend output (Difficulty: 2)

How can we generate high-qualify PS/PDF documentation? One route is to use the DocBook->FO XSLT stylesheets, and then use a tool like Apache's FOP to create PDF. Another route is to use one of the TeX?-generating DocBook processors (like OpenJade?) to build PS/PDF documentation. I've tried the former (the result is good, but not perfect), but have had no success with the latter. The task here is to try other methods and report back on the suitability of those methods.

[I believe we could get some mileage out of the tools at http://www.reportlab.com/opensource.html -- People/David Abrahams ]

Jam integration (Difficulty: 3)

Find a way to integrate building documentation into the build process, using Jam. For instance, it would be great to be able to type "bjam doc-pdf" and get back a PDF file containing Boost documentation. This is an ongoing task that may start simple (C++XML->DocBook via an XSLT processor, then DocBook->HTML via an XSLT processor) and will grow in complexity (Doxygen->C++XML->DocBook->FO->PDF...) as we learn more.

Convert existing documentation (Difficulty: 1)

Note: I plan on switching date_time as soon as feasible -- jeffg

Try converting some existing Boost documentation to the DocBook/C++XML format, and report your responses. It's probably best to start with a small library or, even better, a library that isn't changing often or whose author is not likely to convert the documentation himself. Some potential candidates: any, array, compose. Please get the author's permission first, and report back with any problems you encounter.

Conversions in progress/completed:

• Boost.Function (Doug Gregor)
• Boost.Signals (Doug Gregor)
• Boost.Ref (Doug Gregor)

Documentation, documentation, documentation (Difficulty: 2)

Documentation for developers that want to use this system is a must. What more can I say?

Spruce up the DocBook output (Difficulty: 2)

This is a pretty broad task, but it might include adding Boost logos into the headers and/or footers, getting links to Boost headers wherever the header name is mentioned, and getting clases & class templates into the table of contents for the library.

Create an index (Difficulty: 2)

Extend the XSLT stylesheets to create an index of all classes, class templates, and free functions. This would probably be implemented by adding another mode "index" (in addition to the current "synopsis" and "reference" modes) to the stylesheets.

Header dependencies (Difficulty: 3)

Extend the BoostBook? XML format to contain the header dependency graph. May also include:

• Determining how to present header dependency information
• Determining how to automatically extract header dependency information (Jam?)
• Updating the BoostBook? DTD

Annotated Program Listings (Difficulty: 4)

Documentation systems often parse source files and present stylized versions with links between the source files and the documentation of entities in those source files. This capability is desirable in BoostBook?, but we do not yet have an implementation strategy.