Imported Upstream version 1.0upstream/1.0

1 files changed, 486 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 00000000..c403179a
--- /dev/null
+++ b/README
@@ -0,0 +1,486 @@
+INSTALLATION
+------------
+
+The easiest way to install this software is to use a package, such as
+the RPM that I maintain for Red Hat Linux, the .deb package for
+Debian/GNU Linux or Ubuntu, etc. You still need to source it from either
+/etc/bashrc or ~/.bashrc (or any other file sourcing those). You can do
+this by simply using:
+
+# Use bash-completion, if available
+if [ -f /etc/bash_completion ]; then
+  . /etc/bash_completion
+fi
+
+(if you happen to have *only* bash >= 2.04, see further if not)
+
+If you don't have the package readily available for your distribution, or
+you simply don't want to do this, put the bash_completion file somewhere
+on your system and source it from either /etc/bashrc or ~/.bashrc, as
+explained above.
+
+Here's another possible way of doing that from /etc/bashrc:
+
+# Check for interactive shell.
+if [ -n "$PS1" ]; then
+  if [ $bmajor -eq 2 -a $bminor '>' 04 ] || [ $bmajor -gt 2 ]; then
+    if [ -r /etc/bash_completion ]; then
+      # Source completion code.
+      . /etc/bash_completion
+    fi
+  fi
+fi
+unset bash bminor bmajor
+
+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/3.x users on your system, you
+must avoid using constructs that were not valid under 1.x syntax.
+
+If your system has an /etc/profile.d directory, you might instead want
+to add a script called bash_completion.sh to that directory. Add the
+above code, preceded by the following:
+
+# Check for bash.
+[ -z "$BASH_VERSION" ] && return
+
+In this case, all *.sh scripts in /etc/profile.d are sourced from
+/etc/bashrc by Bourne-like shells, so you need the extra check for bash
+in order to avoid sourcing the rest of the script if a shell other than
+bash is running.
+
+For your convenience, a sample bash_completion.sh file is included in
+the package.
+
+If you're using MacOS X, /etc/bashrc is apparently not sourced at all.
+In that case, you should put the bash_completion file in /sw/etc and add
+the following code to ~/.bash_profile:
+
+if [ -f /sw/etc/bash_completion ]; then
+   . /sw/etc/bash_completion
+fi
+
+If you are putting the bash completion source file somewhere other
+than /etc/bash_completion, you should ensure that $BASH_COMPLETION is
+set to point to it before you source it. Your ~/.bashrc file is a good
+place to do this.
+
+
+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 official patch from the bash
+maintainer:
+
+	ftp://ftp.gnu.org/gnu/bash/bash-2.05b-patches/bash205b-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. However, I have endeavoured to make the code detect
+this version of bash and work around this issue, so please inform me
+if you still encounter this error.
+
+Copies of the patches and prepatched versions of bash are available
+from:
+
+	http://www.caliban.org/bash/
+
+If you find that a given function is producing errors under certain
+circumstances when you attempt completion, try running 'set -v' or
+'set -x' prior to attempting the completion again. This will produce
+useful debugging output that will aid me in fixing the problem if you
+are unable to do so yourself. Turn off the trace output by running
+either 'set +v' or 'set +x'.
+
+
+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.
+
+The have() function is used to conserve memory by only installing
+completion functions for those programs that are actually present on
+your system. The current method of determining whether or not a given
+binary is present is whether or not it can be found along a certain
+path of directories. The path that is currently searched is:
+
+	$PATH:/sbin:/usr/sbin:/usr/local/sbin
+
+where $PATH is your user path at the time the bash completion file is
+sourced.
+
+III.
+
+Many of the completion functions assume GNU versions of the various
+text utilities that they call (e.g. grep, sed and awk). Your mileage
+may vary.
+
+IV.
+
+If you are seeing 'unbound variable' warnings from bash when hitting
+<Tab>, this is because you have either 'set -u' or 'set -o nounset'
+somewhere in your start-up files. This causes bash to flag the use of
+any uninitialised shell variables as an error.
+
+Whilst I try to avoid references to uninitialised variables in the
+code, there seem to be at least some cases where bash issues this
+warning even though the variable in question has been initialised.
+
+One place this appears to occur is within the _muttconffiles() helper
+function used by mutt completion, where the function calls itself
+recursively. This seems to confuse bash and it issues spurious
+warnings if 'nounset' is set.
+
+V.
+
+After upgrading to bash 3.1, you may notice that completing on certain
+commands now fails with a message something like this:
+
+   sed: -e expression #1, char 20: unterminated `s' command
+
+The reason for this is that bash 3.1 contains the following,
+innocent-looking bug fix (from bash's CHANGES file):
+
+  t.  Fixed a bug that caused the expanded value of a $'...' string
+      to be incorrectly re-quoted if it occurred within a
+      double-quoted ${...} parameter expansion.
+
+Unfortunately, this also had the side effect of causing single quotes
+to be stripped from $'...' strings inside double-quoted command
+substitutions. Confused?
+
+Efforts have been made to work around this issue in the bash
+completion code as of the 20060301 release. All previous versions are
+vulnerable to the problem. However, it's possible that, even in the
+20060301 release and later, affected code remains.
+
+The issue has now been officially recognised as a regression in the
+bash 3.1 release and is fixed by official patch 11. If you encounter
+problems of this nature, please apply the patch below to your copy of
+bash:
+
+	ftp://ftp.gnu.org/gnu/bash/bash-3.1-patches/bash31-011
+
+
+FAQ
+---
+
+Q. The bash completion code inhibits some commands from completing on
+   files with extensions that are legitimate in my environment. Do I
+   have to disable completion for that command in order to complete on
+   the files that I need to?
+
+A. No. Use M-/ to (in the words of the man page) attempt file name
+   completion on the text to the left of the cursor. This will
+   circumvent any file type restrictions put in place by the bash
+   completion code.
+
+Q. How can I insert my own local completions without having to
+   reinsert them every time you issue a new release?
+
+A. Put them in ~/.bash_completion, which is parsed at the end of the
+   main completion script. See also the next question.
+
+Q. I author/maintain package X and would like to maintain my own
+   completion code for this package. Where should I put it to be sure
+   that interactive bash shells will find it and source it?
+
+   Put it in the directory pointed to by $BASH_COMPLETION_DIR, which
+   is defined at the beginning of the main completion script. Any
+   scripts placed in this directory will be sourced by interactive
+   bash shells. Usually, this is /etc/bash_completion.d.
+
+Q. I use CVS in combination with passwordless ssh access to my remote
+   repository. How can I have the cvs command complete on remotely
+   checked-out files where relevant?
+
+A. Define $COMP_CVS_REMOTE. Setting this to anything will result in
+   the behaviour you would like.
+
+Q. When I'm running a ./configure script and completion returns a list
+   of long options to me, some of these take a parameter,
+   e.g. --this-option=DESCRIPTION.
+
+   Running ./configure --help lists these descriptions, but everything
+   after the '=' is stripped when returning completions, so I don't
+   know what kind of data is expected as a given option's parameter.
+
+   Is there a way of getting ./configure completion to return the
+   entire option string, so that I can see what kind of data is
+   required and then simply delete the descriptive text and add my own
+   data?
+
+A. Define $COMP_CONFIGURE_HINTS. Setting this to anything will result
+   in the behaviour you would like.
+
+Q. When doing tar completion on a file within a tar file like this:
+
+   tar tzvf foo.tar.gz <Tab>
+
+   the pathnames contained in the tar file are not displayed
+   correctly. The slashes are removed and everything looks like it's
+   in a single directory. Why is this?
+
+A. It's a choice I had to make. bash's programmable completion is
+   limited in how it handles the list of possible completions it
+   returns.
+
+   Because the paths returned from within the tar file are likely not
+   existing paths on the file system, '-o dirnames' must be passed to
+   the complete built-in to make it treat them as such. However, then
+   bash will append a space when completing on directories during
+   pathname completion to the tar files themselves.
+
+   It's more important to have proper completion of paths to tar files
+   than it is to have completion for their contents, so this sacrifice
+   was made and '-o filenames' is used with complete instead.
+
+   If you would rather have correct path completion for tar file
+   contents, define $COMP_TAR_INTERNAL_PATHS *before* sourcing
+   bash_completion.
+
+Q. When completing on a symlink to a directory, bash does not append
+   the trailing / and I have to hit <Tab> again. I don't like this.
+
+A. This has nothing to do with bash_completion. It's the default for
+   completing symlinks to directories in bash 2.05a, and was added
+   because sometimes you want to operate on the symlink itself, rather
+   than what it points to.
+
+   In bash 2.05b and later, you can get the pre-2.05a behaviour back
+   by putting 'set mark-symlinked-directories on' in your /etc/inputrc
+   or ~/.inputrc file.
+
+Q. Completion goes awry when I try to complete on something that contains
+   a colon.
+
+A. This is actually a 'feature' of bash. bash recognises a colon as
+   starting a new completion token, which is often what you want when
+   completing something like a PATH variable:
+
+   $ export PATH=/bin:/sbin:/usr<Tab>
+
+   Without the special treatment of the colon, the above wouldn't work
+   without programmable completion, so it has long been a feature of
+   the shell.
+
+   Unfortunately, you don't want the colon to be treated as a special
+   case when doing something like:
+
+   $ man File::B<Tab>
+
+   Here, the colons make bash think that it's completing the a new
+   token that begins with 'B'.
+
+   Unfortunately, there's no way to turn this off. The only thing you
+   can do is escape the colons with a backslash.
+
+Q. Where did urpmi completion go?
+
+A. Guillaume Rousse <rousse@ccr.jussieu.fr> now maintains it separately as
+   part of the urpmi RPM package.
+
+   CVS: http://cvs.mandrakesoft.com/cgi-bin/cvsweb.cgi/soft/urpmi/
+   Web: http://urpmi.org/
+
+Q. Why is rpm completion so slow with -q?
+
+A. Probably because the database is being queried every time and this uses a
+   lot of memory.
+
+   You can make this faster by pregenerating the list of installed packages on
+   the system. Make sure you have a readable file called /var/log/rpmpkgs.
+   It's generated by /etc/cron.daily/rpm on modern Red Hat and Mandrake
+   Linux systems.
+
+   If you don't have such a cron job, make one:
+
+   #!/bin/sh
+
+   rpm -qa --qf '%{name}-%{version}-%{release}.%{arch}.rpm\n' 2>&1 \
+           | sort > /var/log/rpmpkgs
+
+   rpm completion will use this flat text file instead of the RPM database,
+   unless it detects that the database has changed since the file was created,
+   in which case it will still use the database to ensure accuracy.
+
+Q. Can tab completion be made even easier?
+
+A. The readline(3) library offers a few settings that can make tab
+   completion easier (or at least different) to use.
+
+   For example, try putting the following in either /etc/inputrc or
+   ~/.inputrc:
+
+     set show-all-if-ambiguous on
+
+   This will allow single tab completion as opposed to requiring a
+   double tab. This makes things much more pleasant, in my opinion.
+
+     set visible-stats on
+
+   This will suffix each returned file completion with a character
+   denoting its type, in a similar way to ls(1) with -F or --classify.
+
+     set page-completions off
+   
+   This turns off the use of the internal pager when returning long
+   completion lists.
+
+Q. This code is rubbish/not bad/pretty good/the best thing since
+   sliced bread. How can I show my appreciation?
+
+A. If you're a registered Freshmeat user, take a moment to rate the
+   project at:
+
+	http://freshmeat.net/rate/19041/
+
+   Of course, writing to me and letting me know how you feel also works.
+   Patches and new completion routines are most welcome, too.
+
+Q. How can I stay abreast of new releases?
+
+A. If you're a registered Freshmeat user, you can subscribe to new release
+   announcements at:
+
+	http://freshmeat.net/subscribe/19041/
+
+Q. Is bash the be-all-and-end-all of completion as far as shells go?
+
+A. Absolutely not. zsh has an extremely sophisticated completion system
+   that offers many features absent from the bash implementation. Its
+   users often cannot resist pointing this out. More information can
+   be found at:
+
+	http://www.zsh.org/
+
+
+CONTRIBUTING
+------------
+
+Contributions to the bash completion project are more than
+welcome. Fixes, clean-ups and improvements of existing code are much
+appreciated, as are completion functions for new commands.
+
+If you wish to contribute code, please bare the following coding
+guidelines in mind:
+
+- Do not use Perl, Ruby, Python etc. to do text processing unless the
+  command for which you are writing the completion code implies the
+  presence of one of those languages.
+
+  For example, if you were writing completion code for perldoc(1), the
+  use of Perl to achieve your goal would be acceptable. irb(1)
+  completion would similarly make the use of Ruby acceptable.
+
+  Even so, please consider alternatives to these large and slow to
+  start interpreters. Use lightweight programs such as grep(1), awk(1)
+  and sed(1).
+
+- Use the full power of bash 2.x. Programmable completion has only
+  been available since bash 2.04, so you may as well use all the
+  features of that version of bash to optimise your code. However, be
+  careful when using features added since 2.04, since not everyone
+  will be able to use them. Be ESPECIALLY careful of using features
+  exclusive to 3.x, as many people are still using 2.x.
+
+  For example, here strings (<<<) were not added until 2.05b, so don't
+  use them for the time being.
+
+  Similarly, 3.0 added the use of the regex operator '=~', commonly
+  found in Perl and Ruby. Whilst this is very useful, it's not yet
+  safe to assume its ubiquity.
+  
+  On the other hand, extended globs were added in bash 2.02 and often
+  enable you to avoid the use of external programs, which are
+  expensive to fork and execute, so do make full use of those:
+
+  ?(pattern-list) - match zero or one occurrences of patterns
+  *(pattern-list) - match zero or more occurrences of patterns
+  +(pattern-list) - match one or more occurrences of patterns
+  @(pattern-list) - match exactly one of the given patterns
+  !(pattern-list) - match anything except one of the given patterns
+
+- Following on from the last point, be sparing with the use of
+  external processes whenever you can. Completion functions need to be
+  fast, so sacrificing some code legibility for speed is acceptable.
+
+  For example, judicious use of sed(1) can save you from having to
+  call grep(1) and pipe the output to cut(1), which saves a fork(2)
+  and exec(3).
+
+  Sometimes you don't even need sed(1) or other external programs at
+  all, though. Use of constructs such as ${parameter#word},
+  ${parameter%word} and ${parameter/pattern/string} can provide you a
+  lot of power without having to leave the shell.
+
+  For example, if $foo contains the path to an executable, ${foo##*/}
+  will give you the basename of the program, without having to call
+  basename(1). Similarly, ${foo%/*} will give you the dirname, without
+  having to call dirname(1).
+
+  As another example,
+
+    bar=$( echo $foo | sed -e 's/bar/baz/g' )
+
+  can be replaced by:
+
+    bar=${foo//bar/baz}
+
+  These forms of parameter substitutions can also be used on arrays,
+  which makes them very powerful (if a little slow).
+
+- Do not write to the file-system under any circumstances. This can
+  create race conditions, is inefficient, violates the principle of
+  least surprise and lacks robustness.
+
+- Send your patches as unified diffs. You can make these with
+  'diff -u'.
+
+- Send small, incremental diffs that affect a single function. Don't
+  cram massive, unrelated patches into a single diff.
+
+- If your code was written for a particular platform, try to make it
+  portable to other platforms, so that everyone may enjoy it. If your
+  code works only with the version of a binary on a particular
+  platform, ensure that it will not be loaded on other platforms that
+  have a command with the same name.
+
+  In particular, do not use GNU extensions to commands like sed and
+  awk if you can write your code another way. If you really must use
+  them, however, do feel free to do so.
+
+- Read the existing source code for examples of how to solve
+  particular problems. Read the bash man page for details of all the
+  programming tools available to you within the shell.
+
+- Please test your code thoroughly before sending it to me. I don't
+  have access to all the commands for which I am sent completion
+  functions, so I am unable to test them all personally. If your code
+  is accepted into the distribution, a lot of people will try it out,
+  so try to do a thorough job of eradicating all the bugs before you
+  send it to me.
+  
+-- 
+Ian Macdonald
+ian@caliban.org