Reference Manual Style Guide

The following style rules should be followed for all new reference manual entries. See the Reference Manual Template page for starting a new reference entry and Example Markup for a quick reference example of each of the typically used markups.

Main Sections

Section titles are wrapped with three equal signs, for example:

===Synopsis===

and can include the following (note that this is also the order that these sections should appear in the body of the page:

Purpose (*) - short description of function purpose (from H1 line in m-file)

Synopsis (*) - I/O of use. Do NOT include calls to retrieve options, demo, or help

Description (*) - detailed description of use of function

Options - bulleted list of options

Algorithm - detailed description of algorithm used by function

Examples - brief code examples of how to use function (reserve long examples for demo)

See Also (*) - list of related functions

(*) = required segment

Notes

• Include links to other functions or pages by providing the function name / page name in double square brackets:

[[pca]]

• In all narratives, separate paragraphs by including an additional blank line between them:

This is paragraph one.

        blank line

This is paragraph two.

        blank line

Description Sub-Topics

Some standard sub-topics can be used in the Description section. These sub-topic titles are wrapped with four equal signs, for example:

====Inputs====

and include:

Inputs

Optional Inputs

Outputs

Notes

• The contents of these sections should be given as bulleted lists (i.e. start each line with an asterisk * ) with each input/output as a separate item in the list.
• Input/output name should be bolded (i.e. surround with triple single quotes '''data'''
• Follow the name with an equal sign and the concise description of the input/output:
• Lists of possible values for a given input/output should be given using indenting (i.e. start the line with a colon : ) or using sub-bulleted lists (i.e. start the line with double asterisks ** )
• These sub-topics are always plural, even if there is only one item in the list (e.g. one output)

Example

*'''data''' = data matrix to be analyzed

• data = data matrix to be analyzed

Options

Options are listed as bulleted lists (i.e. start each line with an asterisk * )

Notes

• Name of option must be in bold (i.e. surround with triple single quotes '''display'''
• Follow immediately by a colon : and then either the default value or the possible values (for fixed-option strings):
  • Double [ 3 ]
  • Empty [ ]
  • Fixed-option double [ 1 |{2}] (default shown with { } )
  • Fixed-option string [ 'off' |{'on'}] (default shown with { } )
• Complete the option line with a concise description of the option
• If necessary, lists of possible values for a given option should be given using indenting (i.e. start the line with a colon : ) or using sub-bulleted lists (i.e. start the line with double asterisks ** )

Example

* '''plots''': ['none' | {'final'} ] Governs plotting.

• plots: ['none' | {'final'} ] Governs plotting.

Matlab Code

Matlab code can be included in the body of the description using either:

1. Indenting (i.e. start line with a semicolon) - use for Synopsis section and for single lines of code in description

:model = pca(data,3)

2. Preformatted code using one of the methods below - use any time there are multiple lines of associated code shown together

2a. start line with one or more space characters

2b. wrap code in a <pre> </pre> tag.

2c. if you need mono spaced text within the body of normal text use the <tt> </tt> (teletype) tag.

Example

<pre>

opts = pca('options');

opts.plots = 'none';

model = pca(data,3,opts);

</pre>

     opts = pca('options');
     opts.plots = 'none';
     model = pca(data,3,opts);

See Also

• See Also section should list related and similar functions
• List should be in alphabetical order
• Each item is a link to the function (enclose function names in double square brackets)

Example

[[analysis]], [[corrmap]], [[gcluster]], [[simca]]

analysis, corrmap, gcluster, simca