[Home]Boost Documentation Format/Tasks

BOOST WIKI | Boost Documentation Format | RecentChanges | Preferences | Page List | Links List

Difference (from prior major revision) (no other diffs)

Changed: 1,113c1,169


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)



Assigned to:

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)



Assigned to: People/Peter Simons

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)



Assigned to:

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)



Assigned to: People/Aleksey Gurtovoy

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)



Assigned to: [Doug Gregor]?

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?)



Assigned to:

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)



Assigned to:

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)



Assigned to: [Rene Rivera]?

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)



Assigned to:

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)



Assigned to:

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

Spruce up the DocBook output (Difficulty: 2)



Assigned to:

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)



Assigned to:

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)



Assigned to:

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)



Assigned to:

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.

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)

Assigned to:

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)

Assigned to: People/Peter Simons

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)

Assigned to:

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)

Assigned to: People/Aleksey Gurtovoy

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)

Assigned to: [Doug Gregor]?

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?)

Assigned to:

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:

    <briefdescription>
    </briefdescription>

PS/PDF backend output (Difficulty: 2)

Assigned to:

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)

Assigned to: [Rene Rivera]?

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)

Assigned to:

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, documentation, documentation (Difficulty: 2)

Assigned to:

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

Spruce up the DocBook output (Difficulty: 2)

Assigned to:

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)

Assigned to:

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)

Assigned to:

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

Annotated Program Listings (Difficulty: 4)

Assigned to:

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.


BOOST WIKI | Boost Documentation Format | RecentChanges | Preferences | Page List | Links List
Edit text of this page | View other revisions
Last edited December 18, 2004 12:17 pm (diff)
Search:
Disclaimer: This site not officially maintained by Boost Developers