Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Supporting Tools and Documents Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Introduction: The Current State of AIPS++ Documentation

Subsections

Use of DocBook
- Advantages of using DocBook
- Potential Pitfalls
In-line Documentation for Glish
- The Case for In-line Documenation
- Features of the In-line Documentation Framework for Glish

An XML-based Framework

This proposed framework addresses the creation, maintenance, and delivery of the two types of documentation aimed at end users: expository documents and the Reference Manual. The author feels that the current framework for documenting C++ code in-line is pretty good. It's backed by a formal quality assurance process that is reasonably effective. Furthermore, the large amount of C++ code documentation already in place makes substantial changes to it hard to justify. Documentation for the end user is more important. In particular, this author feels that changes to how the Reference Manual is constructed will result in the greatest benefits for users.

This new framework is based on the following principles:

1.: Users must have access to documentation on-line.
2.: Users must be able to print out documentation in a high-quality form.
3.: It is not necessary that documentation built locally from source files as part of a standard AIPS++; installing pre-built documentation should be sufficient.
4.: Authors must be able to easily build and validate their documents for the different versions supported by the system.
5.: HTML is the best format for the on-line version as it offers the greatest flexibility to the user for presentation (e.g. font style and size, window size, foreground and background colors).
6.: It is easier to enable automated machine-processing of metadata and documentation using XML than L^ATEX.

The proposed framework is characterized by two key features:

DocBook, a system for structuring documents in SGML or XML, is used to create and maintain expository documents.
The Reference Manual as well as the Tool Manager metadata files (i.e. tool_meta.g) are generated from in-lined comments using a markup similar to JavaDoc but which is converted to XML upon extraction.

XML will serve then as the base format for conversion into other formats. HTML is used for browser-based access. Plain text can be used for access within an interactive Glish session. Hardcopy can be provided in either PostScript or PDF format.

Use of DocBook

DocBook is perhaps best known as the most widely used SGML markup language available as open source and freely available. It is maintained by the DocBook Technical Committee of the Organization for the Advancement of Structured Information Standards (OASIS). DocBook began its life in 1991 as an SGML DTD; however, with Version 4.1, an XML version is now available and supported by the most common DocBook-compliant tools. The XML version includes MathML as an extension for marking up mathematical equations. The DocBook DTD is modular in design and has an explicit framework for extending it to add new elements or further control attribute values.

Advantages of using DocBook

DocBook is well supported

O'Reilly publishes a book on DocBook².
LyX, a free WYSIWYG editor, ³can create and export DocBook-format documents. Successful use of this application could minimize the amount authors need to learn about DocBook as a markup language. It is possible to add new Layout classes to LyX that make it easier to create documents that must conform to particular styles. (In fact, in addition to its DocBook layout classes and templates, LyX also ships with support for other styles, including one for the AAS journal manuscripts.) An easy-to-use word processor of this sort may make documentation authoring more attractive to non-developers.
Several packages are freely available for converting DocBook to other formats. Jade provides extensible DSSSL style sheets for converting to L^ATEXand RTF. (Jade can also be used for validation.) nwalsh.com supplies free, customizable XSL stylesheets for converting to HTML. Novell has produced a UNIX script for converting DocBook to HTML.
A few commercial products such as Adobe's FrameMaker+SGML and WordPerfect 9.0 for MS Windows support DocBook ``out of the box.''
The wide variety of generic SGML/XML tools can be used with DocBook documents.

DocBook is widely used.

The Linux Documentation Project uses DocBook for authoring the various HOWTOs, FAQs, and Project Guides it maintains. In fact, there are a few aspects of the LDP model that we can borrow:
- availability of a HOWTO-HOWTO document for new authors,
- style guides,
- standard style sheets,
- recommended authoring tools.
The K Desktop Environment (KDE) uses DocBook for its documentation. They provide a very nice ``crash course'' document entitled Writing Documenation using DocBook.

DocBook is a cross-platform format.

DocBook documents can be edited with any editor.

As with all SGML/XML formats, content and presentation are seperated.

This has two important ramifications. First, the presentation can be evolved without having to alter the source documents. Second, it is not necessary that all authors have the specific skills for manipulating presentation.

XML offers greater flexibility for controling presentation.

It's worth noting that in principle, L^ATEX separates content and presentation as well; however, in can be argued that this does not happen in effect. The expertise necessary to alter a style file and subsequently support it with L^ATEX2HTML discourages experimentation with presentation. In this author's opinion, manipulating XML style sheets is much easier than L^ATEX style files.

Potential Pitfalls

Very few actual experiments using DocBook for AIPS++ have been done to date, and many of the details concerning how we might use it have not been worked out, yet. Here are some ways that DocBook may not live up to its promise:

