Manuals

Hand written and automatically generated documentation atoms and isotopes are combined into manuals. Two different kinds of manuals may be generated.

1. User Manual
2. Programmers and Reference Manual

When the documentation is assembled, VMake scans the project for documentation atoms and isotopes. In a second phase these are combined with the automatically extracted documentation to form the manuals. The following documentation atoms are combined into the User Manual:

• ``about.tex''
• ``intro.tex''
• ``motiv.tex''
• ``terms.tex''
• ``tutorial.tex''
• ``concept.tex''
• ``interact.tex''
• ``fileio.tex''
• ``indata.tex''
• ``outdata.tex''
• ``dialog.tex''
• ``ui.tex''
• ``panels.tex''
• ``exec.tex''
• ``theory.tex''
• ``examples.tex''
• ``install.tex''
• ``history.tex''
• ``future.tex''
• ``faq.tex''
• ``refs.tex''

For the Programmers and Reference Manual the following documentation atoms are used:

• ``catlist.tex''
• ``about.tex''
• ``terms.tex''
• ``concept.tex''
• ``archi.tex''
• ``files.tex''
• ``pi.tex''
• ``exten.tex''
• ``implemen.tex''
• ``diag.tex''
• ``ref.tex''
• ``xres.tex''
• ``bugs.tex''

These are both default configurations which can be overridden in the vmfile.mk by using the rules Docu-UserManual and Docu-ProgrammerManual.



They are required to create a manual of a specific type. If the rule is used without key parameters, the default configuration will be generated.

The key atoms can be used to create a specific documentation out of these atoms overriding any default. The key exclude can be used to remove some default atoms from the manual.

The documentation atoms and isotopes are included in the following ordering during manual creation.

1. The documentation atom.
2. Documentation isotopes associated to atom.
3. The extracted and automatically generated documentation of that atom.
4. The extracted and automatically generated documentation of these isotopes.

External figures created by the simple public domain drawing tool XFIG can be converted to PostScript[Smi96] for inclusion into the manuals by using the Docu-Figure.

Picture files already converted to PostScript with the extension ``eps'' for an Encapsulated PostScript Files need no explicit statements to be recognized by VMake if they are included by one of the macros:

• psfig{file}{caption}
  include the file formed by adding the extension ``eps'' to the file name as Encapsulated PostScript File into the document. The size of the picture is either natural or shrinked to maximum horizontal or vertical size.
• psfigsize{file}{vsize}{caption}
  Similar to psfig, but the pictures is shrinked/enlarged horizontally to the given size.

Figures are always centered horizontally and can be referenced by using the name of the first parameter file. The parameter caption is used to write an explanation below the figure which is also included in the table of figures at the beginning of the manual. All documentation is combined with the file inclusion mechanism into one LaTeX file and then automatically compiled by LaTeX to form a device independent output file. This file is converted to PostScript for printing. The LaTeX source file can be converted by public domain converter into HTML to allows an interactive browsing through the documentation using a WWW browser.