Development: DocbookForWxDocs

XML-based documentation format

Using some XML-based format for the wxWidgets documentation is current being discussed. This has clearly not happened yet, see Development: Documentation.

I see much virtue in an XML-based format, and have done work to [http://www.bzzt.net/~wxwidgets/index2.html make this happen].

If you want to help, please look at XML-Based_Documentation_Format-Ongoing Work

Solution overview

The XML-based documentation consists of 2 parts:

• The class reference, as a document in a special-purpose wxClassXML with actual content-markup (as opposed to only presentation-markup). Warning: this file is big, some browsers will have problems displaying it.
• The rest of the reference manual, as a DocBook document set

From the class reference, all kinds of useful information can be extracted.

It can also be transformed (with an xslt script) into a DocBook chapter, which can be easily plugged into the rest of the reference manual.

The combined DocBook document can be processed to generate PDF, CHM, HTML, etc, basically replacing tex2rtf in that respect.

Acceptability

This solution seems to meet all requirements; looking at Development: Documentation, these are the corresponding features of the Docbook XML approach:

1. Docbook format can be edited by hand or by using WYSIWYG tools. See "Tools" below.
2. Installation for converting docbooks to other formats can be easily installed on linux (typically a matter of installing the "docbook-xsl" package) and on win32 (see e.g. http://wxwpm.sourceforge.net/docbook-tools-win32.zip).
3. DocBook can be used to convert to all popular formats (HTML, CHM, PDF, Manpages, etc) and virtually to any other format.
4. Arnout Engelen has already written much of the necessary scripts for converting automatically the current laTex docs to an xml format that can be converted into docbook.
5. producing "customized" documentation should be quite simply with standard XML processing tools (e.g. a specific version of the manual for wxPython).
6. warning whenever reference docs are out of sync with wxWidgets public function definitions (c.q. vice-versa :)) is tricky, but possible.

Value added

• we no longer depend on tex2rtf (and its bugs and strong limitations): the DocBook toolchain (which is more widely used and supported) takes over its task
• we can generate many useful other things from one source. Examples:
  • a listing of all event macro's
  • manpages
  • a table showing which classes are supported on which ports
  • a class hierarchy
  • ]http://arnout.engelen.eu/~wxwidgets/xmldocs/planned-schematic.png schematic explaining how file formats could work together]

Feasible

http://bzzt.net/~wxwidgets/xmldocs

Outstanding issues:

• aesthetics of the result - currently rather crude, but DocBook seems to be quite tweakable
• references don't always work yet
• wxDb needs to be converted

Tools

Docbook website has a page with a list of the authoring tools: [[1]].

Here is a list of WYSIWYG tools tested by Francesco Montorsi:

• XML is pretty easily edited with a text editor, plus there are nice XML editors available.
• Some editors mangle whitespace, so people would have to run a cleanup-script before committing a document formatted with such an editor

Comments

what about stuff that can be gleaned from looking at the code?

Should we include stuff that can be gleaned from looking at the source code? - duplicating this information seems like a recipe for inconsistancies. Ideally the source itself should be parsed for this - for example with something like doxygen.

• This would be possible if there was a single `wxWidgets interface'. However, what implementation is currently used (gtk, msw, with/without unicode, etc) directly influences which files are parsed, so this might lead to inconsistencies. In my opinion it would be better to see the hand-written documentation as a specification. You could then parse the source with for example doxygen and check that the implementation adheres to the specification. Some work has been done: http://www.bzzt.net/~wxwidgets/xmldocs/applications/checker/

boost

It might be worth considering working together with the Boost project, who seem to be doing roughly the same thing: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost_Documentation_Format

FAQ

Will it be easier for users to change the documentation?

People generally aren't more comforatble with TeX than they are with HTML, so this'd be a mild `yes'.

Will it be easier for users to check that their changes don't break something?

I think so: XML validation tools (like XMLlint, or just opening the file in Mozilla/Firefox I think) are generally available, whereas tex2rtf can be a pain to install. However, http://wiki.wxwidgets.org/docpatcher kindof makes this a moot point (when it's adapted to XML, which should be simple).

But if the tex doc's can be automatically converted to XML anyway (like Arnout did), we already have all benefits without needing to change formats, right?

Not really: the conversion is basically a big hack for one-time conversion, not something reliable.