<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 2008 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Documentation Strings</TITLE>
<META NAME="description" CONTENT="Documentation Strings">
<META NAME="keywords" CONTENT="mma">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="mma.css">
<LINK REL="next" HREF="node27.html">
<LINK REL="previous" HREF="node25.html">
<LINK REL="up" HREF="mma.html">
<LINK REL="next" HREF="node27.html">
</HEAD>
<BODY bgcolor="#ffffff">
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html839"
HREF="node27.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html837"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html831"
HREF="node25.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html840"
HREF="node27.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html838"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html832"
HREF="node25.html">Begin/End Blocks</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL CLASS="ChildLinks">
<LI><A NAME="tex2html841"
HREF="node26.html#SECTION002610000000000000000">Doc</A>
<LI><A NAME="tex2html842"
HREF="node26.html#SECTION002620000000000000000">Author</A>
<LI><A NAME="tex2html843"
HREF="node26.html#SECTION002630000000000000000">DocVar</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION002600000000000000000">
Documentation Strings</A>
</H1>
<P>
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
D<SMALL>OC</SMALL> directive.
<P>
In addition to the commands listed in this chapter, you should also
note <A HREF="node6.html#sec-grooves">D<SMALL>EF</SMALL>G<SMALL>ROOVES</SMALL></A>).
<P>
For some real-life examples of how to document your library files,
look at any of the library files supplied with this distribution.
<P>
<H1><A NAME="SECTION002610000000000000000"></A> <A NAME="sec-docs"></A>
<BR>
Doc
</H1>
<P>
A D<SMALL>OC</SMALL> command is pretty simple:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Doc This is a documentation string! </B>
</td></tr>
</Table>
<P>
In most cases, D<SMALL>OC</SMALL>s are treated as C<SMALL>OMMENT</SMALL>s. However,
if the <SPAN CLASS="textit">-Dx</SPAN><A NAME="tex2html97"
HREF="#foot13990"><SUP><SPAN CLASS="arabic">26</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> option is given
on the command line, D<SMALL>OC</SMALL>s are processed and printed to standard
output.
<P>
For producing the <SPAN CLASS="textit">
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> Standard Library Reference</SPAN> a trivial
Python program is used to collate the output generated with a command
like:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>$ mma -Dxl -w /usr/local/lib/mma/swing </B>
</td></tr>
</Table>
<P>
Note, the '-w' option has been used to suppress the printing of warning
messages.
<P>
All D<SMALL>OC</SMALL> 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).
<P>
<H1><A NAME="SECTION002620000000000000000">
Author</A>
</H1>
<P>
As part of the documentation package, there is a A<SMALL>UTHOR</SMALL>
command:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Author Bob van der Poel </B>
</td></tr>
</Table>
<P>
Currently A<SMALL>UTHOR</SMALL> 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.
<P>
<H1><A NAME="SECTION002630000000000000000">
DocVar</A>
</H1>
<P>
If any variables are used to change the behavior of a library file
they should be documented with a D<SMALL>OC</SMALL>V<SMALL>AR</SMALL> 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.
<P>
Assuming that you are using the
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> variable $C<SMALL>HORD</SMALL>V<SMALL>OICE</SMALL> as
an optional voice setting in your file, you might have the following
in a library file:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Begin DocVar
<BR>
ChordVoice Voice used in Chord tracks (defaults to Piano2).
<BR>
End
<BR>
<BR>
If NDef ChordVoice
<BR>
Set ChordVoice Piano2
<BR>
Endif </B>
</td></tr>
</Table>
<P>
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 S<SMALL>HOW</SMALL>V<SMALL>ARS</SMALL> to the end of the library file and
compile. Then document the variables and remove the S<SMALL>HOW</SMALL>V<SMALL>ARS</SMALL>.
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot13990">...-Dx</A><A
HREF="node26.html#tex2html97"><SUP><SPAN CLASS="arabic">26</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
<DD>See the <A HREF="node2.html#cmd-summary">command
summary</A>.
</DD>
</DL>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html839"
HREF="node27.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html837"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html831"
HREF="node25.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html840"
HREF="node27.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html838"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html832"
HREF="node25.html">Begin/End Blocks</A></DIV>
<!--End of Navigation Panel-->
<ADDRESS>
bob
2010-11-07
</ADDRESS>
</BODY>
</HTML>