Formatting Help Blocks

For many items defined in the rulefiles, short descriptive texts can (and ought to) be placed immediately above the definition in form of comment blocks. These texts are “automagically” gathered by polymake and made available to the users of the interactive shell by the means of help command; they can also be transformed into HTML pages which then become part of the official release documentation. Currently the following definitions can be accompanied by help blocks: “big” object types, their properties and property types, user functions and methods (including those embedded in C++ clients), preference labels, custom variables, and option lists.

Besides this, arbitrary topics can be inserted into the help system using the special @topic notation in the first line of the comment block. For example, @topic application titles a text describing the application as a whole; usually this block is located in the application's main.rules or help.rules. Repeating occurrences of text blocks ascribed to the same topic are concatenated together.

All help topics of similar kind are kept as siblings in the tree-like hierarchy; for example, all texts about “big” object types will be collected under /objects, and all properties of a “big” object under /objects/OBJECT_TYPE/properties. In order to increase the legibility of large collections of related topics, you may introduce categories which then are inserted as an intermediate level of the help hierarchy.

# @category Combinatorics
# Combinatorial dimension
property COMBINATORIAL_DIM : Int;

Please be careful in spelling the category names; they are compared case-sensitively and without omitting any special characters but superfluous white spaces.

An introductory text for each category must be provided in a separate help block using @topic notation:

# @topic category properties/Combinatorics
# some wise words

Universal category descriptions may be provided as fallbacks; they are distinguished by the wildcard keyword “any” appearing at the beginning or in the middle of the topic path:

# @topic category any/Combinatorics
# These +++ capture combinatorial information of the object. 

provides the text for all missing categories /functions/Combinatorics, /objects/XXX/properties/Combinatorics, /objects/XXX/methods/Combinatorics and so on; the topic path element matching “any” will be substituted for “+++” - in this example it will be “properties” or “methods”

# @topic category methods/any/Topology
# The following methods compute topological invariants.

provides the fallback for /objects/XXX/methods/Topology only.

Application “common” provides several descriptions of this kind in the file global_categories.rules.

Descriptions of user functions and methods have a richer structure compared to other help blocks. They can contain additional tags designating descriptions of single arguments, options, or return values. Adhering to javadoc/doxygen custom, the tags are introduced with symbol @ and must stand at the beginning of a line; the text belonging to a tag may stretch over several lines up to the next tagged line or the end of the entire help block.

@param Type Name text

Describes a positional parameter of the function. Type must be one of the known property types or big object types; if the function accepts a variety of types not having a formal common base, please use one of the generic names SCALAR, ARRAY, HASH, CODE, or Any. Name is the name of the parameter under which it should appear in the human-readable representation of the signature. The order of @param lines must correspond to the actual order of the parameters in the signature.

@value Name Value text

Provides an allowed value for a parameter Name, which must be introduced beforehand. Value should be a named constant belonging to an enumeration type or a string literal.

@tparam Name text

Describes a template parameter; should be normally used for those template parameter which are to be specified explicitly in the call rather than deduced from the arguments.

@options text

Introduces a group of related keyword parameters. Must be followed by a sequence of @option lines.

@options %global_option_list

Tells that this function accepts keyword parameters declared in a named option list. When the function accepts several option lists, they should be listed on separate lines of this kind.

If no such tags are specified, the references to option lists occurring in the function signature are automatically included into the help text.

@option Type Name text

Describes an optional keyword parameter. For the Type, the same rules as for function parameters apply.

@return Type text

Describes the return value. Specifying exact return types of functions creating “big” objects is important, because it allows to offer TAB completion in complex expressions involving calls to such functions.

A modest markup is allowed in the texts, faintly resembling the syntax of Wiki you are just reading: //italics//, **bold**, __underlined__, simple HTML tags like <sub>index</sub> or <sup>power</sup>, mathematical symbol entities like ⊕ as well as references to other [[topics]] or [[wiki:page#anchor|Wiki pages]] . You should use them sparingly, however, because they can clutter the on-screen presentation and even render it completely illegible.

Help blocks may contain examples illustrating typical use cases or clarifying the exact semantics. In particular, documentation of functions and properties which are likely to be looked at by beginners should be accompanied with easy to understand examples. The examples should be valid perl/polymake commands which could be copied verbatim into the interactive shell and executed. If appropriate, an example can contain the response expected to appear on the screen.

An example within a help block has the following format:

# @example Some introductory text
# more text
# > command;
# > another command;
# | expected output
# | which can span over several lines
# continued explanations
# > one more command;
# | its expected output
# ...

More formally an example is a repeating sequence of free text lines, command input, and expected output, where the only mandatory part is the command input. All commands within an example comprise a single script, so that a variable introduced in the first command line may be referred to in subsequent commands. A help block may also contain several examples, but every example must be self-contained.

Code examples are automatically verified every time the polymake testsuite is run. The commands are executed as if entered in the interactive shell, and the produced output is compared verbatim with the expected one; only trailing white spaces and empty lines are ignored. Some examples can provide hints for the execution. The hints are placed in square brackets immediately after the tag @example; they stay invisible for the user and do not appear on the generated documentation pages. Currently, the following hints are recognized:

[prefer LABEL]

execute prefer_now "LABEL"; at the beginning; useful for examples whose output may depend on the executed production rules

[application APPNAME]

temporarily switch to another application because the example contains commands defined in that application which is not imported into the current one

[nocompare]

do not compare the produced output with the expected one because the latter is incomplete or subject to random changes like an unordered set

[notest]

exempt the example from verification altogether; should only be used in exceptional cases because the untested example may quickly become outdated and thus misleading for users