next up previous
Next: Paths, Files and Libraries Up: Reference Manaul Previous: Begin/End Blocks


Documentation Strings

We've mentioned a few times already the importance of clearly documenting your files and library files. For the most part, you can use comments in your files; but in library files we suggest you use the Doc directives.

In most cases, Docs are treated as Comments. However, if the -Dx18.1option is given on the command line, Docs are processed and printed to standard output.

For producing the MMA Standard Library Reference a trivial Python program is used to collate the output generated with a command like:

mma -Dx -w /usr/local/lib/mma/swing

Note, we added the '-w' option to suppress the printing of warning messages.

Important: All the text in documentation strings must be suitable for LATEX: this means that special symbols like ``#'', ``&'', etc. must be ``quoted'' with a preceding `` \''.

There are several Doc directives:

File
Usually contains the filename of the library file. At the present, this is not used by the documentation parser.

Example:
Doc File swing

Only one Doc File directive is permitted in a file.

Author
Usually contains the groove(y) author's name.. At the present, this is not used by the documentation parser.

Example:
Doc Author Bob van der Poel

Only one Doc Author directive is permitted in a file.

Note
Any number of Doc Note directives can appear in a file. The current documentation parser uses notes for section headers.

Example:
Doc Note This is a cool groove!

Defines
This directive is used to document the name and function of a Groove defined in the file. Any number of Doc Defines can appear in a file.

Example:
Doc Defines Swing1 The standard swing beat.

The use of this command is not recommended. It is much clearer and easier to add the a comment to a DefGroove ([*]).

A complete example:

Begin Doc

  File bigband

  Note For a standard tune which doesn't fit the Swing grooves.

  Begin Defines
    BigBand      2 bar seq, basic big band beat
    BigBandEnd   2 bar ending for BigBand
    BigBand1     basic big band with 1,3 bass, no walking
    BigBand1End  2 bar ending
    BigBand8     BigBand with 8 bar variation
    BigBand8End  4 bar ending
  End

  Author Bob van der Poel
End

A better example placing the ``Defines'' in the groove definitions:

Begin Doc

  File bigband

  Note For a standard tune which doesn't fit the Swing grooves.

  Author Bob van der Poel

End

... sequence stuff

DefGroove BigBand     A basic big band beat.

List a few of the included library files to get the idea.



Footnotes

...-Dx18.1
See the command summary ([*]).

next up previous
Next: Paths, Files and Libraries Up: Reference Manaul Previous: Begin/End Blocks
2004-04-19