3.8.10 Typesetting of help and info strings

The info strings of the libraries which are included in the distribution of SINGULAR and the help strings of the corresponding procedures are parsed and automatically converted into the texinfo format (the typesetting language in which the documentation of SINGULAR is written).

The illustrative example given in template_lib should provide sufficient information on how this works. For more details, check the following items:

• Users familiar with texinfo may write help and info strings directly in the texinfo format. The string should, then, start with the @ sign. In this case, no parsing will be done.
• Help and info strings are typeset within a @table @asis environment (which is similar to the latex description environment).
• If a line starts with uppercase words up to a colon, then the text up to the colon is taken to be the description-string of an item, and the text following the colon is taken to be the content of the item.
• If the description-string of an item matches

  SEE ALSO

  then the content of the item is assumed to consist of comma-separated words which are valid references to other texinfo nodes of the manual (e.g., all procedure and command names are also texinfo nodes).

  KEYWORDS

  then the content of the item is assumed to be a semicolon-separated list of phrases which are taken as keys for the index of the manual (the name of a procedure/library is automatically added to the index keys).

• If the description-string of an item in the info string of a library matches

  LIBRARY

  then the content of the item is assumed to be a one-line description of the library. If this one-line description consists of uppercase characters only, then it is typeset in lowercase characters (otherwise it is left as is).

  PROCEDURES

  then the content of the item is assumed to consist of lines of type

  <proc_name>(); <one line description of the purpose>

  Separate texinfo nodes (subsections in printed documents) are created precisely for those procedures of the library appearing here (that is, for some if not all non-static procedures of the library).

With respect to the content of an item, the following texinfo markup elements are recognized:

• @* Enforces a line-break.

  Example:

  old line @* new line
  ==>
  old line
  new line

• @ref{...} For references to other parts of the SINGULAR manual, use one of the following @ref{node} constructs. Here, node must be the name of a section of the SIGNULAR manual. In particular, it may be the name of a function, library or procedure in a library.

  @xref{node}

  for a reference to the node node at the beginning of a sentence.

  @ref{node}

  for a reference to the node node at the end of a sentence.

  @pxref{node}

  for a reference to the node node within parentheses.

  Example:

  @xref{Hurricanes}, for more info.
  ==>*Note Hurricanes::, for more info.
  ==>See Section 3.1 [Hurricanes], page 24, for more info.

  For more information, see @ref{Hurricanes}.
  ==>For more information, see *Note Hurricanes::.
  ==>For more information, see Section 3.1 [Hurricanes], page 24.

  ... storms cause flooding (@pxref{Hurricanes}) ...
  ==>... storms cause flooding (*Note Hurricanes::) ...
  ==>... storms cause flooding (see Section 3.1 [Hurricanes], page 24)

• @math{..} Typeset short mathematical expressions in LaTeX math-mode syntax (short: does not cause expansion over multiple lines).

  Example:

  @math{\alpha}
  ==>
  

  Note:

  The mathematical expressions inside @math{..} must not contain the characters {,}, and @.

• @code{..} Typeset short strings in typewriter font (short: does not cause expansion over multiple lines).

  Example:

  @code{typewriter font}
  ==>
  typewriter font

  Note:

  The string inside @code{..} must not contain the characters {,}, and @.

• Typeset pre-formatted text in typewriter font.

  @example ... @end example

  Example:

  before example @example in example notice escape of special characters like @{,@},@@ @end example after example

  ==>
  before example

  in example notice escape of special characters like {,},@

  after example

  Note:

  Inside an @example environment, the characters {,},@ have to be escaped by an @ sign.

• Typeset pre-formatted text in normal font.

  @format ... @end format

  Example:

  before format @format in format notice escape of special characters like @{,@},@@ @end format after format

  ==>
  before format

  in format escape of special characters like {,},@

  after format

  Note:

  Inside an @format environment, the characters {,},@ have to be escaped by an @ sign.

• Write text in pure texinfo.

  @texinfo ... @end texinfo

  Example:

  @texinfo Among others, within a texinfo environment, one can use the tex environment to typeset more complex mathematical items like @tex $i_{1,1} $ @tex @end texinfo

  
  ==>
  Among others, within a texinfo environment, one can use the tex environment to typeset more complex mathematical items like

  Furthermore, a line-break is inserted before each line whose previous line is shorter than 60 characters and does not contain any of the above described recognized texinfo markup elements.