Table of Contents

Name

doc - documentation format for miriad

Description

Each MIRIAD/NEMO program using the online help feature in their respective shells (such as miriad and mirtool) has a simple ASCII file in $MIRPDOC (for NEMO: $NEMODOC) with the name program.doc. In addition a cdoc is used to document shell scripts.

This file contains the text displayed with the help command in miriad or when online help is requested in mirtool with a context sensitive mouse button click.

Within the various packages that use the doc(5MIR) format, special programs exist that extract the doc-file from the source code doc(1MIR) , or the executable mkpdoc(8NEMO)

Format

Format of .doc files associated with tasks; or of .sdoc files for routines:
%N taskname [%F filename]
multi-line program description
%D one-line description (note: maximum length is 65 characters)
%P person responsible for maintaining the task
%: section(s) in systematic list of tasks
%A keyword
multi-line keyword description
[%B
multi-line description block]
 > The %A and %B directives may be repeated many times
 > in multi-line description blocks lines may start with <TAB> or ’ ’
 > they must not pass column 72
 > Descriptions may contain any character. Characters special to (La)TeX
 > ($&%#{}_~^|<>) (but not ) are escaped; " is changed into ‘‘ and ’’.
 > If character 1 and 2 are ’ ’ or <TAB> line is set in (La)TeX’s verbatim mode.

FORMAT FOR .for, .f AND .c FILES:

Within MIRIAD programs, it is common to include directives for doc(1MIR) to extract a .doc file. The format for this is:
  c= [module name] [one-line description] for tasks
  c* [module name] [filename] [one-line description] for subroutines
  c& person responsible for maintaining the routine
  c: comma separated list of keywords pertaining to the routine
  c+ this starts a multi-line documentation block.
  [c@ keyword
  multi-line keyword description]
  [c< keyword]
  c-- this ends a multi-line documentation block.
> The documentation block between c+ and c-- may contain any character,
> except that the tilde (~) cannot be used inside a verbatim block
> Lines with descriptions should not pass column 72
> The flag character ’c’ may also be ’C’ or ’ (the latter for .c files)
> In case the extension-override option -e was used, directives should
> start with # or $!
> Descriptions may contain any character. Characters special to (La)TeX
> ($&%#{}_~^|<>) (but not ) are escaped; " is changed into ‘‘ and ’’.
> If character 1 and 2 are ’ ’ or <TAB> line is set in (La)TeX’s verbatim mode.

See Also

mkpdoc(8NEMO) , mknemo(8NEMO) , doc(1MIR)

Author

Bart Wakker, Peter Teuben

Update History


21-jun-91    doc created      PJT
13-oct-91    more documentation - made it MIR ownership    PJT


Table of Contents