writing documentation

Introduction

Documentation for user defined packages and Macaulay 2 itself is written using the document function, using a straightforward hypertext markup language. It is then formatted via installPackage as the documentation built in to Macaulay 2, 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 beginDocumentation section of the package.

Documentation templates

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

The easiest way to write documentation for an entry is to start with one of the following examples or templates, and then modify it.

• package header template, example
• function name template, example
• function call (includes classes of function arguments) template, example
• optional argument name template, example
• optional argument template, example
• overview template, example

The documentation writing cycle

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.

• edit your doc entries as desired
• generate the html pages for your package, using e.g.,

  installPackage("yourPackage")

  A link to your package documentation is placed in the index.html file in the directory applicationDirectory()
• view your html using your favorite web browser, or use viewHelp as in e.g.,

  viewHelp "doc entry name"

  which displays this page in your browser.

Documentation style conventions

There are a few stylistic conventions which should be noted:

• Lowercase is used for all titles, unless a proper noun is being used.
• The name of any Macaulay 2 function, option, or variable, occurring in the documentation should be an active hyperlink. This can be accomplished with the tag TO.
• If one needs to refer to the i-th coefficient of some object, then use the format as given here.