-- -*- mode: M2; coding: utf-8 -*- Node Key SimpleDoc Headline simpler documentation for functions and methods Description Text This package provides a simple, human-readable text format for documentation nodes as an alternative to the classic @TO "Macaulay2Doc :: hypertext list format"@ accepted by the @TO "Macaulay2Doc :: document(List)"@ function. The new format is accepted by the @TO (doc, String)@ function for writing either a single or multiple documentation nodes from a string or file and adheres to the @wikipedia "off-side rule"@, i.e., using indentation to separate blocks. Tree :Getting started with SimpleDoc @TO2 {"Macaulay2Doc :: writing documentation", "Writing documentation in Macaulay2"}@ @TO2 {doc, "Using SimpleDoc for documentation"}@ @TO2 {"Text", "Using markup in documentation"}@ @TO2 {"Text::html(TEX)", "Using TeX in documentation"}@ :Templates for using the @TO (doc, String)@ method "docExample" "docTemplate" packageTemplate :Documentation helpers arXiv stacksProject wikipedia Contributors Andrew Hoefel contributed to this package. Node Key packageTemplate (packageTemplate, String) Headline a template for a package Usage packageTemplate name Inputs name:String the name of the package Description Text This routine returns a barebones package template that can be used to start writing a package. Example print packageTemplate "WonderfulModules" SeeAlso "docExample" "testExample" Node Key "docExample" Headline an example of a documentation string Usage docExample Description Text The variable {\tt 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"}@. Code EXAMPLE { PRE docExample } SeeAlso packageTemplate "testExample" Node Key "testExample" Headline an example of a test string Usage testExample Description Text The variable {\tt testExample} is a @TO String@ containing an example of the use of @TO "Macaulay2Doc :: TEST(String)"@ to write a test case. Code EXAMPLE { PRE testExample } Text The @TO check@ method executes all package tests defined this way. Example check SimpleDoc SeeAlso symbol TEST check packageTemplate "docExample" Node Key doc (doc, String) (document, String) "multidoc" "docTemplate" Description Headline a simple documentation function Usage doc s document s Inputs s:String a structured source for the documentation, either as a string or a filename Consequences Item Documentation is created and stored so that after @TO installPackage@ is used, @TO help@ and @TO viewHelp@ can be used to access the corresponding documentation node(s) Description Text The string {\tt 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. @TO (document, String)@ is a synonym for @TO doc@. For backwards compatibility, the function @TT "multidoc"@ is also a synonym for @TO doc@. Text @HEADER2 "Template for documentation strings"@ The variable {\tt docTemplate} is a @TO 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. Code EXAMPLE { PRE docTemplate } Text @HEADER2 "Description of keywords allowed in documentation strings"@ The only keyword which is always required is @TO Key@. Other valid keywords are: Code UL { { TOH Key, PARA { "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 ", TO [document,Key], "."}}, { TOH Headline, PARA {"The body of this section should be a single line description of the node."}}, { TOH Usage, PARA {"The lines of this section present alternative usages of the key."}}, { TOH Inputs, BR{}, TOH Outputs, PARA { "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 ", TT "s2:String", ". The variable name and type are both optional."}, PARA { "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."}}, { TOH Consequences, PARA { "Each subsection of the this section should start with the keyword ", TT "Item", "; the text in each item may include markup."}}, { TT "Description", PARA {"The text in this section occurs in subsections with keywords:"}, UL { { TT "Text", " -- prose containing markup or tex", PARA { "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 ", TT "

", " tag, except if its top level markup is an instance of ", TO HypertextContainer, " or ", TO HypertextParagraph, "."}}, { TT "Tree", " -- classify documentation nodes under headings", PARA { "The lines in this section beginning with ", TT ":", " or ", TT "@", " are treated as subsections. The remaining lines are treated as keys to a documentation node and are processed by the ", TO 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."}}, { TT "Example", " -- examples of the usage", PARA { "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."}}, { TT "CannedExample", " -- pre-evaluated example results", PARA { "The text in this subsection consists of lines containing an interaction with Macaulay2, to displayed as an example."}}, { TT "Pre", " -- preformatted text", PARA { "The text in this subsection, with common indentation removed, is wrapped with ", TO PRE, "."}}, { TT "Code", " -- custom Macaulay2 code", PARA { "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 ", TO document, "."}} } }, { TT "Synopsis", " -- prepare documentation for different usages of a function", BR{}, PARA { "Each section with this keyword prepares a standardized synopsis similar to the ", TO SYNOPSIS, " template of the classic ", TO document, " command. The text in this section occurs in subsections with the following keywords:"}, UL { { TO Heading, " -- similar to the ", TO Headline, " keyword" }, { TO BaseFunction, " -- the basename of the function; see ", TO [SYNOPSIS, BaseFunction] }, { "Keywords that can be repeated once for each synopsis: ", TO Usage, " (required), ", TO Inputs, ", ", TO Outputs, ", ", TO Consequences, ", and ", TO Description, "."} }, BR{} }, { TOH Acknowledgement, BR{}, TOH Contributors, BR{}, TOH References, PARA { "The text in these sections is parsed and rendered similar to the ", TO Text, " subsection and can be used to acknowledge funding sources, collaborators, and non-author contributors, or to provide references."}}, { TOH Caveat, PARA { "The text in these sections is parsed and rendered similar to the ", TO Text, " subsection and can be used to inform users of potential limits of the implementation."}}, { TOH SeeAlso, PARA { "The lines in this section are parsed as in the ", TO Key, " section and are displayed as links to other relevant documentation nodes."}}, { TOH Subnodes, PARA { "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."}}, { TOH SourceCode, PARA { "The lines in this section are parsed as a list of functions whose source code should be displayed in the documentation."}}, { TOH ExampleFiles, PARA { "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."}} } Text @HEADER2 "Markup keywords allowed in documentation strings"@ The markup keywords allowed include 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 Pre The @TO Key@ section is required. Text will include a link to another node of the documentation. This package also provides a number of helper functions, such as the @TO arXiv@ function, which may be used to succinctly reference e-Prints. See @TO "Text"@ for other hypertext types. Note that any Macaulay2 code resulting in a @TO String@ or @TO Hypertext@ may be used inside {\tt \@...\@}, but for longer code it is easier to use the @TT "Code"@ keyword described above. Text @HEADER2 "Documenting multiple nodes at once"@ If the least indented keyword in the documentation string {\tt s} is @TT "Node"@, possibly occurring multiple times, multiple documentation nodes will be prepared. @UL {{ TT "Node", PARA {"The text following each such keyword is handled just as by ", TO doc, " resulting in a separate documentation node."}}}@ See @HREF {currentLayout#"packages" | "SimpleDoc/doc.txt", "SimpleDoc/doc.txt"}@ for an example of how the @TT "Node"@ keyword is used in documenting this package. SeeAlso document "testExample" "docExample"