
SCRIPTING STYLE GUIDE FOR COMPLETION SCRIPTS


1) File names:

The scripts are named after a binary which, if it is installed on the the
system, triggers the inclusion of the script in the system wide completion
cache (eg. bash and all builtins go to file 'bash', gzip and gunzip go to 'gzip'
...).
# this check is not yet implemented in xpcomp_updatecache

There will evenually be a directory containing scripts for packages installed
by the package management system, these scripts will have the same name as the
package.

The directory containing the scripts is in the same directory as the 'include'
directory which contains useful variable definitions and completion commands,
so inclusion of these files looks like 'source ../include/<filename>'.


2) Script layout:

Only files from the include directory may be sourced.

A variable 'cmd' is set to the the name of the completed command and all
optcomplete command lines use this variable instead of the literal command name
(this allows for usage of include scripts when differend commands have 
the same option, as x11 or gnome commands).

Variables that have been set in a script are unset at the end of the script
(this is because i am quite a pedantic nerd).

optcomplete commands lines start in the first column and have the form
'optcomplete <optcomplete options>  $cmd <option name> ..'
(this allows for easier regexp replacing if interface changes are necessary).


3) How to do command completion:

Try to generate as many (syntactically correct) matches as possible.
Do not stick with your own expectations or usage style, as this might
be annoying for other users with other habits.

Try to complete ALL options and non-option words on the command line,
not only those that seem important most often used.

Look at the bash 'complete' builtin and use as much of its feature as possible
by using the same options for the optcomplete command.  Most of the following
only applies if you use the -C option or command substitutiun with the -W
command.

Completions are evaluated in restricted mode.

No output is generated on stderr (use 2>&1 or appropriate command options
to accomplish this).  Be ware of unexpected characters in XPC_PATTERN,
use ${XPC_PATTERN%%[^[:alnum:]]*} or sth. like this if necessary.

No network connections are initiated (i am not sure if this should be
an option for the user, but currently it is not).

Be sure to only use commands (for generating the matches) that can be
reasonably assumed to be availible on the system (eg. sed, diff, awk,
<the completed command itself>, grep, file,  ...).


