Help text style guide

From Octave
Revision as of 19:28, 9 January 2012 by Carandraug (talk | contribs) (created page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Functions should have help text so that people know how to use it.

TexInfo

This is the prefered 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{})