SYNOPSIS -- a standardized synopsis for use in documentation nodes

Synopsis

Usage:

SYNOPSIS ( ..., Usage => "...", ... )
Inputs:
- a list, with Hypertext, String, and special documentation entries as optional arguments such as Usage => "..." (required)
Optional inputs:
- BaseFunction => a function, default value null, see document(...,BaseFunction=>...) -- the basename of a function in a documentation node
- Heading => a list, default value "Synopsis", see document(...,Headline=>...) -- specifies a subheading for the synopsis
- Usage => a list, default value "", see document(...,Usage=>...) -- ways to use a function in a documentation node
- Inputs => a list, default value {}, see document(...,Inputs=>...) -- inputs for a function in a documentation node
- Outputs => a list, default value {}, see document(...,Outputs=>...) -- outputs for a function in a documentation node
- Consequences => a list, default value {}, see document(...,Consequences=>...) -- side-effects of a function in a documentation node
Outputs:
- a markup list, usable as an input of document(List)

Description

This function prepares a standardized synopsis in hypertext for use in documentation nodes. Here is an empty template for use with SYNOPSIS.


SYNOPSIS (
        BaseFunction => fn,
        Heading      => "",
        Usage        => "",
        Inputs       => {},
        Outputs      => {},
        Consequences => {},
        PARA { ... },
        EXAMPLE lines " ... ")

The options are used just as with document. Here is an example of its use.


SYNOPSIS {
        Heading => "using binary methods for method functions",
        Usage   => "f(x,y)",
        Inputs  => {
            "f" => { "a method function" },
            "x" => { "an object of type ", TT "X" },
            "y" => { "an object of type ", TT "Y" }},
        Outputs => {
            { "the previously installed method for ", TT "f(X, Y)", " is called with arguments ", TT "(x, y)",
                ", and the return value is returned. If no such method has been installed, then Macaulay2
                searches for a method for ", TT "f(X',Y')", ", where ", TT "X'", " is an ancestor of ", TT "X",
                " and ", TT "Y'", " is an ancestor of ", TT "Y", "(see ", TO "inheritance", " for details)."}},
        "The second line of the following example illustrates the syntax above,
        using ", TO "source", ", which happens to be a method function.",
        EXAMPLE lines ///
          source(String, String) := peek;
          source("foo", "bar")///,
        PARA "The same syntax works for 3 or 4 arguments."}

See the Synopsis keyword in doc(String) for usage as a keyword in that format.

Ways to use SYNOPSIS :

SYNOPSIS(List)
SYNOPSIS(Sequence)
SYNOPSIS(Thing)

For the programmer

The object SYNOPSIS is a method function with a single argument.