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:
Example:
Doc File swing |
Only one Doc File directive is permitted in a file.
Example:
Doc Author Bob van der Poel |
Only one Doc Author directive is permitted in a file.
Example:
Doc Note This is a cool groove! |
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 |
A better example placing the ``Defines'' in the groove definitions:
Begin Doc |
List a few of the included library files to get the idea.