Back to files

*** About KAVClient documentation

KAVClient documentation is maintaned in DocBook format. The main document file is kavclient.docbook. Various other format, such as HTML, PDF and RTF can be obtained from the DocBook source.

To create HTML documentation run make; to create PDF documentation run make pdf; to create RTF documentation, run make rtf.

• Technical details.
  • Creating HTML

KAVClient documentation is transformed into HTML using DocBook XSL stylesheets from docbook.sourceforge.net with a customization layer. The customization stylesheet is kavclient.xsl in this directory. Besides setting a few parameters defined by DocBook XSL stylesheets, it performs the following tricks.

1. Auto crossreferencing of functions. In KAVClient HTML documentation, each libkavclient function name is a hyperlink linking to the function synopsis, unless the synopsis is in the same section as the function name (I decided it made little sense to cross-link within the same page). To this end, an XSL key is defined of funcsynopsis element, and a custom template matching function element is defined. It makes use of "href.target" template from DocBook XSL stylesheets. The stylesheetis also generates IDs for funcsynopsis elements that don't already have them.
2. "Funcsect" olinks. KAVClient documentation has olink DocBook elements with type attribute set to "funcsect". This is a "custom" olink, not supported by DocBook XSL stylesheets. Such olink element must have a localinfo attribute set to a name of a libkavclient function. This olink element generates a link to the section where this function is defined. The customization stylesheet accomplishes this by defining a custom template matching olink element with type="funcsect". The template makes use of href.target template of DocBook XSL stylesheets, as well as their xref-to mode.

Additional trick is employed to generate lists of possible error codes for each libkavclient function. The source for these list is the master error code list in section "libkavclient error codes", marked up as a msgset element with id="kavclient-errors". Within this msgset the following conventions are observed:
* In each msg element, there's msgmain/title/errorname element containing the error code symbolic constant.
* In each msg element there's msgtext/para element containing short error description as returned by kav_strerror. * In each msgexplan element the first paragraph has attribute role="applies-to" and describes to which functions this error code applies. Function names are marked up appropriately with function element. * If a piece of explanatory text applies to only one of the functions that the error code applies to, this text is marked up with <phrase condition="function_name">...</phrase>. If a piece of text should be included only in the master listing, but not in any of the function own error list, it is marked up with <phrase condition="common">...</phrase> (in fact this has been used only for conjunction "or").

Once these conventions are followed, the DocBook source is processed with function-errors.xsl stylsheet to produce function-errors.xml that contains the error list for each function. Appropriate pieces of function-errors.xml are included into the main DocBook source by means of XInclude. Unfortunately, this means that kavclient.docbook does not truly confirm to DocBook DTD, since DTDs are not namespace aware and cannot validate documents with multiple namespaces (DocBook and XInclude). This also means that your XSLT processor must be XInclude-aware. I use xsltproc from libxslt package (http://xmlsoft.org/XSLT/) with --xinclude option.

• Creating PDF and RTF

PDF and RTF are produced by Jade using DocBook DSSSL stylesheets from docbook.sourceforge.net. I experimented with producing PDF by first converting DocBook to XSL-FO with XSL stylesheets, and then converting XSL-FO into PDF with passivetex. This seems to work with the latest version of passivetex (1.22), but I liked the look of Jade's PDF better.

Since I don't know DSSSL, and DSSSL obviously does not support XInclude, I decided to implement the tricks mentioned in the HTML section above by preprocessing the source DocBook file into an intermediate DocBook file that has all the tricks with XSLT. This is accomplished by preproc.xsl stylesheet. It does the following:
1. Function crossreferencing. It wraps each function element into link element to link to funcsynopsis element that defines this function (unless the funcsynopsis element is within the same section as the function element). This achieves the same effect as function crossreferencing in HTML version.
2. The "funcsect" olinks are processed by transforming them into xref elements that link to the appropriate section.

Finally, function error code lists are XInclude'd by the XSLT processor. BTW, this makes the preprocessed DocBook file fully confirm to DocBook DTD.

As a final note, this documentation system is surely way too complex for such a small library as kavclient. It was mostly done for fun and to learn DocBook, XML and XSL.