| Both sides previous revision Previous revision Next revision | Previous revision |
| reference:help_formatting [2017/02/07 07:10] – [Functions and methods] gawrilow | user_guide:extend:help_formatting [2019/01/29 21:46] (current) – external edit 127.0.0.1 |
|---|
| ====== Formatting Help Blocks ====== | ====== 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 [[clients#connection to perl|C++ clients]]), preference labels, custom variables, and option lists. | 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 [[user_guide:extend:clients#connection to perl|C++ clients]]), preference labels, custom variables, and option lists. |
| |
| Besides this, arbitrary topics can be inserted into the help system using the special [[rulefiles#credits and help|@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. | Besides this, arbitrary topics can be inserted into the help system using the special [[rulefiles#credits and help|@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. |
| # some wise words | # 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. |
| ===== Functions and methods ===== | ===== Functions and methods ===== |
| 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. | 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. |
| | |
| ===== Markup ===== | ===== Markup ===== |
| 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. | 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. |
| ===== Examples ===== | ===== Examples ===== |
| 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. | 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. |