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
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Documentation Tips</title>
<meta name="description" content="GNU Octave: Documentation Tips">
<meta name="keywords" content="GNU Octave: Documentation Tips">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Tips-and-Standards.html#Tips-and-Standards" rel="up" title="Tips and Standards">
<link href="Contributing-Guidelines.html#Contributing-Guidelines" rel="next" title="Contributing Guidelines">
<link href="Function-Headers.html#Function-Headers" rel="prev" title="Function Headers">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Documentation-Tips"></a>
<div class="header">
<p>
Previous: <a href="Function-Headers.html#Function-Headers" accesskey="p" rel="prev">Function Headers</a>, Up: <a href="Tips-and-Standards.html#Tips-and-Standards" accesskey="u" rel="up">Tips and Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Tips-for-Documentation-Strings"></a>
<h3 class="section">C.4 Tips for Documentation Strings</h3>
<p>As noted above, documentation is typically in a commented header block
on an Octave function following the copyright statement. The help string
shown above is an unformatted string and will be displayed as is by
Octave. Here are some tips for the writing of documentation strings.
</p>
<ul>
<li> Every command, function, or variable intended for users to know about
should have a documentation string.
</li><li> An internal variable or subroutine of an Octave program might as well have
a documentation string.
</li><li> The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary.
<p>The documentation string can have additional lines that expand on the
details of how to use the function or variable. The additional lines
should also be made up of complete sentences.
</p>
</li><li> For consistency, phrase the verb in the first sentence of a
documentation string as an infinitive with “to” omitted. For
instance, use “Return the frob of A and B.” in preference to “Returns
the frob of A and B.” Usually it looks good to do likewise for the
rest of the first paragraph. Subsequent paragraphs usually look better
if they have proper subjects.
</li><li> Write documentation strings in the active voice, not the passive, and in
the present tense, not the future. For instance, use “Return a list
containing A and B.” instead of “A list containing A and B will be
returned.”
</li><li> Avoid using the word “cause” (or its equivalents) unnecessarily.
Instead of, “Cause Octave to display text in boldface,” just write
“Display text in boldface.”
</li><li> Use two spaces between the period marking the end of a sentence and the
word which opens the next sentence. This convention has no effect for
typeset formats like TeX, but improves the readability of the documentation
in fixed-width environments such as the Info reader.
</li><li> Do not start or end a documentation string with whitespace.
</li><li> Format the documentation string so that it fits within an 80-column screen.
It is a good idea for most lines to be no wider than 60 characters.
<p>However, rather than simply filling the entire documentation string, you
can make it much more readable by choosing line breaks with care.
Use blank lines between topics if the documentation string is long.
</p>
</li><li> <strong>Do not</strong> indent subsequent lines of a documentation string so
that the text is lined up in the source code with the text of the first
line. This looks nice in the source code, but looks bizarre when users
view the documentation. Remember that the indentation before the
starting double-quote is not part of the string!
</li><li> When choosing variable names try to adhere to the following guidelines.
<dl compact="compact">
<dt>vectors :</dt>
<dd><p>x,y,z,t,w
</p>
</dd>
<dt>matrices :</dt>
<dd><p>A,B,M
</p>
</dd>
<dt>strings :</dt>
<dd><p>str,s
</p>
</dd>
<dt>filenames :</dt>
<dd><p>fname
</p>
</dd>
<dt>cells,cellstrs :</dt>
<dd><p>c,cstr
</p></dd>
</dl>
</li><li> The documentation string for a variable that is a yes-or-no flag should
start with words such as “Nonzero means…”, to make it clear that
all nonzero values are equivalent and indicate explicitly what zero and
nonzero mean.
</li><li> When a function’s documentation string mentions the value of an argument
of the function, use the argument name in capital letters as if it were
a name for that value. Thus, the documentation string of the operator
<code>/</code> refers to its second argument as ‘<samp>DIVISOR</samp>’, because the
actual argument name is <code>divisor</code>.
<p>Also use all caps for meta-syntactic variables, such as when you show
the decomposition of a list or vector into subunits, some of which may
vary.
</p></li></ul>
<p>Octave also allows extensive formatting of the help string of functions
using Texinfo. The effect on the online documentation is relatively
small, but makes the help string of functions conform to the help of
Octave’s own functions. However, the effect on the appearance of printed
or online documentation will be greatly improved.
</p>
<p>The fundamental building block of Texinfo documentation strings is the
Texinfo-macro <code>@deftypefn</code>, which takes three arguments: The class
the function is in, its output arguments, and the function’s
signature. Typical classes for functions include <code>Function File</code>
for standard Octave functions, and <code>Loadable Function</code> for
dynamically linked functions. A skeletal Texinfo documentation string
therefore looks like this
</p>
<div class="example">
<pre class="example">-*- texinfo -*-
@deftypefn {Function File} {@var{ret} =} fn (…)
@cindex index term
Help text in Texinfo format. Code samples should be marked
like @code{sample of code} and variables should be marked
as @var{variable}.
@seealso{fn2, fn3}
@end deftypefn
</pre></div>
<p>This help string must be commented in user functions, or in the help
string of the <code><span class="nolinebreak">DEFUN_DLD</span></code><!-- /@w --> macro for dynamically loadable
functions. The important aspects of the documentation string are
</p>
<dl compact="compact">
<dt>-*- texinfo -*-</dt>
<dd><p>This string signals Octave that the following text is in Texinfo format,
and should be the first part of any help string in Texinfo format.
</p>
</dd>
<dt>@deftypefn {class} … @end deftypefn</dt>
<dd><p>The entire help string should be enclosed within the block defined by
deftypefn.
</p>
</dd>
<dt>@cindex index term</dt>
<dd><p>This generates an index entry, and can be useful when the function is
included as part of a larger piece of documentation. It is ignored
within Octave’s help viewer. Only one index term may appear per line
but multiple @cindex lines are valid if the function should be
filed under different terms.
</p>
</dd>
<dt>@var{variable}</dt>
<dd><p>All variables should be marked with this macro. The markup of variables
is then changed appropriately for display.
</p>
</dd>
<dt>@code{sample of code}</dt>
<dd><p>All samples of code should be marked with this macro for the same
reasons as the @var macro.
</p>
</dd>
<dt>@qcode{"sample_code"}</dt>
<dt>@qcode{’sample_code’}</dt>
<dd><p>All samples of code which are quoted should use this more specialized macro.
This happens frequently when discussing graphics properties such as "position"
or options such as "on"/"off".
</p>
</dd>
<dt>@seealso{function2, function3}</dt>
<dd><p>This is a comma separated list of function names that allows cross
referencing from one function documentation string to another.
</p></dd>
</dl>
<p>Texinfo format has been designed to generate output for online viewing
with text terminals as well as generating high-quality printed output.
To these ends, Texinfo has commands which control the diversion of parts
of the document into a particular output processor. Three formats are
of importance: info, HTML, and TeX. These are selected with
</p>
<div class="example">
<pre class="example">@ifinfo
Text area for info only
@end ifinfo
</pre></div>
<div class="example">
<pre class="example">@ifhtml
Text area for HTML only
@end ifhtml
</pre></div>
<div class="example">
<pre class="example">@tex
Text area for TeX only
@end tex
</pre></div>
<p>Note that often TeX output can be used in HTML documents and so often
the <code>@ifhtml</code> blocks are unnecessary. If no specific output
processor is chosen, by default, the text goes into all output
processors. It is usual to have the above blocks in pairs to allow the
same information to be conveyed in all output formats, but with a
different markup. Currently, most Octave documentation only makes a
distinction between TeX and all other formats. Therefore, the
following construct is seen repeatedly.
</p>
<div class="example">
<pre class="example">@tex
text for TeX only
@end tex
@ifnottex
text for info, HTML, plaintext
@end ifnottex
</pre></div>
<p>Another important feature of Texinfo that is often used in Octave help
strings is the <code>@example</code> environment. An example of its use is
</p>
<div class="example">
<pre class="example">@example
@group
@code{2 * 2}
@result{} 4
@end group
@end example
</pre></div>
<p>which produces
</p>
<div class="example">
<pre class="example"><code>2 * 2</code>
⇒ 4
</pre></div>
<p>The <code>@group</code> block prevents the example from being split across a
page boundary, while the <code>@result{}</code> macro produces a right
arrow signifying the result of a command. If your example is larger than
20 lines it is better <em>NOT</em> to use grouping so that a reasonable page
boundary can be calculated.
</p>
<p>In many cases a function has multiple ways in which it can be called,
and the <code>@deftypefnx</code> macro can be used to give alternatives. For
example
</p>
<div class="example">
<pre class="example">-*- texinfo -*-
@deftypefn {Function File} {@var{a} =} fn (@var{x}, …)
@deftypefnx {Function File} {@var{a} =} fn (@var{y}, …)
Help text in Texinfo format.
@end deftypefn
</pre></div>
<p>Many complete examples of Texinfo documentation can be taken from the
help strings for the Octave functions themselves. A relatively complete
example of which is the <code>nchoosek</code> function. The Texinfo
documentation string for <code>nchoosek</code> is
</p>
<div class="example">
<pre class="example">-*- texinfo -*-
@deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k})
@deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k})
Compute the binomial coefficient or all combinations of a set of items.
If @var{n} is a scalar then calculate the binomial coefficient
of @var{n} and @var{k} which is defined as
@tex
$$
{n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
= {n! \over k! (n-k)!}
$$
@end tex
@ifnottex
@example
@group
/ \
| n | n (n-1) (n-2) @dots{} (n-k+1) n!
| | = ------------------------- = ---------
| k | k! k! (n-k)!
\ /
@end group
@end example
@end ifnottex
@noindent
This is the number of combinations of @var{n} items taken in groups of
size @var{k}.
If the first argument is a vector, @var{set}, then generate all
combinations of the elements of @var{set}, taken @var{k} at a time, with
one row per combination. The result @var{c} has @var{k} columns and
@w{@code{nchoosek (length (@var{set}), @var{k})}} rows.
For example:
How many ways can three items be grouped into pairs?
@example
@group
nchoosek (3, 2)
@result{} 3
@end group
@end example
What are the possible pairs?
@example
@group
nchoosek (1:3, 2)
@result{} 1 2
1 3
2 3
@end group
@end example
@code{nchoosek} works only for non-negative, integer arguments. Use
@code{bincoeff} for non-integer and negative scalar arguments, or for
computing many binomial coefficients at once with vector inputs
for @var{n} or @var{k}.
@seealso{bincoeff, perms}
@end deftypefn
</pre></div>
<p>which demonstrates most of the concepts discussed above.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Function-Headers.html#Function-Headers" accesskey="p" rel="prev">Function Headers</a>, Up: <a href="Tips-and-Standards.html#Tips-and-Standards" accesskey="u" rel="up">Tips and Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
