24
File: octave.info, Node: Documentation Tips, Prev: Function Headers, Up: Tips
26
C.5 Tips for Documentation Strings
27
==================================
29
As noted above, documentation is typically in a commented header block
30
on an Octave function following the copyright statement. The help string
31
shown above is an unformatted string and will be displayed as is by
32
Octave. Here are some tips for the writing of documentation strings.
34
* Every command, function, or variable intended for users to know
35
about should have a documentation string.
37
* An internal variable or subroutine of an Octave program might as
38
well have a documentation string.
40
* The first line of the documentation string should consist of one
41
or two complete sentences that stand on their own as a summary.
43
The documentation string can have additional lines that expand on
44
the details of how to use the function or variable. The
45
additional lines should also be made up of complete sentences.
47
* For consistency, phrase the verb in the first sentence of a
48
documentation string as an infinitive with "to" omitted. For
49
instance, use "Return the frob of A and B." in preference to
50
"Returns the frob of A and B." Usually it looks good to do
51
likewise for the rest of the first paragraph. Subsequent
52
paragraphs usually look better if they have proper subjects.
54
* Write documentation strings in the active voice, not the passive,
55
and in the present tense, not the future. For instance, use
56
"Return a list containing A and B." instead of "A list containing
57
A and B will be returned."
59
* Avoid using the word "cause" (or its equivalents) unnecessarily.
60
Instead of, "Cause Octave to display text in boldface," write just
61
"Display text in boldface."
63
* Do not start or end a documentation string with whitespace.
65
* Format the documentation string so that it fits in an Emacs window
66
on an 80-column screen. It is a good idea for most lines to be no
67
wider than 60 characters.
69
However, rather than simply filling the entire documentation
70
string, you can make it much more readable by choosing line breaks
71
with care. Use blank lines between topics if the documentation
74
* *Do not* indent subsequent lines of a documentation string so that
75
the text is lined up in the source code with the text of the first
76
line. This looks nice in the source code, but looks bizarre when
77
users view the documentation. Remember that the indentation
78
before the starting double-quote is not part of the string!
80
* The documentation string for a variable that is a yes-or-no flag
81
should start with words such as "Nonzero means...", to make it
82
clear that all nonzero values are equivalent and indicate
83
explicitly what zero and nonzero mean.
85
* When a function's documentation string mentions the value of an
86
argument of the function, use the argument name in capital letters
87
as if it were a name for that value. Thus, the documentation
88
string of the operator `/' refers to its second argument as
89
`DIVISOR', because the actual argument name is `divisor'.
91
Also use all caps for meta-syntactic variables, such as when you
92
show the decomposition of a list or vector into subunits, some of
95
Octave also allows extensive formatting of the help string of
96
functions using Texinfo. The effect on the online documentation is
97
relatively small, but makes the help string of functions conform to the
98
help of Octave's own functions. However, the effect on the appearance
99
of printed or online documentation will be greatly improved.
101
The fundamental building block of Texinfo documentation strings is
102
the Texinfo-macro `@deftypefn', which takes three arguments: The class
103
the function is in, its output arguments, and the function's signature.
104
Typical classes for functions include `Function File' for standard
105
Octave functions, and `Loadable Function' for dynamically linked
106
functions. A skeletal Texinfo documentation string therefore looks
110
@deftypefn{Function File} {@var{ret} = } fn (...)
112
Help text in Texinfo format. Code samples should be marked
113
like @code{sample of code} and variables should be marked
118
This help string must be commented in user functions, or in the help
119
string of the `DEFUN_DLD' macro for dynamically loadable functions.
120
The important aspects of the documentation string are
123
This string signals Octave that the follow text is in Texinfo
124
format, and should be the first part of any help string in Texinfo
127
@deftypefn{class} ... @end deftypefn
128
The entire help string should be enclosed within the block defined
132
This generates an index entry, and can be useful when the function
133
is included as part of a larger piece of documentation. It is
134
ignored within Octave's help viewer.
137
All variables should be marked with this macro. The markup of
138
variables is then changed appropriately for display.
140
@code{sample of code}
141
All samples of code should be marked with this macro for the same
142
reasons as the @var macro.
145
This is a comma separated list of function names that allows cross
146
referencing from one function documentation string to another.
148
Texinfo format has been designed to generate output for online
149
viewing with text-terminals as well as generating high-quality printed
150
output. To these ends, Texinfo has commands which control the
151
diversion of parts of the document into a particular output processor.
152
Three formats are of importance: info, html and TeX. These are
156
Text area for info only
160
Text area for html only
169
Note that often TeX output can be used in html documents and so often
170
the `@ifhtml' blocks are unnecessary. If no specific output processor
171
is chosen, by default, the text goes into all output processors. It is
172
usual to have the above blocks in pairs to allow the same information
173
to be conveyed in all output formats, but with a different markup.
175
Another important feature of Texinfo that is often used in Octave
176
help strings is the `@example' environment. An example of its use is
190
The `@group' block prevents the example from being split across a
191
page boundary, while the `@result{}' macro produces a right arrow
192
signifying the result of a command.
194
In many cases a function has multiple means in which it can be
195
called, and the `@deftypefnx' macro can be used to give alternatives.
199
@deftypefn{Function File} {@var{a} = } fn (@var{x}, ...)
200
@deftypefnx{Function File} {@var{a} = } fn (@var{y}, ...)
201
Help text in Texinfo format.
204
Many complete examples of Texinfo documentation can be taken from the
205
help strings for the Octave functions themselves. A relatively complete
206
example of which is the `nchoosek' function. The Texinfo documentation
207
string of `nchoosek' is
210
@deftypefn {Function File} {} nchoosek (@var{n}, @var{k})
212
Compute the binomial coefficient or all combinations of
213
@var{n}. If @var{n} is a scalar then, calculate the
214
binomial coefficient of @var{n} and @var{k}, defined as
219
{n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
228
| n | n (n-1) (n-2) ... (n-k+1)
229
| | = -------------------------
236
If @var{n} is a vector, this generates all combinations
237
of the elements of @var{n}, taken @var{k} at a time,
238
one row per combination. The resulting @var{c} has size
239
@code{[nchoosek (length (@var{n}),@var{k}), @var{k}]}.
244
which demonstrates most of the concepts discussed above.
247
File: octave.info, Node: Trouble, Next: Installation, Prev: Tips, Up: Top
249
Appendix D Known Causes of Trouble
250
**********************************
252
This section describes known problems that affect users of Octave.
253
Most of these are not Octave bugs per se--if they were, we would fix
254
them. But the result for a user may be like the result of a bug.
256
Some of these problems are due to bugs in other software, some are
257
missing features that are too much work to add, and some are places
258
where people's opinions differ as to what is best.
262
* Actual Bugs:: Bugs we will fix later.
271
File: octave.info, Node: Actual Bugs, Next: Reporting Bugs, Up: Trouble
273
D.1 Actual Bugs We Haven't Fixed Yet
274
====================================
276
* Output that comes directly from Fortran functions is not sent
277
through the pager and may appear out of sequence with other output
278
that is sent through the pager. One way to avoid this is to force
279
pending output to be flushed before calling a function that will
280
produce output from within Fortran functions. To do this, use the
285
Another possible workaround is to use the command
287
page_screen_output = "false"
289
to turn the pager off.
291
A list of ideas for future enhancements is distributed with Octave.
292
See the file `PROJECTS' in the top level directory in the source
296
File: octave.info, Node: Reporting Bugs, Next: Bug Criteria, Prev: Actual Bugs, Up: Trouble
301
Your bug reports play an essential role in making Octave reliable.
303
When you encounter a problem, the first thing to do is to see if it
304
is already known. *Note Trouble::. If it isn't known, then you should
307
Reporting a bug may help you by bringing a solution to your problem,
308
or it may not. In any case, the principal function of a bug report is
309
to help the entire community by making the next version of Octave work
310
better. Bug reports are your contribution to the maintenance of Octave.
312
In order for a bug report to serve its purpose, you must include the
313
information that makes it possible to fix the bug.
315
If you have Octave working at all, the easiest way to prepare a
316
complete bug report is to use the Octave function `bug_report'. When
317
you execute this function, Octave will prompt you for a subject and then
318
invoke the editor on a file that already contains all the configuration
319
information. When you exit the editor, Octave will mail the bug report
322
-- Function File: bug_report ()
323
Have Octave create a bug report template file, invoke your favorite
324
editor, and submit the report to the bug-octave mailing list when
325
you are finished editing.
330
* Where: Bug Lists. Where to send your bug report.
331
* Reporting: Bug Reporting. How to report a bug effectively.
332
* Patches: Sending Patches. How to send a patch for Octave.
335
File: octave.info, Node: Bug Criteria, Next: Bug Lists, Prev: Reporting Bugs, Up: Trouble
337
D.3 Have You Found a Bug?
338
=========================
340
If you are not sure whether you have found a bug, here are some
343
* If Octave gets a fatal signal, for any input whatever, that is a
344
bug. Reliable interpreters never crash.
346
* If Octave produces incorrect results, for any input whatever, that
349
* Some output may appear to be incorrect when it is in fact due to a
350
program whose behavior is undefined, which happened by chance to
351
give the desired results on another system. For example, the
352
range operator may produce different results because of
353
differences in the way floating point arithmetic is handled on
356
* If Octave produces an error message for valid input, that is a bug.
358
* If Octave does not produce an error message for invalid input,
359
that is a bug. However, you should note that your idea of
360
"invalid input" might be my idea of "an extension" or "support for
361
traditional practice".
363
* If you are an experienced user of programs like Octave, your
364
suggestions for improvement are welcome in any case.
367
File: octave.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Trouble
369
D.4 Where to Report Bugs
370
========================
372
If you have Octave working at all, the easiest way to prepare a complete
373
bug report is to use the Octave function `bug_report'. When you
374
execute this function, Octave will prompt you for a subject and then
375
invoke the editor on a file that already contains all the configuration
376
information. When you exit the editor, Octave will mail the bug report
379
If for some reason you cannot use Octave's `bug_report' function,
380
send bug reports for Octave to <bug@octave.org>.
382
*Do not send bug reports to `help-octave'*. Most users of Octave do
383
not want to receive bug reports. Those that do have asked to be on the
386
As a last resort, send bug reports on paper to:
388
Octave Bugs c/o John W. Eaton
389
University of Wisconsin-Madison
390
Department of Chemical Engineering
391
1415 Engineering Drive
392
Madison, Wisconsin 53706 USA
395
File: octave.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Trouble
397
D.5 How to Report Bugs
398
======================
400
Send bug reports for Octave to one of the addresses listed in *note Bug
403
The fundamental principle of reporting bugs usefully is this:
404
*report all the facts*. If you are not sure whether to state a fact or
405
leave it out, state it!
407
Often people omit facts because they think they know what causes the
408
problem and they conclude that some details don't matter. Thus, you
409
might assume that the name of the variable you use in an example does
410
not matter. Well, probably it doesn't, but one cannot be sure.
411
Perhaps the bug is a stray memory reference which happens to fetch from
412
the location where that name is stored in memory; perhaps, if the name
413
were different, the contents of that location would fool the
414
interpreter into doing the right thing despite the bug. Play it safe
415
and give a specific, complete example.
417
Keep in mind that the purpose of a bug report is to enable someone to
418
fix the bug if it is not known. Always write your bug reports on the
419
assumption that the bug is not known.
421
Sometimes people give a few sketchy facts and ask, "Does this ring a
422
bell?" This cannot help us fix a bug. It is better to send a complete
423
bug report to begin with.
425
Try to make your bug report self-contained. If we have to ask you
426
for more information, it is best if you include all the previous
427
information in your response, as well as the information that was
430
To enable someone to investigate the bug, you should include all
433
* The version of Octave. You can get this by noting the version
434
number that is printed when Octave starts, or running it with the
437
* A complete input file that will reproduce the bug.
439
A single statement may not be enough of an example--the bug might
440
depend on other details that are missing from the single statement
441
where the error finally occurs.
443
* The command arguments you gave Octave to execute that example and
444
observe the bug. To guarantee you won't omit something important,
445
list all the options.
447
If we were to try to guess the arguments, we would probably guess
448
wrong and then we would not encounter the bug.
450
* The type of machine you are using, and the operating system name
453
* The command-line arguments you gave to the `configure' command when
454
you installed the interpreter.
456
* A complete list of any modifications you have made to the
459
Be precise about these changes--show a context diff for them.
461
* Details of any other deviations from the standard procedure for
464
* A description of what behavior you observe that you believe is
465
incorrect. For example, "The interpreter gets a fatal signal,"
466
or, "The output produced at line 208 is incorrect."
468
Of course, if the bug is that the interpreter gets a fatal signal,
469
then one can't miss it. But if the bug is incorrect output, we
470
might not notice unless it is glaringly wrong.
472
Even if the problem you experience is a fatal signal, you should
473
still say so explicitly. Suppose something strange is going on,
474
such as, your copy of the interpreter is out of synch, or you have
475
encountered a bug in the C library on your system. Your copy
476
might crash and the copy here would not. If you said to expect a
477
crash, then when the interpreter here fails to crash, we would
478
know that the bug was not happening. If you don't say to expect a
479
crash, then we would not know whether the bug was happening. We
480
would not be able to draw any conclusion from our observations.
482
Often the observed symptom is incorrect output when your program
483
is run. Unfortunately, this is not enough information unless the
484
program is short and simple. It is very helpful if you can
485
include an explanation of the expected output, and why the actual
488
* If you wish to suggest changes to the Octave source, send them as
489
context diffs. If you even discuss something in the Octave source,
490
refer to it by context, not by line number, because the line
491
numbers in the development sources probably won't match those in
494
Here are some things that are not necessary:
496
* A description of the envelope of the bug.
498
Often people who encounter a bug spend a lot of time investigating
499
which changes to the input file will make the bug go away and
500
which changes will not affect it. Such information is usually not
501
necessary to enable us to fix bugs in Octave, but if you can find
502
a simpler example to report _instead_ of the original one, that is
503
a convenience. Errors in the output will be easier to spot,
504
running under the debugger will take less time, etc. Most Octave
505
bugs involve just one function, so the most straightforward way to
506
simplify an example is to delete all the function definitions
507
except the one in which the bug occurs.
509
However, simplification is not vital; if you don't want to do
510
this, report the bug anyway and send the entire test case you used.
512
* A patch for the bug. Patches can be helpful, but if you find a
513
bug, you should report it, even if you cannot send a fix for the
24
517
File: octave.info, Node: Sending Patches, Next: Service, Prev: Bug Reporting, Up: Trouble
26
519
D.6 Sending Patches for Octave
added
removed
doc/interpreter/octave.info-5
