Prev Next why

The Purpose and Motivation for OMhelp
  1. Introduction
  2. Same Time Documentation
  3. Version Control
  4. Language Independent and User Oriented
  5. World Wide Web
  6. Single Source
  7. Searching
  8. Cross Referencing Aids
  9. Platform Independent
  10. Latex Support of Mathematics
  11. Source Code Examples
  12. Spell Checking


Introduction
OMhelp was originally created to reduce the time and effort required to document the O-Matrix computer language. The CppAD CppAD is a better demonstration of what OMhelp can do. Brad Bell's home page is also written in OMhelp.

Same Time Documentation
Make documentation changes and additions at the same time as the source code changes. This reduces the total amount of work because the changes and additions to the system are fresh in ones mind when the documentation is modified. In addition, the other people on the project immediately have a specification (for the changes and additions) that is separate from the actual code.

Version Control
Use the same version control system that tracks changes to the source code to track changes to the documentation; see version control . This makes it easy and natural to make the documentation changes at the same time as the source code changes. In addition, the developer edits OMhelp commands directly instead of through a visual editor that displays what the user will see. This reduces the source changes between versions and makes them more meaningful to the developer.

Language Independent and User Oriented
OMhelp can extract documentation from source code comments of the system that is written in multiple languages. This makes it easier to accomplish the objectives listed above. In addition, embedding the documentation in the source code (in a language independent way) requires the developer to think about the changes from the users point of view. The doxygen system is similar with the following exceptions:
  1. Doxygen only works for systems in one language.
  2. Doxygen generates documentation from a developer (not user) point of view; i.e., it exposes implementation details.
When the users are developer and only one language is being used, Doxygen has the advantage of automatically providing language specific aids to the documentation.

World Wide Web
OMhelp can create both HTML and XML representations for display by browsers. The file names corresponding to the web pages are controlled by the OMhelp user and persist between different builds of the documentation. Web search engines tend to pick up individual OMhelp pages (that are part of a package documentation) as solutions to specific problems. In addition, links to these web pages are a good way to discuss problems and solutions.

Single Source
Many of the OMhelp features come from a single source philosophy. It is easy to create examples that are both source code and documentation. There is provision for jump tables such that if the destination text changes the source text changes automatically. A printable version of the web site can be generated with all the cross reference links included and numbered so they are fully functional.

Searching
OMhelp makes it easy to provide the user of the corresponding help system with the means of finding things quickly. For example, entries in the keyword index are also used by the OMhelp search utility. In addition, all the keywords are posted in meta commands that aid Web search engines in finding the corresponding documentation. Furthermore, a jump table for each section called reference table, a list of external links, and a table of contents are automatically provided.

Cross Referencing Aids
All of the internal cross references are checked when OMhelp is run. This informs one immediately when the help system changes in a way that breaks a cross reference (thus changes that have this effect are easier to make). In addition, it is possible to list all of the external cross reference links and where they occur in the help system. This makes it easy to check links that depend on things outside of the help system and that there usage within the help system is still correct.

Platform Independent
OMhelp will run under Microsoft Windows, Mac, or any Unix Operating system.

Latex Support of Mathematics
OMhelp supports Latex commands which it converts to MathML ( *.xml ) or MathJax ( *.htm ) for display by a browser. This is far superior to using pictures to display mathematics.

Source Code Examples
OMhelp has may options for including source code that also runs. This include some source code highlighting commands. It also makes it easy to keep the examples up to date with changes to a system (when the examples are also automated tests).

Spell Checking
OMhelp provides a spell command that lists spelling exceptions for a particular section. This relieves the user from having to allow the same spelling exception multiple times.
Input File: why.omh