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

User manual for Singular version 4-0-3, 2016, generated by texi2html.