Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 803

News	FAQ
Search	Home

Introduction

The objective of this system is to provide a way for programmers to document source code in a way which allows documentation to be extracted and converted into a reference document. To accomplish this, it is necessary to provide a way for the programmer to specify information which supplements the regular comments. This ``extra'' information is know as markup. The markup provides a means of structuring the comments, and allows them to be formatted in ways more sophisticated than ASCII text.

This system allows both the source code and the documentation for the source to exist in the same file. This close proximity will increase the chances that the reference document will remain up to date. In addition, the goal is to have a parser which understands most of the C++ language. This allows much of the reference document to be generated automatically from the source code.

The first revision of this system used a language similar to the roff dialects. This language was abandoned in favor of SGML, Standard Generalized Markup Language. There are a few reasons for this:

• Since SGML is an ISO/ANSI standard many tools are likely to be available in the future to support it.
• Generalized markup is a better model for information reuse and flexibility. It allows the information it structures to be used by a variety of applications.
• SGML provides a good basis for future expansion.
• Many successful applications already use SGML, and the work they and the various standardization groups have done can be leveraged to our benefit.