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:
Doxygen only works for systems in one language.
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: omh/why.omh
