<?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>writing documentation</title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_check.html">next</a> | <a href="___T__E__S__T.html">previous</a> | <a href="_check.html">forward</a> | <a href="___T__E__S__T.html">backward</a> | <a href="_creating_spa_sppackage.html">up</a> | <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>
<div><a href="index.html" title="">Macaulay2Doc</a> > <a href="___The_sp__Macaulay2_splanguage.html" title="">The Macaulay2 language</a> > <a href="_packages.html" title="">packages</a> > <a href="_creating_spa_sppackage.html" title="">creating a package</a> > <a href="_writing_spdocumentation.html" title="">writing documentation</a></div>
<hr/>
<div><h1>writing documentation</h1>
<div><h3>Introduction</h3>
Documentation for user defined <a href="_packages.html" title="">packages</a> and Macaulay2 itself is written using the <a href="_document.html" title="package item: documentation node">document</a> function, using a straightforward <a href="_hypertext_splist_spformat.html">hypertext</a> markup language. It is then formatted via <a href="_install__Package.html" title="load and install a package and its documentation ">installPackage</a> as the documentation built in to Macaulay2, the online HTML documentation, and the info pages. Much of the format and structure of the documentation is automatically generated. Each documentation entry must be part of a package, and occur after the <a href="_begin__Documentation.html" title="package item: start documentation section">beginDocumentation</a> section of the package.<h3>Documentation templates</h3>
Each documentation entry is either an overview topic, or documentation of an individual feature, such as a symbol, a function name, a function call (that is, a function name, together with specific types of its arguments), an optional argument to a function, or a package<p/>
The easiest way to write documentation for an entry is to start with one of the following examples or templates, and then modify it.<ul><li>package header <a href="_package_spdocumentation_sptemplate.html">template</a></li>
<li>function name <a href="_function_spname_spdocumentation_sptemplate.html">template</a></li>
<li>function call (includes classes of function arguments) <a href="_function_spdocumentation_sptemplate.html">template</a></li>
<li>optional argument name <a href="_optional_spargument_spname_spdocumentation_sptemplate.html">template</a></li>
<li>optional argument <a href="_optional_spargument_spdocumentation_sptemplate.html">template</a></li>
<li>overview <a href="_overview_spdocumentation_sptemplate.html">template</a></li>
</ul>
<h3>The documentation writing cycle</h3>
Start with the package that you wish to document, and select one, or several of the above examples or templates. Cycle through the following steps as you refine your documentation.<ul><li>edit your doc entries as desired</li>
<li>generate the html pages for your package, using e.g., <pre>installPackage("yourPackage")</pre>
A link to your package documentation is placed in the <tt>index.html</tt> file in the directory <a href="_application__Directory.html">applicationDirectory()</a></li>
<li>view your html using your favorite web browser, or use <a href="_view__Help.html" title="view online doc with a web browser">viewHelp</a> as in e.g., <pre>viewHelp "doc entry name"</pre>
which displays this page in your browser.</li>
</ul>
<h3>Documentation style conventions</h3>
There are a few stylistic conventions that should be noted:<ul><li>Lowercase is used for all titles, unless a proper noun is being used.</li>
<li>The name of any Macaulay2 function, option, or variable, occurring in the documentation should be an active hyperlink. This can be accomplished with the tag <a href="../../Text/html/___T__O.html" title="hypertext documentation link">TO</a>.</li>
<li>If one needs to refer to the <tt>i</tt>-th coefficient of some object, then use the format as given here.</li>
</ul>
</div>
<div class="single"><h2>See also</h2>
<ul><li><span><a href="_document.html" title="package item: documentation node">document</a> -- package item: documentation node</span></li>
<li><span><a href="_hypertext_splist_spformat.html" title="">hypertext list format</a></span></li>
<li><span><a href="___S__Y__N__O__P__S__I__S.html" title="">SYNOPSIS</a></span></li>
</ul>
</div>
</div>
</body>
</html>
