next | previous | forward | backward | up | top | index | toc | Macaulay2 website
Macaulay2Doc > The Macaulay2 language > writing documentation > document

document -- create a documentation node

Synopsis

Description

There are two basic types of documentation:

  1. Documenting a function or a method, as in resolution(Module).
  2. documenting an overview or functions with methods, as in chain complexes or resolution respectively.

The headings Usage, BaseFunction, Inputs, Outputs, and Consequences, are useful only for documentation of the first type, as well as in a call to SYNOPSIS.

Templates for using the document(List) method

Here is a basic template:


    document {
        Key          => {myFunc, (myFunc, MyType), [myFunc, MyOption], ...},
        Headline     => "one line description of myFunc", -- not needed for overviews
        BaseFunction => myFunc, -- usually not needed
        Usage        => "myFunc x",
        Inputs       => { inputs, ... },
        Outputs      => { outputs, ... },
        SourceCode   => { METHOD1, ... }, -- usually not needed
        Consequences => { side-effects, ... },
        "A list of strings containing names of files in the auxiliary
        directory of the package can go here; the files will be visible
        in the current directory while example code is run.",
        ExampleFiles => {"datafile1", "datafile2"},
        "There can be explanatory prose here in the form of a hypertext list.",
        EXAMPLE lines ///
          m2code
          m2code
          m2code
        ///,
        "There can be explanatory prose here in the form of a hypertext list.",
        Caveat       => {"warning"},
        SeeAlso      => {"other things"},
        Subnodes     => {
            "subheading a",
            TO "node 1",
            TO "node 2",
            "subheading b",
            TO "node 3",
            ...
            },
        }

Other Functions generating hypertext list format that you may use:

  • SYNOPSIS -- a standardized synopsis for use in documentation nodes
  • EXAMPLE -- hypertext EXAMPLE item

See also

Ways to use document :

For the programmer

The object document is a function closure.

Menu

Documentation templates based on the hypertext list format

Special documentation keywords