The Hush Online Technology Toolkit
Even with the existence of numerous tools
for software documentation
a number of issues come up when one attempts to arrive
at a fully documented system.
First of all there are several kinds of document types,
plain or structured text such as for example requirements
specifications,
but also code, in a bewildering variety,
and configuration information.
Secondly, one needs s preferably uniform style
of annotation for the various kinds of program code
and configuration code.
Issues
- document types -- code, configuration, text
- annotation -- C++, Java, IDL, scripts
- documentation format -- dot-tee pseudo SGML
- tools -- Java/C++/IDL Doc
- conceptual graphs -- ciao, acasia , dotty
- indexing -- file level (find), content level (glimpse)
slide: The Hush Online Technology Toolkit
For presenting the documentation, furthermore,
one needs some suitable
formatting language, such as HTML, LaTeX, or SGML.
For hush I used the dot-tee format, which
is somewhere in between SGML and HTML. An euphemism, indeed.
The formatting language must be (conforming to) the output
of the various tools that are in use.
In reality, I had to modify these tools to make
them conform to my standard!
Text being text,
it is nice, in addition, to
be able to create
conceptual graphs, preferably in a reverse engineering fashion.
And finally, a point which also holds for the previous issue,
given the size of the potential document base,
there must be support for indexing,
both on a file level as well as on a content level.
Tools
The actual toolkit consists of a small collection
of filters and scripts
that may be used to generate HTML documents.
Tools
slide: Tools
In addition, I used several utilities
such as Acacia and
[Ciao] for creating graphs,
Doc++ for creating structured documentation
for C++ and Java
and IDLDoc for documenting CORBA IDL.
Minor modifications of these utilities were necessary though,
in order to arrive at a consistent format.