[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

# cmdr::help(n) 1.3.2 doc "Cmdr, a framework for command line parsing and dispatch"

## Name

cmdr::help - Cmdr - (Internal) Utilities for help text formatting and setup

## Table Of Contents

## Synopsis

- package require cmdr::help

- ::cmdr::help auto actor

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

This internal package implements the four standard help formats

1. full,

2. short,

3. list, and

4. by-category.

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

## API

::cmdr::help auto actor

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

  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 by-category will be used, except if a command name was given to help, then the default will be full.

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

  cmdr::actor actor

    The cmdr::actor instance to be extended with help.

## Format Notes

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

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.

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

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

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

## Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

## Keywords

arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries