Help text style guide: Difference between revisions

From Octave
Jump to navigation Jump to search
(created page)
 
(→‎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 prefered format for help text. There is also a comprehensive [http://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html TexInfo manual].
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{})