-- -*- 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:
