doc -- a simple documentation function

Synopsis

Usage:

doc s

document s
Inputs:
- s, a string, a structured source for the documentation, either as a string or a filename
Consequences:
- Documentation is created and stored so that after installPackage is used, help and viewHelp can be used to access the corresponding documentation node(s)

Description

The string s contains a series of sections describing the documentation to be produced. The first line of each section contains only a keyword that specifies the purpose of that section. The keywords must all be indented to the same level, and everything else must be further indented. Lines beginning with white space followed by two hyphens are ignored and can be used for commenting.

document(String) (missing documentation) is a synonym for doc. For backwards compatibility, the function multidoc is also a synonym for doc.

Template for documentation strings

The variable docTemplate is a String, which can be cut and pasted into a text file, to be used as a template for writing documentation for functions and other objects in a package.


doc ///
Key
Headline
Usage
Inputs
Outputs
Consequences
  Item
Description
  Text
  Tree
  Code
  Pre
  Example
  CannedExample
ExampleFiles
Acknowledgement
Contributors
References
Caveat
SeeAlso
Subnodes
///

Description of keywords allowed in documentation strings

The only keyword which is always required is Key. Other valid keywords are:

Key -- key of a documentation node
Each line in this section is evaluated as a Macaulay2 expression to yield a documentation key. If the key is a string, for instance the title of a tutorial, it must be surrounded by quotation marks. Examples for documentation keys are given in document(...,Key=>...).
Headline -- headline of a documentation node
The body of this section should be a single line description of the node.
Usage -- ways to use a function in a documentation node
The lines of this section present alternative usages of the key.
Inputs -- inputs for a function in a documentation node
Outputs -- outputs for a function in a documentation node
The text in these sections is divided into subsections, each of which corresponds to one input or output value. The first line of each subsection contains the name of the variable corresponding to it, as referred to in the usage line, a colon, and the type of the variable. The name of the variable must be a nonempty string of alphanumeric characters or quotation marks. For example, the first line might be s2:String. The variable name and type are both optional.

For optional inputs, one puts the name of the option, a double arrow, and the expected type of value; for example, the first line might be Precision=>ZZ. Subsequent lines of the subsection, indented further, describe the variable and may include markup.
Consequences -- side-effects of a function in a documentation node
Each subsection of the this section should start with the keyword Item; the text in each item may include markup.
Description
The text in this section occurs in subsections with keywords:
- Text -- prose containing markup or tex
  The text in this subsection can be separated into paragraphs with blank lines. A paragraph, when rendered in HTML, is typically enclosed in an HTML <p> tag, except if its top level markup is an instance of HypertextContainer or HypertextParagraph.
- Tree -- classify documentation nodes under headings
  The lines in this section beginning with : or @ are treated as subsections. The remaining lines are treated as keys to a documentation node and are processed by the TOH function, producing a link followed by the headline. The purpose is to allow a classification of the documentation nodes grouped under a subsections. Further indentation is treated as further sub-classifications.
- Example -- examples of the usage
  The text in this subsection consists of lines of Macaulay2 code to be used as examples in the documentation node. Output will be generated automatically and incorporated into the display.
- CannedExample -- pre-evaluated example results
  The text in this subsection consists of lines containing an interaction with Macaulay2, to displayed as an example.
- Pre -- preformatted text
  The text in this subsection, with common indentation removed, is wrapped with PRE.
- Code -- custom Macaulay2 code
  The text in this subsection, with common indentation removed, is wrapped with parentheses and evaluated; the result is spliced into the list of documentation items at the appropriate point before passing the list to document.
Synopsis -- prepare documentation for different usages of a function

Each section with this keyword prepares a standardized synopsis similar to the SYNOPSIS template of the classic document command. The text in this section occurs in subsections with the following keywords:
- Heading -- similar to the Headline keyword
- BaseFunction -- the basename of the function; see SYNOPSIS(...,BaseFunction=>...)
- Keywords that can be repeated once for each synopsis: Usage (required), Inputs, Outputs, Consequences, and Description (missing documentation) .
Acknowledgement -- acknowledgements listed in a documentation node
Contributors -- non-author contributors listed in a documentation node
References -- references listed in a documentation node
The text in these sections is parsed and rendered similar to the Text subsection and can be used to acknowledge funding sources, collaborators, and non-author contributors, or to provide references.
Caveat -- warnings or limitations listed in a documentation node
The text in these sections is parsed and rendered similar to the Text subsection and can be used to inform users of potential limits of the implementation.
SeeAlso -- cross-references to other documentation nodes
The lines in this section are parsed as in the Key section and are displayed as links to other relevant documentation nodes.
Subnodes -- a menu of documentation nodes
The lines in this section not beginning with a colon are keys giving links to the subnodes of the current documentation node. The purpose is to allow the documentation of the package to be arranged linearly, as in a book. The lines beginning with a colon are subheadings used to classify the subnodes.
SourceCode -- sources displayed in a documentation node
The lines in this section are parsed as a list of functions whose source code should be displayed in the documentation.
ExampleFiles -- data files corresponding to a documentation node
Each line in this section should be the name of a file in the auxiliary files directory of the package; the name of that directory is the same as the name of the package. Copies of the corresponding files will be made available in the running path of the examples.

Markup keywords allowed in documentation strings

The markup keywords allowed include many TeX commands, as allowed in TEX; for details and examples see html(TEX), allowing various mathematical expressions, such as $\PP^3$ or $x_i^{33} + 1/2$, to be displayed in the html form of the documentation.

Also allowed is a pair of @ characters, enclosing Macaulay2 code to be executed, yielding appropriate hypertext. For example

The @TO Key@ section is required.

will include a link to another node of the documentation. This package also provides a number of helper functions, such as the arXiv function, which may be used to succinctly reference e-Prints. See Text for other hypertext types.

Note that any Macaulay2 code resulting in a String or Hypertext may be used inside @...@, but for longer code it is easier to use the Code keyword described above.

Documenting multiple nodes at once

If the least indented keyword in the documentation string s is Node, possibly occurring multiple times, multiple documentation nodes will be prepared.

Node
The text following each such keyword is handled just as by doc resulting in a separate documentation node.

See SimpleDoc/doc.txt for an example of how the Node keyword is used in documenting this package.

Ways to use doc :

doc(String)

For the programmer

The object doc is a method function.