This is SimpleDoc.info, produced by Macaulay2, version 1.4

SimpleDoc -- simpler documentation for functions and methods
************************************************************

Authors
=======

  * Dan Grayson <dan@math.uiuc.edu>
  * Mike Stillman <mike@math.cornell.edu>

Version
=======

This documentation describes version 1.1 of SimpleDoc.

Source code
===========

The source code from which this documentation is derived is in the file
SimpleDoc.m2.  The auxiliary files accompanying it are in the directory
SimpleDoc/.

Exports
=======

  * Functions and commands
      * doc -- a simple documentation function
      * multidoc -- a simple documentation function, allowing
        multiple documentation nodes
      * packageTemplate -- a template for a package
      * simpleDocFrob -- an example of a function to
        document
  * Other things
      * docExample -- an example documentation node
      * docTemplate -- a template for a documentation node

doc -- a simple documentation function
**************************************

Synopsis
========

  * Usage:doc s
  * Inputs:
      * s, a string (Macaulay2Doc), See the example below for the
        format of {\tt s}
  * Consequences:
      * Documentation is created and stored so that after installPackage (Macaulay2Doc),
        or getPackage (Macaulay2Doc),
        is used, the corresponding
        documentation is available via help (Macaulay2Doc), and
        viewHelp (Macaulay2Doc),

