next up previous contents index
Next: Document a macro Up: Documentation Previous: Documentation   Contents   Index


Document a module

Each module you write must be documented. MegaWave2 helps you as much as possible in this unattractive task: when you compile a module, a document skeleton is generated in the directory $MEGAWAVE2/doc/obj/ (or $MY_MEGAWAVE2/doc/obj/). It takes the name of the module and the extension .doc. This file documents in the LATEX language about everything that could be automatically done, as the synopsis of the run-time command, the summary of the module function, the release number and the copyright for the authors and laboratories.

(Un)Fortunately, there will always be a part of the documentation which cannot be automatically generated: the mathematical description of the algorithm. This part is the Description field of the documentation. Therefore, the author of a new module must write this content in a file into the $MEGAWAVE2/doc/src/ (administrator only) or $MY_MEGAWAVE2/doc/src/ (plain user) directory. Give this file the name of the module with the extension .tex. As the file will be inserted by MegaWave2 into the whole documentation, you must write the text using a subset of the LATEX language. In particular, don't use any commands about the style or the presentation (as \begin{document}, \documentstyle, \newpage, \section, ...).

You can get a lot of examples of such documents by seeking the files into subdirectories of $MEGAWAVE2/doc/src.

Since MegaWave2 V 2.21, the system uses bibliographic databases where all citations are recorded. As this allows cross-references, it is now possible to get all modules associated to a given article. In order to fulfill the new requirements, citations have to be set in the .tex file using the standard \cite LATEX command, and the corresponding references have to be given in the bibliographic database (.bib file), NO MORE in the .tex file. Beware, do not collapse citations : use e.g. \cite{key1}\cite{key2} instead of \cite{key1,key2}. References for private modules have to be put in $MY_MEGAWAVE2/doc/private.bib while references for public modules are in $MEGAWAVE2/doc/public.bib. Of course, only references for private modules not in public.bib have to be in private.bib. See the system macro mwmodbibtex for more information about the bibliographic database.


next up previous contents index
Next: Document a macro Up: Documentation Previous: Documentation   Contents   Index
mw 2004-05-05