Artifact Content
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Artifact 8883918a90b2e2b3ceb90ff378b24a60377c9133:

[comment {-*- tcl -*- doctools manpage}]
[include parts/]
[vset VERSION 1.3.2]
[manpage_begin [vset LABEL_HELP] [vset MAN_SECTION] [vset VERSION]]
[include parts/]
[require cmdr::help]
[titledesc [vset TITLE_HELP]]
[include parts/]

This internal package implements the four standard help formats

[list_begin enumerated]
[enum] [const full],
[enum] [const short],
[enum] [const list], and
[enum] [const by-category].

[para] It provides a single utility command used by the other parts of
the framework to add a [syscmd help] command to any
[package cmdr::actor] requiring such.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::help] [method auto] [arg actor]]

When invoked this command extends the [arg actor] with a [const help]
command. The result of the command is the empty string.

[para] The inserted command will accept all known format names as
options, enabling the user to choose the form of the help. By default
the format [const by-category] will be used, except if a command name
was given to [syscmd help], then the default will be [const full].

[para] An additional option accepted by [syscmd help] is
[const --width], giving the user control over the length of lines
in the help. By default help will be formatted to the width of the

[list_begin arguments]
[arg_def [package cmdr::actor] actor]
The [package cmdr::actor] instance to be extended with [syscmd help].

[section {Format Notes}]

The format [const by-category] looks for and uses the block
[const *category-order*] for when the user wishes to override the
natural (alphabetical) order of display for the toplevel sections.

[para] This block has to be defined by the user, in the root of
the command hierarchy.

Its value has to be a dictionary mapping from the names of toplevel
sections/categories to an integer number. This is used to change
the order of displaying these sections in the generated text.

[para] Sections with higher/larger numbers are shown first, and
lower/smaller numbers move towards the end. Negative numbers are

[para] Sections not mentioned in the dictionary are assigned their
natural number. This is calculated by sorting all sections
alphabetically ([option -dict]) ascending and assigning [const 0]
to the first section, [const -10] to the next, and so on.

[para] The generated section/category [const Miscellaneous] is
given the number [const -10000] to force it to the end (bottom)
of the help text, if it was generated.

[include parts/]