  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 string {\tt s} contains text describing the
    documentation to be produced.

    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@, and @TO
    Caveat@.

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

    Each line in the @TO Key@ section is evaluated as a Macaulay 2 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 Macaulay 2 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 @TO Text@ and {\tt Example}.  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 {\tt
    Example} subsection consists of lines of code to be used as examples in the
    documentation node.

    The following example is not complete yet, as we are writing this
    documentation node using ", TO "doc", ", and multi-line example code
    is not yet implemented to allow writing a better example.

   Example
     ourfcn = method()
     ourfcn ZZ := (n) -> n+1;
     ourfcn 3

  SeeAlso
    document
    "docExample"
    "docTemplate"
