| Both sides previous revision Previous revision Next revision | Previous revision |
| reference:help_formatting [2017/02/07 07:25] – [Categories] universal 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. |
| | |
| ===== 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. |