$Id: README,v 1.5 2002/02/25 23:02:41 ianmacd Exp $


INSTALLATION
------------

If you are installing the source file manually as opposed to using a packaging
system such as dpkg or rpm, put it somewhere on your system and source it from
either /etc/bashrc or ~/.bashrc.

Here's one possible way of doing that from /etc/bashrc:

bash=${BASH_VERSION%.*}; bmajor=${bash%.*}; bminor=${bash#*.}
if [ "$PS1" ] && [ $bmajor -eq 2 ] && [ $bminor '>' 04 ] \
   && [ -f /etc/bash_completion ]; then # interactive shell
        # Source completion code
        . /etc/bash_completion
fi
unset bash bmajor bminor

This code checks that the version of bash that is parsing the code is later
than 2.04 and, if so, sources the bash completion code.

While this code may, at first, seem overly complex, the advantage of using it
is that it will also parse correctly when interpreted by bash 1.x. If you have
bash 1.x and bash 2.x users on your system, you must avoid using constructs
that were not valid under 1.x syntax.

If you are putting the bash completion source file somewhere other than
/etc/bash_completion, you will need to edit the top of the file to make
$BASH_COMPLETION point to the correct location.

The line you need to adjust is this one:

[ -z "$BASH_COMPLETION" ] && declare -r BASH_COMPLETION=/etc/bash_completion


TROUBLESHOOTING
---------------

If you get errors about 'complete' or 'compgen' not accepting the -g flag,
you are probably running bash 2.05 and should either apply the group completion
patch, download a prepatched bash binary of 2.05, or upgrade to 2.05a or later.

If you find that some commands, such as 'cd /usr<Tab>', end with a trailing
space instead of appending a /, you are probably running the base version of
bash 2.05, which suffers from a bug that causes the '-o filenames' option to
the complete built-in to be ignored. You can fix this by applying the following
the following official patch from the bash maintainer:

	ftp://ftp.cwru.edu/pub/bash/bash-2.05-patches/bash205-006

If you get errors about 'complete' not accepting the -o flag, you are probably
running bash 2.04. In this case, you should upgrade to bash 2.05a or later.

Copies of the patches and prepatched versions of bash are available from:

			http://www.caliban.org/bash/

KNOWN PROBLEMS
--------------

I.

There seems to be some issue with using the bash built-in cd within Makefiles.
When invoked as /bin/sh within Makefiles, bash seems to have a problem changing
directory via the cd command. A work-around for this is to define
SHELL=/bin/bash within your Makefile. This is believed to be a bug in bash.

II.

There may be points along the command line where completion is not supported
for a given command. Attempting completion at these points may result in a
usage message for the bash built-in compgen being printed on stderr.

The cause of this is usually that compgen is being passed a parameter for
completion whose value begins with a hyphen. After variable expansion, compgen
has no way of knowing that the hyphen option is not an option to itself.

For example, if the completion code for a given command is something like
'compgen -f "$cur"', where $cur is the current parameter on which you are
attempting to complete and it expands to "-x", bash will try to execute the
command 'compgen -f -x', believing that -x is an option to itself, not a string
upon which to complete.

I have endeavoured to trap as many instances of this in the code as possible,
but it is highly likely that others remain. If you receive compgen errors while
attempting completion, please report these incidents to me.

III.

The have() function is used to conserve memory by only installing completion
functions for binaries actually present on your system. The current method of
determining whether or not a binary is present is whether or not it is in your
$PATH.

This approach has the disadvantage that sudo completion will not be able to
perform sub-completion on, say, ifconfig if /sbin is not in your path, which,
as an unprivileged user, it typically isn't.

The work-around for this is to put all directories of binaries for which you
require completion into your $PATH variable.

-- 
Ian Macdonald <ian@caliban.org>