This is the annotated DTD for the simple xml format for xml completion function representation. Via the simple2long.xsl XSL script it is possible to generate the equivalent long xml format, which can them be converted into an actual completion function via the arg.xsl XSL script.
This simple format is able to only generate a subset of the completion functions that can be generated by the longer format. For instance, the simple format only handles one command. It doesn't currently have support for subcommands (e.g. cvs subcommands) or for flags that have more than one argument.
The "command" element is the root element of this simple format. It currently only has one attribute "command" The "command" attribute is used to specify the name of the command that is going to be completed. At some point this should handle passing flags to _arguments, probably through attributes. The "multiple" attribute is a boolean flag (taking values of either 'true' or 'false', with a default of 'false' if not specified). If the multiple attribute is true, then it is assumed that all the flags can be given more than once.
<!ELEMENT command ( flag+, arg+, generation+, subcommands ) > <!ATTLIST command command NMTOKEN #REQUIRED > <!ATTLIST command multiple NMTOKEN #IMPLIED >
The "arg" element is used to describe the fixed position or final arguments to a command.
The "position" attribute can either be a number which is the position that this argument is used for or the string "any". If "position" has the value "any", this is the final argument, and it can be repeated any number of times.
The "argtag" attribute is used to specify a tag that will be mapped to the action for this argument. This typically this tag is used as a key to find a template in the included defines file, or might be used as a state name or a the argument passed to the arguments handling function. This is specified by the arg.xsl stylesheet parameter "ActionTagGeneration".
The "taghelp" attribute holds the help text that will be listed for this
flag.
<!ELEMENT arg EMPTY > <!ATTLIST arg argtag NMTOKEN #REQUIRED > <!ATTLIST arg position NMTOKEN #REQUIRED > <!ATTLIST arg taghelp NMTOKEN #REQUIRED > <!ATTLIST arg words_only_normal_args NMTOKEN #IMPLIED >
The "flag" element is used to describe a command flag.
The "argtag" attribute is used to specify a tag that will be mapped to the action for this argument. This typically this tag is used as a key to find a template in the included defines file, or might be used as a state name or a the argument passed to the arguments handling function. This is specified by the arg.xsl stylesheet parameter "ActionTagGeneration".
The "mutiple" attribute can take the value "true" or "false". If this attribute is not specified it is assumed to be the value of the "multiple" attribute in the "command" element. If this attribute is given a true value, then the flag is allowed to be given more than once on the command line.
The "name" attribute is the actual flag.
The "same_word" attribute takes a boolean value ('true' or 'false', defaulting to 'false'). If it is set to true, then the flag's argument is suppose to be in the same word as the flag.
The "exclusionlist" attribute is a space separated list of flags, numbers, and "*" telling which flags or positions which if present on the command line will prevent this flag from being completed.
The "fixedstring" attribute is a space separated list of constant words that are the legal values for the argument for this flag. There currently is no way to supply help text for the strings.
The "taghelp" attribute is the help text for this flags' argument.
The "words_only_normal_args" tells the completion system to modify the words array to make the current the command, so that the following words are considered normal arguments. Useful for when you have subcommands.
<!ELEMENT flag EMPTY > <!ATTLIST flag argtag NMTOKEN #IMPLIED > <!ATTLIST flag exclusionlist CDATA #IMPLIED > <!ATTLIST flag fixedstrings CDATA #IMPLIED > <!ATTLIST flag multiple NMTOKEN #IMPLIED > <!ATTLIST flag name NMTOKEN #REQUIRED > <!ATTLIST flag same_word NMTOKEN #IMPLIED > <!ATTLIST flag taghelp CDATA #REQUIRED >
The "generation" element is currently only used for documentation purposes. The idea is that every step used to generate a completion function should be documented so that someone can later re-perform the processing, (e.g. for a different version of the command). The text of this is element is passed on to the long format, and the generated completion function (as a comment.)
<!ELEMENT generation EMPTY > <!ATTLIST generation command CDATA #REQUIRED >
The "subcommand" element has the same basic structure as a command. It can contain "flag" and "arg" elements. It requires a "name" attribute, which is the name of the subcommand. Also, it can take a "description" attribute which can be offered for help.
<!ELEMENT subcommand ( flag*, arg* ) > <!ATTLIST subcommand description CDATA #REQUIRED > <!ATTLIST subcommand name ID #REQUIRED >
The "subcommands" element is used when a command has subcommands, which have their only command line flags (e.g. like the cvs command). This element is a grouping element, it contains "subcommand" elements that describe each subcommand. The "dispatch" attribute is the name of the type of dispatch function to use. Currently there is only one dispatch function. The "prefix" attribute is used as a prefix for the functions created to complete each subcommand. Typically this prefix should being and end with an underscore character.
<!ELEMENT subcommands ( subcommand+ ) > <!ATTLIST subcommands dispatch NMTOKEN #REQUIRED > <!ATTLIST subcommands prefix NMTOKEN #REQUIRED >