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.
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 /// |
The only keyword which is always required is Key. Other valid keywords are:
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=>...).
The body of this section should be a single line description of the node.
The lines of this section present alternative usages of the key.
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.
Each subsection of the this section should start with the keyword Item; the text in each item may include markup.
The text in this section occurs in subsections with keywords:
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.
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.
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.
The text in this subsection consists of lines containing an interaction with Macaulay2, to displayed as an example.
The text in this subsection, with common indentation removed, is wrapped with PRE.
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.
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:
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.
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.
The lines in this section are parsed as in the Key section and are displayed as links to other relevant 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.
The lines in this section are parsed as a list of functions whose source code should be displayed in the documentation.
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.
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.
If the least indented keyword in the documentation string s is Node, possibly occurring multiple times, multiple documentation nodes will be prepared.
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.
The object doc is a method function.