The effort for adapting style sheets for use with AIPS++ may be more extensive than expected.
Extending DocBook for handling AIPS++-specific structures (analogue to aips2defs.tex) may be more difficult than expected, or doing so makes generic DocBook tools less helpful. (It appears at this time, however, that we can make effective use of DocBook with little or no extensions to the DocBook DTD.)
It may be necessary but difficult to adapt LyX for creating AIPS++ documentation. Without LyX or similar product, authors will have to learn the details of the DocBook DTD which defines about 100 different elements.
It is too difficult to convert existing documents into DocBook when necessary. This is expected to apply only to documents like Getting Results that will continue to evolve and expand.

In-line Documentation for Glish

The Case for In-line Documenation

Given the proper supporting tools, in-line documentation of software can provide tremendous advantages:

Much of the information that needs to appear in the documentation can be extracted directly from the code itself. This includes:
- tool and function names and indices
- function signatures
- parameter names
- default values
As a result, quite a bit of information can be extracted with little or no markup included. Furthermore, this reduces the amount of redundant information the developer has to type in.
In-line documentation aids fellow programmers in understanding what the code does when the code is examined directly.
It enables a convenient regimen for developing documentation simultaneously with the development of the code itself. Otherwise, documenting the code can seems more like a separate chore, usually started after the development work is done.
It is easier to keep documentation up-to-date with code changes, since the relevent information can be kept close to the actual implementation.
In-line documentation favors a format that is well suited for a reference manual. Since in-line documentation appears close to the thing it is describing (e.g. tool or function definition), the information tends to aggregate to predictable locations in the documentation. This is important to users when they are looking for specific information.
Well-structured in-line documentation can encourage completeness. Tags that mark up such things as default and allowed values make it more convenient to include full descriptions of these items. Furthermore, because some information can be extracted automatically, such as default values, it can be made more obvious to the developer when these descriptions are not present.

Features of the In-line Documentation Framework for Glish

For the purposes of discussion, this note will refer to the framework for in-lining documentation into Glish code as GlishDoc. An implementation of this framework as described here may result in a software tool of the same name.

This section gives an incomplete description of how the proposed framework for in-lining documentation will work. An extended example of documented code is given in Appendix A.

Developers markup Glish source code files using specialized markup tags (see below) within Glish comments. It should be possible to filter out these comments as part of the AIPS++build system if they pose a performance problem.
To process the documentation, GlishDoc comments are extracted from the Glish source code and converted into XML using a custom extraction tool (implemented in Glish).
The XML DTD used for GlishDoc documentation may either be an extended version of DocBook or a custom DTD for Glish documentation. If the former is chosen, it will be necessary to define a number of tags to describe Glish tool interface components and characteristics. In the latter case, we may want to enable a further conversion to the DocBook DTD in order better to integrate the reference manual with the rest of the documentation. A hybrid solution (e.g. akin to the way DocBook supports MathML) may also be possible.
The GlishDoc extraction tool constructs the basic XML document primarily from the Glish code itself. Markup tags added by the developer further guide and augment the output document's structure and content.
A GlishDoc comment block has a special format that identifies it as such. The GlishDoc comment block starts with a line that contains only a comment starting with the characters #@. Subsequent comment lines are included in the block. The block ends prior to the first line that contains either Glish code or the start of another GlishDoc comment block. For example:
```
#@
# Writes a summary of the properties of the imager to the
# default logger.
public.summary:=function() {
```

Markup tags use the JavaDoc style syntax of the form @tag_name. The marked text appears after the tag and continues either until the next tag or the end of the block; interpretation depends on the tag. This style of tag is quicker to type and less prone to errors than XML or L^ATEX-style tags because it requires a minimum of special characters and does not require a closing element or brace. For example,

#@
# Summarize the measurement set.
#
# This function will print a summary of the measurement set to the
# system logger. The verbose argument provides some control on how
# much information is displayed.
# 
# @outparam header  Selected header information returned as a Glish 
#                   record.
# @inparam  verbose If true, produce a verbose summary.
public.summary:=function(ref header=[=], verbose=F) {

XML tags can also be used for special types of markup within descriptions. This will be useful for including links to other documents, inserting tables or figures, or including mathematical formulas. The GlishDoc extraction tool would pass this markup unchanged.
Many markup tags can be assumed based on the context of the GlishDoc comment block. For instance, the first example above could also be written as:
```
#@tfunction
# Writes a summary of the properties of the imager to the
# default logger.
public.summary:=function() {
```
However, the fact that the text describes a tool function can be assumed because it appears within a tool definition and just before a function definition.
Among the available GlishDoc tags will be an include directive (e.g. @include filename). This will allow one to easily include longer descriptive sections that may be more easily authored externally using DocBook markup and LyX.
All the functionality provided by the current L^ATEX markup (defined in aips2help.sty) would be duplicated in the GlishDoc framework.
Developers can also include information needed by the Tool Manager to build GUIs automatically. Initially, this information could be transformed from XML into Glish code of the form currently supported via the tool_meta.g files. In the future, this information could be accessed directly from Glish via a Glish XML parser client.
Prior to checking in documented code, developers can run it through a validation tool that will alert them of syntax errors and warn them about missing markup that is required by the style guide.

Next: Supporting Tools and Documents Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Introduction: The Current State of AIPS++ Documentation Contents