1,847
edits
Carandraug (talk | contribs) (→TexInfo: add section for line limit of examples (from the removed manual section on contribution guidelines)) |
(→Ellipsis (...): Update deftypefn to current standards.) |
||
(6 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
== Guidelines == | |||
The first line of the documentation string should consist of a summary of | |||
the function. | |||
Subsequent lines may expand the general nature of the function. | |||
After the introduction there should be paragraphs describing the meaning | |||
and usage of each input, followed by the meaning and usage of each output. | |||
Finally, there may be more general information such as notes about the | |||
algorithm used, references to scientific papers, notes about any | |||
incompatibilities with Matlab, etc. | |||
=== First sentence === | |||
The first sentence of help text should start with a statement that is like a command. For example, the first sentence of {{Codeline|hist}}: | The first sentence of help text should start with a statement that is like a command. For example, the first sentence of {{Codeline|hist}}: | ||
<pre> | <pre> | ||
Line 10: | Line 22: | ||
</pre> | </pre> | ||
== Manual reference == | Usually it looks good to do likewise for the rest of the first paragraph. | ||
Subsequent paragraphs usually look better if they have proper subjects. | |||
=== Voice === | |||
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." | |||
Avoid using the word "cause" (or its equivalents) unnecessarily. | |||
Instead of, "Cause Octave to display text in boldface," just write | |||
"Display text in boldface." | |||
=== Wording === | |||
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. | |||
=== Whitespace === | |||
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. | |||
<pre> | |||
there is no correct for sentence spacing. But we need a convention # good | |||
there is no correct for sentence spacing. But we need a convention # bad | |||
</pre> | |||
Do not start or end a documentation string with whitespace. | |||
Do not 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! | |||
=== Line length === | |||
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. | |||
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. | |||
=== Variable naming === | |||
When choosing variable names try to adhere to the following guidelines. | |||
{| class="wikitable" | |||
! Variable type | |||
! Standard names | |||
|- | |||
|vectors | |||
|x,y,z,t,w | |||
|- | |||
|matrices | |||
|A,B,M | |||
|- | |||
|strings | |||
|str, s | |||
|- | |||
|filename | |||
|fname | |||
|- | |||
|cells | |||
|c | |||
|- | |||
|cellstrs | |||
|cstr | |||
|} | |||
=== Manual reference === | |||
When submitting a function to Octave, a tag for the docstring should be added to some appropriate place in one of the manual's .txi source files (they are all in {{Path|doc/interpreter/}}). Find the most appropriate section in the manual and add the following with the related functions: | When submitting a function to Octave, a tag for the docstring should be added to some appropriate place in one of the manual's .txi source files (they are all in {{Path|doc/interpreter/}}). Find the most appropriate section in the manual and add the following with the related functions: | ||
{{Code|adding tag for function help text in Octave's manual|<pre> | {{Code|adding tag for function help text in Octave's manual|<pre> | ||
Line 18: | Line 108: | ||
If appropriate, also write some text about the function on the manual for better inclusion into the manual. | If appropriate, also write some text about the function on the manual for better inclusion into the manual. | ||
= TexInfo = | == TexInfo == | ||
This is the preferred format for help text. There is also a comprehensive [ | This is the preferred format for help text. There is also a comprehensive [https://www.gnu.org/software/texinfo/manual/texinfo/ TexInfo manual]. | ||
== Examples == | === Examples === | ||
If you give a code example in the documentation written in Texinfo with | If you give a code example in the documentation written in Texinfo with | ||
Line 36: | Line 120: | ||
ps documents. That means, keep the lines of examples under 60 characters. | ps documents. That means, keep the lines of examples under 60 characters. | ||
== Octave specific macros == | === Octave specific macros === | ||
=== seealso === | ==== seealso ==== | ||
Do not use this macro empty as it will create problems with the {{forge|generate_html}} package. | Do not use this macro empty as it will create problems with the {{forge|generate_html}} package. | ||
=== deftypefn === | ==== deftypefn ==== | ||
This environment will enclose the function help text. It takes as argument the type of function. Typical values are | This environment will enclose the function help text. It takes as argument the type of function. Typical values are | ||
* Function File -- for functions in .m files | * Function File -- for functions in .m files | ||
Line 48: | Line 132: | ||
Besides this environment there is also the alternative {{Codeline|deftypenx}} for alternative forms. Typically these are mentioned at the top of the help text, right after the {{Codeline|deftypen}} although this is not really necessary. Cases where it's acceptable to have them on other sections would be methods on the help text of a class constructor, since they will not always be on a separate file. | Besides this environment there is also the alternative {{Codeline|deftypenx}} for alternative forms. Typically these are mentioned at the top of the help text, right after the {{Codeline|deftypen}} although this is not really necessary. Cases where it's acceptable to have them on other sections would be methods on the help text of a class constructor, since they will not always be on a separate file. | ||
== Formatting == | === Formatting === | ||
=== Formulas === | ==== Formulas ==== | ||
Do not use the example environment to insert formulas, consider using {{Codeline|@verbatim}} instead. | Do not use the example environment to insert formulas, consider using {{Codeline|@verbatim}} instead. | ||
Line 77: | Line 161: | ||
</pre>}} | </pre>}} | ||
=== Plain-tex missing macros === | ==== Plain-tex missing macros ==== | ||
When compared to LaTeX, plain TeX is missing some very useful macros for including mathematical notation. The following is a list of their definitions which can be added on a as needed basis: | When compared to LaTeX, plain TeX is missing some very useful macros for including mathematical notation. The following is a list of their definitions which can be added on a as needed basis: | ||
Line 83: | Line 167: | ||
<pre>\def\frac#1#2{{\begingroup#1\endgroup\over#2}}</pre> | <pre>\def\frac#1#2{{\begingroup#1\endgroup\over#2}}</pre> | ||
== Special inserts == | === Special inserts === | ||
=== Escape characters === | ==== Escape characters ==== | ||
To escape characters in TexInfo, use the character {{Codeline|@}}. Only the characters '''@''', '''{''' and '''}''' need to be escaped. | To escape characters in TexInfo, use the character {{Codeline|@}}. Only the characters '''@''', '''{''' and '''}''' need to be escaped. | ||
Line 93: | Line 177: | ||
In certain contexts (such as {{Codeline|@acronym}} or {{Codeline|@xref}}), commas may need to be escaped. In such situations, use {{Codeline|<nowiki>@comma{}</nowiki>}}. | In certain contexts (such as {{Codeline|@acronym}} or {{Codeline|@xref}}), commas may need to be escaped. In such situations, use {{Codeline|<nowiki>@comma{}</nowiki>}}. | ||
=== Ellipsis (...) === | ==== Ellipsis (...) ==== | ||
Ellipsis are frequently used in octave help text, | Ellipsis are frequently used in octave help text, especially when defining a function API. Use the {{Codeline|<nowiki>@dots{}</nowiki>}} rather than three dots. | ||
{{Code||<pre> | {{Code||<pre> | ||
@deftypefn { | @deftypefn {} {} imhist (@var{I}) | ||
@deftypefnx { | @deftypefnx {} {[@var{counts}, @var{x}] =} imhist (@dots{}) | ||
</pre>}} | </pre>}} | ||
=== Matlab === | ==== Matlab ==== | ||
Sometimes it is | Sometimes it is needed to mention Matlab in the help text. An example might be to mention that a weird behavior needs to be kept for Matlab compatibility. In such case, small caps should be used. For example, the following is used in the {{Codeline|length}} help text: | ||
{{Code||<pre> | {{Code||<pre> | ||
Line 108: | Line 192: | ||
greater (this odd definition is used for compatibility with @sc{matlab}). | greater (this odd definition is used for compatibility with @sc{matlab}). | ||
</pre>}} | </pre>}} | ||
[[Category:Development]] |