# multidoc -- a simple documentation function, allowing multiple documentation nodes

## Synopsis

• Usage:
multidoc s
• Inputs:
• s,
• Consequences:
• The string s is handled by parsing it the same way doc does, but expecting the least indented keyword to be Node, which can occur multiple times. The text following each such keyword is handled just as by doc, resulting in a documentation node.

## Description

Here is the input submitted to multidoc to document (most of) this package:

 -- -*- 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@ 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}, {\bf Caveat}, and {\bf ExampleFiles}. 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 CannedExample}, {\bf Pre}, and {\bf Code}. The text in a {\bf Text} subsection can be separated into paragraphs with blank lines. (A paragraph, when rendered in HTML, will normally be enclosed in an HTML P tag, except if its top level markup is an instance of @TO HypertextContainer@ or @TO HypertextParagraph@.) The text in an {\bf Example} subsection consists of lines of Macaulay2 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; output will be generated automatically and incorporated into the display. The text in a {\bf CannedExample} subsection consists of lines containing an interaction with Macaulay2, to displayed as an example. 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@. Each line in the {\bf ExampleFiles} 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 visible in the current directory while the example code is running. 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"

## Ways to use multidoc :

• multidoc(String)