Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Conclusions Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Supporting Tools and Documents

Subsections

Implementation Plan

This section describes a phased approach for adopting and implementing the proposed change to the documentation system. Because XML is easily converted into other formats, this framework is well-suited for gradual adoption. This is helpful as there are many details that have to yet to be worked out. As each phase is completed we will have the opportunity to re-evaluate the framework in light of the implementation and tools available to date. It is expected that the steps listed below would be turned into development targets.

Phase I: Initial GlishDoc implementation

1.: Adopt and/or create a DTD for encoding tool descriptions that will be extracted from the source code. Define necessary GlishDoc-style tags for documenting tool source code.
2.: Implement an initial version of the GlishDoc document extractor in Glish. (It is expected that a Glish implementation will be easier for a typical AIPS++ developer to maintain than one based on, say, Perl. It also allows the possibility for further integration of the documentation extraction into the AIPS++ system in the future.)
3.: Develop (or adapt) style sheets to convert XML tool descriptions into currently supported .help and _meta.g files. Install wrapper script that applies style sheet transformations to XML descriptions. (Augment the EMACS Glish mode to add keyboard macros for inserting commonly used GlishDoc markup.)
4.: Create an AIPS++ note describing how to use GlishDoc tags to mark up in-lined documentation and how to use associated tools to extract the documentation and convert it to currently support forms.
5.: Encourage developers to try in-lining documenation. Evaluate current state of framework for ease-of-use, robustness, adaptability to the AIPS++ system, and effects on the quality of documentation and software process. Adjust plan for later phases accordingly.

Phase II: Initial Use of DocBook

1.: Decide on the specific relationship between DocBook and the XML used by GlishDoc as described in §2.2.2, p. (if not already determined in Phase I).
2.: Define any extensions to the DocBook DTD needed for supporting AIPS++ documents. Ease of use by authors should be an important factor in defining new tags.
3.: Adapt the LyX DocBook layout class as necessary and helpful for creating AIPS++ expository documents.
4.: Create (or adapt) style sheets converting DocBook documents into L^ATEX in the traditional AIPS++ style.
5.: Create a DocBook-formatted template for creating AIPS++ notes.
6.: Create an AIPS++ note using DocBook that describes how to use DocBook, LyX, and associated tools for authoring expository documents for AIPS++.
7.: Encourage developers to try DocBook and LyX for creating documenation. Evaluate current state of tools for ease-of-use, robustness, adaptability to the AIPS++ system, and effects on the quality of documentation. Adjust plan for last phases accordingly.

Phase III: Final Integration

Assuming the first two phases are successful and the framework is determined to be useful, this phase completes the adoption of the new framework.

1.: Adapt existing validation tools to check the syntax and completeness of GlishDoc documentation.
2.: Create (or adapt) style sheets for used to convert XML-based documentation into other needed formats, including HTML, PostScript/PDF, and (if necessary) plain text. (Unless a pre-existing tool for direct conversion to PostScript or PDF is available, it is expected that XML will be converted first to L^ATEX for subsequent processing into the hardcopy format.)
3.: Fully integrate tools that can be used by authors for validating and formatting DocBook and GlishDoc documents into the AIPS++ system.
4.: Adapt the AIPS++ make system as appropriate to build new XML-based documentation.
5.: Determine how much of the documentation should continue to be built locally to the AIPS++ and how much should be preformatted and delivered to an AIPS++ site on demand.
6.: Convert limited number of existing AIPS++ documents to DocBook format. This conversion should be limited to those documents that will be edited further into the future.
7.: Convert all existing L^ATEX-formatted Reference Manual documents to XML (DocBook) documents.
8.: Create a style guide for creating complete, high-quality, inlined Glish tool documentation.

Next: Conclusions Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Supporting Tools and Documents Contents