Content-type: text/html Manpage of HELP2SIMPLE.PL

HELP2SIMPLE.PL

Section: User Commands (1)
Updated: May 2002
Index Return to Main Contents

NAME

help2simple.pl - manual page for help2simple.pl tool to parse command usage information to generate ZSH completion functions.

SYNOPSIS

help2simple.pl -c command_name

DESCRIPTION

Use help2simple.pl to parse another program's usage information (as is typically generated by one of the flags "-h", "--help", "-u") to generate an xml version of the same information. You can easily convert this XML output into a ZSH completion function. Details can be found at: http://www.oocities.org/f_rosencrantz/xml_completion.htm

There is no standard format for usage information. So there are many different formats and styles that are used. Help2simple.pl's parsing attempts to match a common style, but will have problems with the usage of many commands. To improve results you may need to pre-edit usage information before passing it to help2simple.pl.

Help2simple.pl expects it's input to be provided either as stdin or as a filename on the command line. Many times a command will print usage information to stderr, in which case you need to save stderr to a file or redirect stderr (by adding a '2>&1' redirection modifier.)

OPTIONS

-c command_name: Use this flag to specify the name of the command to be completed, this will be used to generate the name of the completion function. It's value is also used to generate unique names needed to create the completion function.
-u: Use this flag to get help2simple.pl usage information.
-pyx: Use this flag to get the output in PYX format. PYX is a line-oriented notation that can be easily converted to XML. The line format allows the XML to be more easily processed with Unix-style filters.

Flag Completion Properties

-m: Use this flag to say that all the flags of the command line to be completed are allowed more than once. This will cause the generated completion function to complete the same flag more than once. By default, flags that are already listed on the command line are not offered as completion choices. Use the -M flag if only some flags are allowed to be used more than once.
-M flag_comma_list: Comma separated list of flags that can used multiple times on a command line. Use this when a only a subset of the flags can be used more than once on a command line. Use the "-m" flag if all flags can be completed more than once.
-x flag_comma_list: Comma separated list of flags that are exclusive to one another. Use this flag to specify a group of flags that are exclusive to one another. If one (or more) of any of these flags (or their aliases) are already specified on the command line then none of the other flags (or their aliases) in this list will be offered as completion choices. Sometimes a flag has a short and long form (e.g. -h and --help), these are considered aliases.

Regular Argument Properties

-a argtag

Use this flag to specify arguments of the command to be completed. The argument for this flag is the name of argtag to use for that position. This flag can be used more than once. Arguments are assumed to be in the order specified on the help2simple.pl command line.

Help2simple.pl is unable to parse usage lines, so it isn't able to determine what the arguments to a command are, so it must be told about any arguments with this flag.

Help2simple.pl understands some simple syntax for argtag that allows you to directly specify the type of action that should be used for this argument. It understands several different formats: an argtag beginning with '((' and ending with '))' has fixed strings with explanations; an argtag enclosed in single parentheses is a list of fixed strings; an argtag starting with a space or underscore is considered to be an action; an argtag starting with "->" is considered a state"; an argtag starting with "::" means that we should use "normal_word_args". If the argtag doesn't contain any special formatting, it defaults to being just a tagname.

A tagname is an indirect method of providing a completion action. The process of converting the XML output of this command to the actual completion function will use the tagname as a look up string in a user supplied "<command_name>_defaults.xml" file. The defaults file is useful when a command has regular updates with new flags or arguments. You can run help2simple.pl on the new version, and re-use previously determined actions. Also, a defaults file can be useful when you are dealing with a suite of commands that have a consistent set of flags are arguments.

If the defaults file doesn't provide an action for the tagname, a default action will be used depending on options provided to the conversion script. For example, the conversion script might use the tagname as a state.

Parsing Modifiers

-p flag_prefix

Use this flag when the usage text help2simple.pl is parsing contains flags with arguments that are not separated by a space, and the -S flag cannot be used (e.g. some long options begin with a single dash.) The flag_prefix should be the name of the flag (e.g. '-w'), anything after this prefix will be considered the argument.

-S

Use this flag to say that all flags in the usage text beginning with a single dash are only a single letter long. Any text immediately after the initial dash and letter is the name of argument to that flag.

--getopt opt-spec

Use this flag to specify single letter flags that might not be listed in the usage text, or might not specify that they have args in usage text. The opt-spec is a getopt string for this command (e.g. "Aaf:rs:").

XML Detail Generation

-n is_flag: Use this "is_flag" to say that the argtag to use for all flag arguments in the XML output will be the name of the flag (e.g -w goes to _w_flag) rather than the default, which is the argname found in the usage text. This is useful when names of arguments in the usage text are not descriptive (e.g. 'arg').
-n add_flag: Use this "add_flag" to say that the argtag to use for all flag arguments in the XML output will be the name of the argname found in the usage text plus flag name (e.g -w file goes to file_w_flag) rather than the argname found in the usage text. This is useful when names of arguments in the usage text are partially descriptive (e.g. 'file' or "dir"), and are used for different meanings (e.g. output directory and the font directory).

Subcommand Flags

--is-subcommand: Use this flag when you are giving the usage text for a subcommand. This will cause help2simple.pl generate XML output for a subcommand, rather than a command.
--has-subcommands dir: Use this flag when a command has subcommands. The "dir" argument is a directory containing '*.xml' files (or '*.pyx' files if "-pyx" is specified) that are in the subcommand format as generated by previous runs of help2simple.pl with the "--is-subcommand" option. Help2simple.pl will include all the '*.xml' (or '*.pyx) files from the directory. All these files are expected to be in the proper format.
--subcommands-prefix: Use this flag to specify an alternative prefix for subcommand functions.
: When the completion function is generated, a completion function will be generated for each subcommand. The name of these completion functions will be "_<command_name>_<subcommand_name>". The leading "_<command_name>_" is the default prefix. Use this flag to specify another prefix. Use this flag with the --has-subcommands flag.
--subcommand-dispatch dispatch: Use this flag to specify the type of dispatch mechanism to use for subcommands. The name of the types of dispatch are specific to the conversion process. Currently, there is only one type of dispatch called "describe", which causes the dispatch to include descriptions of subcommands when they are completed. Use this flag with the --has-subcommands flag.
--subcommand-description descr: Use this flag to specify a description of the current subcommand. Use this flag with the "-is-subcommand" flag. The description is provide to the user with the "describe" dispatcher.