next | previous | forward | backward | up | top | index | toc | Macaulay2 website
SimpleDoc :: doc

doc -- a simple documentation function

Synopsis

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:

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.

See also

Ways to use doc :

For the programmer

The object doc is a method function.