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. Categories are introduced “on the fly”, just by ascribing topics to them:

# @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.

You can write an introductory text about each category using a separate help block with @topic notation:

# @topic objects/Cone/properties/Combinatorics
# a few wise words

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 should be one of the known property types or big object types, but can also be any phantasy name which sounds descriptive enough to convey the idea behind it. Name is the name of the parameter under which it should appears 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.

@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.

@option Type Name text

Describes an optional keyword parameter.

@return Type text

Describes the return value. Specifying exact return values 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>, 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.