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.
Contents |
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]]