-- -*- mode: M2; coding: utf-8 -*-
Node
Key
multidoc
(multidoc,String)
Headline
a simple documentation function, allowing multiple documentation nodes
Usage
multidoc s
Inputs
s:String
Consequences
Item
The string {\tt s} is handled by parsing it the same way @ TO doc @ does, but
expecting the least indented keyword to be {\bf Node}, which can occur
multiple times. The text following each such keyword is handled just as by @
TO doc @, resulting in a documentation node.
Description
Text
Here is the input submitted to @ TO multidoc @ to document (most of) this package:
Code
EXAMPLE { PRE concatenate between("\n", lines get(SimpleDoc#"source directory" | "SimpleDoc/doc.txt")) }
Node
Key
packageTemplate
(packageTemplate,String)
Headline
a template for a package
Usage
packageTemplate s
Inputs
s:String
the name of the package
Description
Text
This routine returns a barebones package template
that you can use to start writing a package.
Example
print packageTemplate "WonderfulModules"
SeeAlso
"docExample"
Node
Key
"docTemplate"
Headline
a template for a documentation node
Usage
docTemplate
Description
Text
docTemplate is a @TO String@, which can
be cut and paste into a text file,
to be used as a template for writing
documentation for functions and other objects
in a package.
Example
print docTemplate
SeeAlso
"docExample"
Node
Key
simpleDocFrob
Headline
an example of a function to document
Node
Key
"docExample"
Headline
an example documentation node
Usage
docExample
Description
Text
The variable docExample is a @TO String@ containing an example of
the use of @TO (doc,String)@ to write a documentation page, visible
@TO2 {(simpleDocFrob,ZZ,Matrix), "here"}@.
Example
docExample
SeeAlso
"docTemplate"
Node
Key
SimpleDoc
Headline
simpler documentation for functions and methods
Subnodes
doc
"docExample"
multidoc
packageTemplate
"docTemplate"
Node
Key
doc
(doc,String)
Headline
a simple documentation function
Usage
doc s
Inputs
s:String
See the example below for the format of {\tt s}
Consequences
Item
Documentation is created and stored so that after
@TO installPackage@ or @TO getPackage@ is used,
the corresponding documentation is
available via @TO help@ and @TO viewHelp@
Description
Text
The string {\tt s} contains text describing the documentation to be produced.
Lines beginning with white space followed by two hyphens are ignored.
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: {\bf Key}, {\bf Headline}, {\bf Usage}, {\bf Inputs},
{\bf Outputs}, {\bf Consequences}, {\bf Description}, {\bf SeeAlso}, {\bf Subnodes}, and {\bf Caveat}.
The only keyword which is always required is {\bf Key}.
Each line in the {\bf Key} section is evaluated as a Macaulay2 expression
to yield a documentation key. The various types of documentation keys are
described in @TO [document,Key]@. (If a string is desired as a key, it must be
surrounded by quotation marks.)
The body of the {\bf Headline} section should have a single line, which will be interpreted as a string.
The lines of the {\bf Usage} section may be used to present alternative usages, and they will be collected into a single string.
The text in an {\bf Inputs} or {\bf 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. The name of the variable must be a nonempty string
of alphanumeric characters or quotation marks. For example, the first line
might be {\tt 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 {\tt
Precision => ZZ}.) Subsequent lines of the subsection, indented further,
describe the variable and may include markup.
Markup allowed includes many TeX commands, as allowed in @TO TEX@; for
details and examples see @TO (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 {\tt \@} characters, enclosing Macaulay2 code to
be executed, yielding appropriate hypertext. For example, {\tt \@TO Key\@}
will insert a link to another node of the documentation.
Each subsection of the {\bf Consequences} section should start with the
keyword {\bf Item}; the text in each subsection can be marked up as
described above.
The text in the {\bf Description} section occurs in subsections labeled with
the keywords {\bf Text}, {\bf Example}, {\bf Pre}, and {\bf Code}. The
text in a {\bf Text} subsection can be separated into paragraphs with blank
lines. Each paragraph can contain markup as described above. The text in
an {\bf Example} subsection consists of lines of code to be used as
examples in the documentation node. Within in each complete expression,
indent lines after the first one more than the first. The text in a {\bf
Pre} section, with common indentation removed, is wrapped with @ TO PRE @.
The text in a {\bf Code} section, 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
@TO document@.
The lines in the {\bf Subnodes} 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 in the {\bf Subnodes} section beginning with a
colon are subheadings used to classify the subnodes.
SeeAlso
multidoc
document
"docExample"
"docTemplate"
-- Local Variables:
-- compile-command: "make -C $M2BUILDDIR/Macaulay2/packages PACKAGES=SimpleDoc RemakePackages=true RemakeAllDocumentation=true IgnoreExampleErrors=false RerunExamples=true"
-- End:
|