-- -*- 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}, {\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.  Each paragraph can contain markup as
    described above.  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"
