Next: Paths, Files and Libraries Up: Reference Manual Previous: Begin/End Blocks
It has been 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 you use the DOC directive.
In addition to the commands listed in this chapter, you should also note DEFGROOVES).
For some real-life examples of how to document your library files, look at any of the library files supplied with this distribution.
A DOC command is pretty simple:
| Doc This is a documentation string! |
In most cases, DOCs are treated as COMMENTs. However, if the -Dx32.1 option 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 -Dxl -w /usr/local/lib/mma/swing |
Note, the '-w' option has been used to suppress the printing of warning messages.
All DOC lines/strings are concatenated into one long paragraph. If you want any line breaks they should be indicated with a “<P>”. In LATEX this is converted to a new line; in html it is left as is (forcing a new line as well).
As part of the documentation package, there is a AUTHOR command:
| Author Bob van der Poel |
Currently AUTHOR lines are processed and the data is saved, but never used. It may be used in a future library documentation procedures, so you should use it in any library files you write.
If any variables are used to change the behavior of a library file they should be documented with a DOCVAR command. Normally these lines are treated as comments, but when processing with the -Dxl or -Dxh command line options the data is parsed and written to the output documentation files.
Assuming that you are using the MMA variable $CHORDVOICE as an optional voice setting in your file, you might have the following in a library file:
|
Begin DocVar
ChordVoice Voice used in Chord tracks (defaults to Piano2). End If NDef ChordVoice Set ChordVoice Piano2 Endif |
All variables used in the library file should be documented. You should list the user variables first, and then any variables internal to the library file. To double check to see what variables are used you can add a SHOWVARS to the end of the library file and compile. Then document the variables and remove the SHOWVARS.