Description
===========

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 document(..., Key => ...) (Macaulay2Doc).
(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 TEX (Text),;
for details and examples see html(TEX) (Text), 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 PRE (Text). 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 document (Macaulay2Doc).

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.

See also
========

  * multidoc -- a simple documentation function, allowing
    multiple documentation nodes
  * document (Macaulay2Doc) -- package item: documentation node
  * docExample -- an example documentation node
  * docTemplate -- a template for a documentation node

Ways to use doc :
=================

  * doc(String)

docExample -- an example documentation node
*******************************************

Synopsis
========

  * Usage:docExample

Description
===========

The variable docExample is a String (Macaulay2Doc), containing an
example of the use of doc(String), to write a documentation page,
visible here.

+-----------------------------------------------------------------------------+
|i1 : docExample                                                              |
|                                                                             |
|o1 = doc ///                                                                 |
|       Key                                                                   |
|         (simpleDocFrob,ZZ,Matrix)                                           |
|       Headline                                                              |
|         a sample documentation node                                         |
|       Usage                                                                 |
|         x = simpleDocFrob(n,M)                                              |
|       Inputs                                                                |
|         n:ZZ                                                                |
|           positive                                                          |
|         M:Matrix                                                            |
|           which is square                                                   |
|       Outputs                                                               |
|         x:Matrix                                                            |
|           A block diagonal matrix with {\tt n}                              |
|           copies of {\tt M} along the diagonal                              |
|       Consequences                                                          |
|        Item                                                                 |
|         The first side effect of the function, if any, is described here.   |
|        Item                                                                 |
|         The second side effect of the function is described here, and so on.|
|       Description                                                           |
|        Text                                                                 |
|          Each paragraph of text begins with "Text".  The following          |
|          line starts a sequence of Macaulay2 example input lines.           |
|          However, see @TO (matrix,List)@.                                   |
|        Example                                                              |
|          M = matrix"1,2;3,4";                                               |
|          simpleDocFrob(3,M)                                                 |
|        Text                                                                 |
|          See @ TO "docExample" @ for the code used to create this documentat|
|       Caveat                                                                |
|         This is not a particularly useful function.                         |
|       SeeAlso                                                               |
|         matrix                                                              |
|         (directSum,List)                                                    |
|     ///                                                                     |
|-----------------------------------------------------------------------------|
|ion.                                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * docTemplate -- a template for a documentation node

For the programmer
==================

The object docExample, is a string (Macaulay2Doc).

multidoc -- a simple documentation function, allowing multiple documentation nodes
**********************************************************************************

Synopsis
========

  * Usage:multidoc s
  * Inputs:
      * s, a string (Macaulay2Doc),
  * Consequences:
      * The string {\tt s} is handled by parsing it the same way 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 doc, resulting in a documentation
        node.

Description
===========

Here is the input submitted to multidoc, to document (most of)
this package:

+-----------------------------------------------------------------------------+
|-- -*- 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, |
|   expecting the least indented keyword to be {\bf Node}, which can occur    |
|   multiple times.  The text following each such keyword is handled just as b|
|   TO doc @, resulting in a documentation node.                              |
| Description                                                                 |
|  Text                                                                       |
|   Here is the input submitted to @ TO multidoc @ to document (most of) this |
|  Code                                                                       |
|   EXAMPLE { PRE concatenate between("\n", lines get(SimpleDoc#"source direct|
|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 produ|
|                                                                             |
|    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 Inpu|
|    {\bf Outputs}, {\bf Consequences}, {\bf Description}, {\bf SeeAlso}, {\bf|
|                                                                             |
|    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 ar|
|    described in @TO [document,Key]@.  (If a string is desired as a key, it m|
|    surrounded by quotation marks.)                                          |
|                                                                             |
|    The body of the {\bf Headline} section should have a single line, which w|
|    The lines of the {\bf Usage} section may be used to present alternative u|
|                                                                             |
|    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 li|
|    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, an|
|    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 t|
|    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 w|
|    the keywords {\bf Text}, {\bf Example}, {\bf Pre}, and {\bf Code}.  The  |
|    text in a {\bf Text} subsection can be separated into paragraphs with bla|
|    lines.  Each paragraph can contain markup as described above.  The text i|
|    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 li|
|    of documentation items at the appropriate point before passing the list t|
|    @TO document@.                                                           |
|                                                                             |
|    The lines in the {\bf Subnodes} section not beginning with a colon are ke|
|    giving links to the subnodes of the current documentation node.  The     |
|    purpose is to allow the documentation of the package to be arranged linea|
|    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=SimpleDo|
|-- End:                                                                      |
|-----------------------------------------------------------------------------|
|but                                                                          |
|                                                                             |
|y @                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|package:                                                                     |
|                                                                             |
|ory" | "SimpleDoc/doc.txt")) }                                               |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ced.                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ts},                                                                         |
| Subnodes}, and {\bf Caveat}.                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|e                                                                            |
|ust be                                                                       |
|                                                                             |
|                                                                             |
|ill be interpreted as a string.                                              |
|sages, and they will be collected into a single string.                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ne                                                                           |
|                                                                             |
|d                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o                                                                            |
|@}                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ith                                                                          |
|                                                                             |
|nk                                                                           |
|n                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|.                                                                            |
|                                                                             |
|st                                                                           |
|o                                                                            |
|                                                                             |
|                                                                             |
|ys                                                                           |
|                                                                             |
|rly,                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|c RemakePackages=true RemakeAllDocumentation=true IgnoreExampleErrors=false  |
|-----------------------------------------------------------------------------|
|RerunExamples=true"                                                          |
+-----------------------------------------------------------------------------+

Ways to use multidoc :
======================

  * multidoc(String)

packageTemplate -- a template for a package
*******************************************

Synopsis
========

  * Usage:packageTemplate s
  * Inputs:
      * s, a string (Macaulay2Doc), the name of the package

Description
===========

This routine returns a barebones package template that you can use to start
writing a package.

+---------------------------------------------+
|i1 : print packageTemplate "WonderfulModules"|
|                                             |
|newPackage(                                  |
|        "WonderfulModules",                  |
|        Version => "0.1",                    |
|        Date => "",                          |
|        Authors => {{Name => "",             |
|                  Email => "",               |
|                  HomePage => ""}},          |
|        Headline => "",                      |
|        DebuggingMode => true                |
|        )                                    |
|                                             |
|export {}                                    |
|                                             |
|-- Code here                                 |
|                                             |
|beginDocumentation()                         |
|                                             |
|doc ///                                      |
|Key                                          |
|  WonderfulModules                           |
|Headline                                     |
|Description                                  |
|  Text                                       |
|  Example                                    |
|Caveat                                       |
|SeeAlso                                      |
|///                                          |
|                                             |
|doc ///                                      |
|Key                                          |
|Headline                                     |
|Usage                                        |
|Inputs                                       |
|Outputs                                      |
|Consequences                                 |
|Description                                  |
|  Text                                       |
|  Example                                    |
|  Code                                       |
|  Pre                                        |
|Caveat                                       |
|SeeAlso                                      |
|///                                          |
|                                             |
|TEST ///                                     |
|-- test code and assertions here             |
|-- may have as many TEST sections as needed  |
|///                                          |
+---------------------------------------------+

See also
========

  * docExample -- an example documentation node

Ways to use packageTemplate :
=============================

  * packageTemplate(String)

docTemplate -- a template for a documentation node
**************************************************

Synopsis
========

  * Usage:docTemplate

Description
===========

docTemplate is a String (Macaulay2Doc), 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.

+----------------------+
|i1 : print docTemplate|
|                      |
|doc ///               |
|   Key                |
|   Headline           |
|   Usage              |
|   Inputs             |
|   Outputs            |
|   Consequences       |
|    Item              |
|   Description        |
|    Text              |
|    Code              |
|    Pre               |
|    Example           |
|   Subnodes           |
|   Caveat             |
|   SeeAlso            |
|///                   |
+----------------------+

See also
========

  * docExample -- an example documentation node

For the programmer
==================

The object docTemplate, is a string (Macaulay2Doc).

simpleDocFrob -- an example of a function to document
*****************************************************

Ways to use simpleDocFrob :
===========================

  * simpleDocFrob(ZZ,Matrix) -- a sample
    documentation node

simpleDocFrob(ZZ,Matrix) -- a sample documentation node
*******************************************************

Synopsis
========

  * Usage:x = simpleDocFrob(n,M)
  * Function: simpleDocFrob,
  * Inputs:
      * n, an integer (Macaulay2Doc), positive
      * M, a matrix (Macaulay2Doc), which is square
  * Outputs:
      * x, a matrix (Macaulay2Doc), A block diagonal matrix with
        {\tt n} copies of {\tt M} along the diagonal
  * Consequences:
      * The first side effect of the function, if any, is described here.
      * The second side effect of the function is described here, and so on.

Description
===========

Each paragraph of text begins with "Text".  The following line starts a
sequence of Macaulay2 example input lines. However, see matrix(List) (Macaulay2Doc).

+-------------------------+
|i1 : M = matrix"1,2;3,4";|
|                         |
|              2        2 |
|o1 : Matrix ZZ  <--- ZZ  |
+-------------------------+
|i2 : simpleDocFrob(3,M)  |
|                         |
|o2 = | 1 2 0 0 0 0 |     |
|     | 3 4 0 0 0 0 |     |
|     | 0 0 1 2 0 0 |     |
|     | 0 0 3 4 0 0 |     |
|     | 0 0 0 0 1 2 |     |
|     | 0 0 0 0 3 4 |     |
|                         |
|              6        6 |
|o2 : Matrix ZZ  <--- ZZ  |
+-------------------------+

See docExample, for the code used to create this
documentation.

Caveat
======

This is not a particularly useful function.

See also
========

  * matrix (Macaulay2Doc) -- make a matrix
  * directSum(List) (Macaulay2Doc) -- direct sum of modules or
    maps