# Singular

### 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  (); 
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.

For more information, see @ref{Hurricanes}.

... 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.