Home Online Manual
Top
Back: Documentation Tool
Forward: Loading a library
FastBack: Procedures
FastForward: Debugging tools
Up: Libraries
Top: Singular Manual
Contents: Table of Contents
Index: Index
About: About this document

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 SINGULAR 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}
    ==>
    $\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 $i_{1,1}$

    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.