user_guide:extend:help_formatting

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
reference:help_formatting [2012/04/21 18:27] – [Functions and methods] gawrilowuser_guide:extend:help_formatting [2019/01/29 21:46] (current) – external edit 127.0.0.1
Line 1: Line 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.
  
 ===== Categories ===== ===== Categories =====
-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:+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   # @category Combinatorics
   # Combinatorial dimension   # Combinatorial dimension
Line 11: Line 11:
 Please be careful in spelling the category names; they are compared case-sensitively and without omitting any special characters but superfluous white spaces. 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: +An introductory text for each category must be provided in a separate help block using ''@topic'' notation: 
-  # @topic objects/Cone/properties/Combinatorics +  # @topic category properties/Combinatorics 
-  # a few 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.
  
   ? ''@param'' Type Name text   ? ''@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.+  :: 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 baseplease 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   ? ''@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.   :: 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.
Line 28: Line 43:
   .. If no such tags are specified, the references to option lists occurring in the function signature are automatically included into the help text.   .. 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   ? ''@option'' Type Name text
-  :: Describes an optional keyword parameter.+  :: Describes an optional keyword parameter.  For the //Type//, the same rules as for function parameters apply
   ? ''@return'' Type text   ? ''@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.+  :: 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.
      
 ===== 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 ''%%&oplus;%%'' 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 ===== 
 +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
  • user_guide/extend/help_formatting.1335032831.txt.gz
  • Last modified: 2014/01/03 15:45
  • (external edit)