The string s contains text describing the documentation to be produced.
The text is divided into sections, each of which begins with a keyword alone on a line; the keywords must all be indented to the same level, and everything else must be further indented.
The valid keywords are: Key, Headline, Usage, Inputs, Outputs, Consequences, Description, SeeAlso, and Caveat.
The only keyword which is always required is Key.
Each line in the Key section is evaluated as a Macaulay 2 expression to yield a documentation key. The various types of documentation keys are described in Key. (If a string is desired as a key, it must be surrounded by quotation marks.)
The bodies of the Headline and Usage sections should have a single line, which will be interpreted as a string.
The text in an Inputs or Outputs section 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. For example, the first line might be s:String. The variable name and type are both optional. Subsequent lines of the subsection, indented further, describe the variable. These lines may include markup.
Markup allowed includes many TeX commands, as allowed in TEX; for details and examples see html(TEX), allowing various mathematical expressions, such as ℙ3 or xi33 + 1/2, to be displayed in the html form of the documentation. Also allowed is a pair of @ characters, enclosing Macaulay 2 code to be executed, yielding appropriate hypertext. For example, @TO Key@ will insert a link to another node of the documentation.
The text in the Consequences section can be marked up as described above.
The text in the Description section occurs in subsections labeled with the keywords Text and Example. The text in a Text subsection can be separated into paragraphs with blank lines. Each paragraph can contain markup as described above. The text in an Example subsection consists of lines of code to be used as examples in the documentation node.
The following example is not complete yet, as we are writing this documentation node using ", TO "doc", ", and multi-line example code is not yet implemented to allow writing a better example.
i1 : ourfcn = method() o1 = ourfcn o1 : MethodFunction |
i2 : ourfcn ZZ := (n) -> n+1; |
i3 : ourfcn 3 o3 = 4 |