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 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 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]
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:
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.
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.
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:
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 ]
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.
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:
Documentation for developers that want to use this system is a must. What more can I say?
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.
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.
Extend the BoostBook? XML format to contain the header dependency graph. May also include:
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.