<?xml version="1.0" encoding="utf-8" ?> <!-- for emacs: -*- coding: utf-8 -*- -->
<!-- Apache may like this line in the file .htaccess: AddCharset utf-8 .html -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg-flat.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>doc(String) -- a simple documentation function</title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_doc__Example.html">next</a> | <a href="index.html">previous</a> | <a href="_doc__Example.html">forward</a> | <a href="index.html">backward</a> | up | <a href="index.html">top</a> | <a href="master.html">index</a> | <a href="toc.html">toc</a> | <a href="http://www.math.uiuc.edu/Macaulay2/">Macaulay2 web site</a></div>
</td>
</tr>
</table>
<hr/>
<div><h1>doc(String) -- a simple documentation function</h1>
<div class="single"><h2>Synopsis</h2>
<ul><li><div class="list"><dl class="element"><dt class="heading">Usage: </dt><dd class="value"><div><tt>doc s</tt></div>
</dd></dl>
</div>
</li>
<li><span>Function: <a href="_doc_lp__String_rp.html" title="a simple documentation function">doc</a></span></li>
<li><div class="single">Inputs:<ul><li><span><tt>s</tt>, <span>a <a href="../../Macaulay2Doc/html/___String.html">string</a></span>, See the example below for the format of <tt>s</tt></span></li>
</ul>
</div>
</li>
<li><div class="single">Consequences:<ul><li><div>Documentation is created and stored so that after <a href="../../Macaulay2Doc/html/_install__Package.html" title="load and install a package and its documentation ">installPackage</a> or <a href="../../Macaulay2Doc/html/_get__Package_lp__String_rp.html" title="download a package from the repository">getPackage</a> is used, the corresponding documentation is available via <a href="../../Macaulay2Doc/html/_help.html" title="help command">help</a> and <a href="../../Macaulay2Doc/html/_view__Help.html" title="view online doc with a web browser">viewHelp</a></div>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="single"><h2>Description</h2>
<div><p></p>
<p>The text used to create the documentation node you are currently reading is displayed below.</p>
<p>The string <tt>s</tt> contains text describing the documentation to be produced.</p>
<p>Lines beginning with two hyphens are ignored.</p>
<p>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.</p>
<p>The valid keywords are: <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Key_sp_eq_gt_sp..._rp.html" title="key of a documentation node">Key</a>, <a href="../../Macaulay2Doc/html/___Headline.html" title="make a headline for a documentation node">Headline</a>, <a href="../../Macaulay2Doc/html/___Usage.html" title="shows the usage of a function">Usage</a>, <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Inputs_sp_eq_gt_sp..._rp.html" title="inputs for a function">Inputs</a>, <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Outputs_sp_eq_gt_sp..._rp.html" title="outputs for a function">Outputs</a>, <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Consequences_sp_eq_gt_sp..._rp.html" title="side-effects of a function">Consequences</a>, <a href="../../Macaulay2Doc/html/___Description.html" title="name for an optional argument">Description</a>, <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__See__Also_sp_eq_gt_sp..._rp.html" title="crossreferences in documentation">SeeAlso</a>, <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Subnodes_sp_eq_gt_sp..._rp.html" title="a menu of documentation nodes">Subnodes</a>, and <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Caveat_sp_eq_gt_sp..._rp.html" title="warnings">Caveat</a>.</p>
<p>The only keyword which is always required is <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Key_sp_eq_gt_sp..._rp.html" title="key of a documentation node">Key</a>.</p>
<p>Each line in the <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Key_sp_eq_gt_sp..._rp.html" title="key of a documentation node">Key</a> section is evaluated as a Macaulay2 expression to yield a documentation key. The various types of documentation keys are described in <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Key_sp_eq_gt_sp..._rp.html" title="key of a documentation node">Key</a>. (If a string is desired as a key, it must be surrounded by quotation marks.)</p>
<p>The bodies of the <a href="../../Macaulay2Doc/html/___Headline.html" title="make a headline for a documentation node">Headline</a> and <a href="../../Macaulay2Doc/html/___Usage.html" title="shows the usage of a function">Usage</a> sections should have a single line, which will be interpreted as a string.</p>
<p>The text in an <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Inputs_sp_eq_gt_sp..._rp.html" title="inputs for a function">Inputs</a> or <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Outputs_sp_eq_gt_sp..._rp.html" title="outputs for a function">Outputs</a> 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</tt>. The variable name and type are both optional. Subsequent lines of the subsection, indented further, describe the variable. These lines may include markup.</p>
<p>Markup allowed includes many TeX commands, as allowed in <a href="../../Text/html/___T__E__X.html" title="hypertext TEX item">TEX</a>; for details and examples see <a href="../../Text/html/_html_lp__T__E__X_rp.html" title="conversion of TeX to html">html(TEX)</a>, allowing various mathematical expressions, such as <i>ℙ<sup>3</sup></i> or <i>x<sub>i</sub><sup>33</sup> + 1/2</i>, to be displayed in the html form of the documentation. Also allowed is a pair of <tt>@</tt> characters, enclosing Macaulay2 code to be executed, yielding appropriate hypertext. For example, <tt>@TO Key@</tt> will insert a link to another node of the documentation.</p>
<p>The text in the <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Consequences_sp_eq_gt_sp..._rp.html" title="side-effects of a function">Consequences</a> section can be marked up as described above.</p>
<p>The text in the <a href="../../Macaulay2Doc/html/___Description.html" title="name for an optional argument">Description</a> section occurs in subsections labeled with the keywords <b>Text</b>, <b>Example</b>, and <b>Code</b>. The text in a <a href="../../Text/html/index.html" title="">Text</a> subsection can be separated into paragraphs with blank lines. Each paragraph can contain markup as described above. The text in an <b>Example</b> 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 <b>Code</b> 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 <a href="../../Macaulay2Doc/html/_document.html" title="package item: documentation node">document</a>.</p>
<p>The lines in the <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Subnodes_sp_eq_gt_sp..._rp.html" title="a menu of documentation nodes">Subnodes</a> 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 <a href="../../Macaulay2Doc/html/_document_lp..._cm_sp__Subnodes_sp_eq_gt_sp..._rp.html" title="a menu of documentation nodes">Subnodes</a> section beginning with a colon are subheadings used to classify the subnodes.</p>
<div>Here is some example code:</div>
<table class="examples"><tr><td><pre>i1 : ourfcn = method()
o1 = ourfcn
o1 : MethodFunction</pre>
</td></tr>
<tr><td><pre>i2 : ourfcn ZZ := (n) -> (
n+1)
o2 = {*Function[stdio:2:17-3:6]*}
o2 : FunctionClosure</pre>
</td></tr>
<tr><td><pre>i3 : ourfcn 3
o3 = 4</pre>
</td></tr>
</table>
<div>Here is the text used to create this file:</div>
<table class="examples"><tr><td><pre>
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"
</pre>
</td></tr>
</table>
</div>
</div>
<div class="single"><h2>See also</h2>
<ul><li><span><a href="../../Macaulay2Doc/html/_document.html" title="package item: documentation node">document</a> -- package item: documentation node</span></li>
<li><span><a href="_doc__Example.html" title="an example documentation node">docExample</a> -- an example documentation node</span></li>
<li><span><a href="_doc__Template.html" title="a template for a documentation node">docTemplate</a> -- a template for a documentation node</span></li>
</ul>
</div>
</div>
</body>
</html>
