1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<!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="node32.html">
<LINK REL="previous" HREF="node30.html">
<LINK REL="up" HREF="mma.html">
<LINK REL="next" HREF="node32.html">
</HEAD>
<BODY bgcolor="#ffffff">
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html984"
HREF="node32.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html982"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html976"
HREF="node30.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html985"
HREF="node32.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html983"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html977"
HREF="node30.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="tex2html986"
HREF="node31.html#SECTION003110000000000000000">Doc</A>
<LI><A NAME="tex2html987"
HREF="node31.html#SECTION003120000000000000000">Author</A>
<LI><A NAME="tex2html988"
HREF="node31.html#SECTION003130000000000000000">DocVar</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION003100000000000000000">
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="SECTION003110000000000000000"></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="tex2html125"
HREF="#foot18702"><SUP><SPAN CLASS="arabic">31</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="SECTION003120000000000000000">
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="SECTION003130000000000000000">
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="foot18702">...-Dx</A><A
HREF="node31.html#tex2html125"><SUP><SPAN CLASS="arabic">31</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="tex2html984"
HREF="node32.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html982"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html976"
HREF="node30.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html985"
HREF="node32.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html983"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html977"
HREF="node30.html">Begin/End Blocks</A></DIV>
<!--End of Navigation Panel-->
<ADDRESS>
Bob van der Poel
2016-06-11
</ADDRESS>
</BODY>
</HTML>
|
