next | previous | forward | backward | up | top | index | toc | Macaulay2 web site

doc(String) -- a simple documentation function

Synopsis

Description

The text used to create the documentation node you are currently reading is displayed below.

The string s contains text describing the documentation to be produced.

Lines beginning with 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: Key, Headline, Usage, Inputs, Outputs, Consequences, Description, SeeAlso, Subnodes, and Caveat.

The only keyword which is always required is Key.

Each line in the Key section is evaluated as a Macaulay2 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 Macaulay2 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, Example, and Code. 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. Within in each complete expression, indent lines after the first one more than the first. The text in a 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 document.

The lines in the Subnodes section not beginning with a colon are keys giving links to the subnodes of the current documentation node. The purpose to allow the documentation of the package to be arranged linearly, as in a book. The lines in the Subnodes section beginning with a colon are subheadings used to classify the subnodes.

Here is some example code:
i1 : ourfcn = method()

o1 = ourfcn

o1 : MethodFunction
i2 : ourfcn ZZ := (n) -> (
         n+1)

o2 = {*Function[stdio:2:17-3:6]*}

o2 : FunctionClosure
i3 : ourfcn 3

o3 = 4
Here is the text used to create this file:
  Key
    (doc,String)
    doc
  Headline
    a simple documentation function
  Usage
    doc s
  Inputs
    s:String
      See the example below for the format of {\tt s}
  Consequences
    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 text used to create the documentation node you are currently reading is
    displayed below.

    The string {\tt s} contains text describing the
    documentation to be produced.

    Lines beginning with 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: @TO Key@, @TO Headline@, @TO Usage@, @TO Inputs@,
    @TO Outputs@, @TO Consequences@, @TO Description@, @TO SeeAlso@, @TO
    Subnodes@, and @TO Caveat@.

    The only keyword which is always required is @TO Key@.

    Each line in the @TO Key@ section is evaluated as a Macaulay2 expression
    to yield a documentation key.  The various types of documentation keys are
    described in @TO Key@.  (If a string is desired as a key, it must be
    surrounded by quotation marks.)

    The bodies of the @TO Headline@ and @TO Usage@ sections should have
    a single line, which will be interpreted as a string.

    The text in an @TO Inputs@ or @TO 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 {\tt 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 @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.

    The text in the @TO Consequences@ section can be marked up as described
    above.

    The text in the @TO Description@ section occurs in subsections labeled with
    the keywords {\bf Text}, {\bf Example}, and {\bf Code}.  The text in a @TO
    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 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 @TO Subnodes@ section not beginning with a colon are keys
    giving links to the subnodes of the current documentation node.  The
    purpose to allow the documentation of the package to be arranged linearly,
    as in a book.  The lines in the @TO Subnodes@ section beginning with a
    colon are subheadings used to classify the subnodes.

    Here is some example code:
   Example
     ourfcn = method()
     ourfcn ZZ := (n) -> (
         n+1)
     ourfcn 3

   Text
    Here is the text used to create this file:
   Code
     EXAMPLE { 
          PRE concatenate between("\n", select(
               lines get(first searchPath "SimpleDoc/doc.txt" | "SimpleDoc/doc.txt"),
               p -> not match("^--",p)))}
  SeeAlso
    document
    "docExample"
    "docTemplate"
    

See also