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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
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 NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="mma.css">
<LINK REL="next" HREF="node20.html">
<LINK REL="previous" HREF="node18.html">
<LINK REL="up" HREF="mma.html">
<LINK REL="next" HREF="node20.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html578"
HREF="node20.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="file:/usr/lib/latex2html/icons/next.png"></A>
<A NAME="tex2html576"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="file:/usr/lib/latex2html/icons/up.png"></A>
<A NAME="tex2html570"
HREF="node18.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="file:/usr/lib/latex2html/icons/prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html579"
HREF="node20.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html577"
HREF="mma.html">Reference Manaul</A>
<B> Previous:</B> <A NAME="tex2html571"
HREF="node18.html">Begin/End Blocks</A>
<BR>
<BR>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html580"
HREF="node19.html#SECTION001910000000000000000">Doc</A>
<LI><A NAME="tex2html581"
HREF="node19.html#SECTION001920000000000000000">Author</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION001900000000000000000">
Documentation Strings</A>
</H1>
<P>
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 <I>Doc</I> directive.
<P>
In addition to the commands listed in this chapter, you should also note the <I>DefGroove</I> section (<A HREF="node6.html#sec-grooves"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="file:/usr/lib/latex2html/icons/crossref.png"></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="SECTION001910000000000000000"></A> <A NAME="sec-docs"></A>
<BR>
Doc
</H1>
<P>
A <I>Doc</I> command is pretty simple:
<P>
<TABLE CELLSPACING=0 CELLPADDING=5" BGCOLOR="OldLace" BORDER=3><TR> <TD>
<BLOCKQUOTE><B>Doc This is a documentation string! </B></BLOCKQUOTE>
</TD></TR></TABLE>
<P>
In most cases, <I>Doc</I>s are treated as <I>Comments</I>. However, if the <B>-Dx</B><A NAME="tex2html64"
HREF="#foot7500"><SUP>19.1</SUP></A> option is given on the command line, <I>Doc</I>s are processed and printed to standard output.
<P>
For producing the <B><I><B>MMA</B></I> Standard Library Reference</B> a trivial Python program is used to collate the output generated with a command like:
<P>
<TABLE CELLSPACING=0 CELLPADDING=5" BGCOLOR="OldLace" BORDER=3><TR> <TD>
<BLOCKQUOTE><B>mma -Dx -w /usr/local/lib/mma/swing </B></BLOCKQUOTE>
</TD></TR></TABLE>
<P>
Note, we added the '-w' option to suppress the printing of warning messages.
<P>
<H1><A NAME="SECTION001920000000000000000">
Author</A>
</H1>
<P>
As part of the documentation package, there is a <I>Author</I> command:
<P>
<TABLE CELLSPACING=0 CELLPADDING=5" BGCOLOR="OldLace" BORDER=3><TR> <TD>
<BLOCKQUOTE><B>Author Bob van der Poel </B></BLOCKQUOTE>
</TD></TR></TABLE>
<P>
Currently <I>Author</I> 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 your write.
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot7500">...-Dx</A><A
HREF="node19.html#tex2html64"><SUP>19.1</SUP></A></DT>
<DD>See the command summary (<A HREF="node2.html#cmd-summary"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="file:/usr/lib/latex2html/icons/crossref.png"></A>).
</DD>
</DL><HR>
<!--Navigation Panel-->
<A NAME="tex2html578"
HREF="node20.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="file:/usr/lib/latex2html/icons/next.png"></A>
<A NAME="tex2html576"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="file:/usr/lib/latex2html/icons/up.png"></A>
<A NAME="tex2html570"
HREF="node18.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="file:/usr/lib/latex2html/icons/prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html579"
HREF="node20.html">Paths, Files and Libraries</A>
<B> Up:</B> <A NAME="tex2html577"
HREF="mma.html">Reference Manaul</A>
<B> Previous:</B> <A NAME="tex2html571"
HREF="node18.html">Begin/End Blocks</A>
<!--End of Navigation Panel-->
<ADDRESS>
Bob
2004-12-02
</ADDRESS>
</BODY>
</HTML>
|
