document -- create a documentation node

Synopsis

• Usage:

  document { Key => key, ... }

• Inputs:
  • a list, with Hypertext, String, and special documentation entries as optional arguments such as Key => "..." (required)
• Optional inputs:
  • Key => a list, default value null, key of a documentation node
  • Headline => a list, default value null, headline of a documentation node
  • BaseFunction => a list, default value null, the basename of a function in a documentation node
  • Usage => a list, default value null, ways to use a function in a documentation node
  • Inputs => a list, default value null, inputs for a function in a documentation node
  • Outputs => a list, default value null, outputs for a function in a documentation node
  • Consequences => a list, default value null, side-effects of a function in a documentation node
  • Acknowledgement => a list, default value null, acknowledgements listed in a documentation node
  • Contributors => a list, default value null, non-author contributors listed in a documentation node
  • References => a list, default value null, references listed in a documentation node
  • Caveat => a list, default value null, warnings or limitations listed in a documentation node
  • SeeAlso => a list, default value null, cross-references to other documentation nodes
  • Subnodes => a list, default value null, a menu of documentation nodes
  • SourceCode => a list, default value null, sources displayed in a documentation node
  • ExampleFiles => a list, default value null, data files corresponding to a documentation node
• Consequences:

  • formatted documentation is created and stored in the current package

Description

    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 containings 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",
            ...
            },
        }

See also

• writing documentation
• hypertext -- prepare hypertext for display

Menu

Documentation templates based on the hypertext list format

• package documentation template
• function documentation template
• optional argument documentation template
• overview documentation template

Special documentation keywords

• "document(...,Key=>...)" -- see Key -- key of a documentation node
• "document(...,Headline=>...)" -- see Headline -- headline of a documentation node
• "document(...,BaseFunction=>...)" -- see BaseFunction -- the basename of a function in a documentation node
• "document(...,Usage=>...)" -- see Usage -- ways to use a function in a documentation node
• "document(...,Inputs=>...)" -- see Inputs -- inputs for a function in a documentation node
• "document(...,Outputs=>...)" -- see Outputs -- outputs for a function in a documentation node
• "document(...,Consequences=>...)" -- see Consequences -- side-effects of a function in a documentation node
• "document(...,Acknowledgement=>...)" -- see Acknowledgement -- acknowledgements listed in a documentation node
• "document(...,Contributors=>...)" -- see Contributors -- non-author contributors listed in a documentation node
• "document(...,References=>...)" -- see References -- references listed in a documentation node
• "document(...,Caveat=>...)" -- see Caveat -- warnings or limitations listed in a documentation node
• "document(...,SeeAlso=>...)" -- see SeeAlso -- cross-references to other documentation nodes
• "document(...,Subnodes=>...)" -- see Subnodes -- a menu of documentation nodes
• "document(...,SourceCode=>...)" -- see SourceCode -- sources displayed in a documentation node
• "document(...,ExampleFiles=>...)" -- see ExampleFiles -- data files corresponding to a documentation node