Help text style guide: Difference between revisions
Carandraug (talk | contribs) (created page) |
Carandraug (talk | contribs) (→Guidelines: News section with octave guidelines to write help text) |
||
Line 1: | Line 1: | ||
Functions should have help text so that people know how to use it. | Functions should have help text so that people know how to use it. | ||
= Guidelines = | |||
== 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}}: | |||
<pre> | |||
Produce histogram counts or plots. # good | |||
Produces histogram counts or plots. # bad | |||
hist produces histogram counts or plots. # bad | |||
</pre> | |||
== 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: | |||
{{Code|adding tag for function help text in Octave's manual|<pre> | |||
+@DOCSTRING(function_name) | |||
</pre>}} | |||
If appropriate, also write some text about the function on the manual for better inclusion into the manual. | |||
== Sentence spacing == | |||
The typographical convention in Octave is to use two full spaces after a period that ends a sentence. For example: | |||
<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> | |||
= TexInfo = | = TexInfo = | ||
This is the | This is the preferred format for help text. There is also a comprehensive [http://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html TexInfo manual]. | ||
== Octave specific macros == | == Octave specific macros == |
Revision as of 13:44, 15 March 2012
Functions should have help text so that people know how to use it.
Guidelines
First sentence
The first sentence of help text should start with a statement that is like a command. For example, the first sentence of hist
:
Produce histogram counts or plots. # good Produces histogram counts or plots. # bad hist produces histogram counts or plots. # bad
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 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 |
+@DOCSTRING(function_name) |
If appropriate, also write some text about the function on the manual for better inclusion into the manual.
Sentence spacing
The typographical convention in Octave is to use two full spaces after a period that ends a sentence. For example:
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
TexInfo
This is the preferred format for help text. There is also a comprehensive TexInfo manual.
Octave specific macros
seealso
Do not use this macro empty as it will create problems with the generate_html package.
deftypefn
Formatting
Verbatim
Use this to include literal text. Special useful to insert formulas.
@verbatim E[Z(i,k) ] IRL(k) = ------------ V(i) @end verbatim |
Examples
Do not use the example environment to insert formulas, consider using @verbatim
instead
Special inserts
Escape characters
To escape characters in TexInfo, use the character @
. Only the characters @, { and } need to be escaped.
@@
stands for a single @ (do not put braces after an@@
command)@{
stands for a single {@}
stands for a single }
In certain contexts (such as @acronym
or @xref
), commas may need to be escaped. In such situations, use @comma{}
.
Ellipsis (...)
Ellipsis are frequently used in octave help text, specially when defining a function API. Use the @dots{}
rather than three dots.
@deftypefn {Function File} {} imhist (@var{I}) @deftypefnx {Function File} {[@var{counts}, @var{x}] =} imhist (@dots{}) |