3.9.2 Documentation of a library
The typesetting language in which the SINGULAR documentation is
written is texinfo. Based on various tools, info, dvi, ps, and
html versions of the texinfo documentation are generated.
Starting with SINGULAR version 1-3, the texinfo
documentation of all libraries of the SINGULAR distribution is
generated automatically from their source code.
More precisely, for each library,
- - the info string of the library is parsed and typeset
as explained in Typesetting of help strings.
- - the help string of each procedure listed in the
PROCEDURE:
section of the library info string is parsed
and typeset as explained in Typesetting of help strings.
- - the example of each procedure listed in the
PROCEDURE: section of
the library info string is computed and its output is
included into the documentation.
For a uniform look-and-feel of the library documentation, library
developers should
- - follow the recommendation of
The help string of a library and The help string of
procedures.
- - consult the source code of libraries like
template.lib (see section template_lib)
for examples on how library documentations are
written.
- - make sure that each procedure listed in the
PROCEDURE:
section of the library info string has a help string and an example
section.
- - not use interactive functions like
pause("..") or read(""); (see section read) and should limit the
length of input lines to 60 characters in the example section of
procedures.
- - carefully check the generated
documentation of their libraries in its various formats using the
lib2doc (see section lib2doc) utility.
|