Imported Upstream version 1.2upstream/1.2

1 files changed, 78 insertions, 160 deletions

diff --git a/README b/README
index 7cfd1bd6..725678ac 100644
--- a/README
+++ b/README
@@ -1,59 +1,31 @@
 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:
+The easiest way to install this software is to use a package; it is available
+in many operating system distributions.  The package's name is usually
+bash-completion.  Depending on the package, you may 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 happen to have *only* bash >= 3.2 installed, 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.
+A more elaborate way that takes care of not loading on old, unsupported
+bash versions as well as some other conditions is included in the bash
+completion package as bash_completion.sh.  If your system has the
+/etc/profile.d directory and loads all files from it automatically,
+you may place the file in it.  If not, place the file somewhere on your
+system and source it from /etc/bashrc or ~/.bashrc, or copy its contents
+to one of those files.
 
 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
@@ -72,35 +44,10 @@ 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
+useful debugging output that will aid us 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'.
 
@@ -142,7 +89,7 @@ If you are seeing 'unbound variable' warnings from bash when hitting
 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
+Whilst we 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.
 
@@ -151,36 +98,6 @@ 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
 ---
@@ -241,7 +158,7 @@ Q. When doing tar completion on a file within a tar file like this:
    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
+A. It's a choice we had to make. bash's programmable completion is
    limited in how it handles the list of possible completions it
    returns.
 
@@ -263,13 +180,13 @@ 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
+   completing symlinks to directories since 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.
+   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.
@@ -295,14 +212,6 @@ A. This is actually a 'feature' of bash. bash recognises a colon as
    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
@@ -335,7 +244,7 @@ A. The readline(3) library offers a few settings that can make tab
      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.
+   double tab. This makes things much more pleasant, in our opinion.
 
      set visible-stats on
 
@@ -343,28 +252,10 @@ A. The readline(3) library offers a few settings that can make tab
    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
@@ -397,23 +288,16 @@ guidelines in mind:
   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.
+- Use the full power of bash >= 3.2. We no longer support earlier bash
+  versions, 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 bash 3.2, since not everyone will be able to use them. Be
+  ESPECIALLY careful of using features exclusive to 4.x, as many people
+  are still using 3.x.
 
-  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:
+  For example, extended globs 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
@@ -460,15 +344,37 @@ guidelines in mind:
   difference in speed), but all embedding cases should be documented
   with rationale in comments in the code.
 
+- When completing available options, offer only the most descriptive
+  ones as completion results if there are multiple options that do the
+  same thing.  Usually this means that long options should be preferred
+  over the corresponding short ones.  This way the user is more likely
+  to find what she's looking for and there's not too much noise to
+  choose from, and there are less situations where user choice would be
+  needed in the first place.  Note that this concerns only display of
+  available completions; argument processing/completion for options that
+  take an argument should be made to work with all known variants for
+  the functionality at hand.  For example if -s, -S, and --something do
+  the same thing and require an argument, offer only --something as a
+  completion when completing option names starting with a dash, but do
+  implement required argument processing for all -s, -S, and --something.
+  Note that GNU versions of various standard commands tend to have long
+  options while other userland implementations of the same commands may
+  not have them, and it would be good to have the completions work for
+  as many userlands as possible so things aren't always that simple.
+
 - 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 do one thing. Don't cram unrelated
+  changes into a single diff.
 
-- Send small, incremental diffs that affect a single function. Don't
-  cram massive, unrelated patches into a single diff.
+- Generate patches preferably against the git repository, with "git
+  format-patch origin/master" (assuming the diff was against the
+  origin/master branch), and don't forget the entry for the CHANGES file
+  if you feel that the change deserves one.  If you don't have git
+  available or can't access the repository for some reason, generate
+  patches as unified diffs ('diff -u').
 
 - 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
@@ -477,20 +383,32 @@ guidelines in mind:
   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.
+  awk if you can write your code another way. If you really, REALLY must
+  use them, do so if there's no other sane way to do what you're doing.
+  The "Shell and Utilities" volume of the POSIX specification is a good
+  starting reference for portable use of various utilities, see
+  http://www.opengroup.org/onlinepubs/9699919799/
 
 - 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
+- Please test your code thoroughly before sending it to us. We don't
+  have access to all the commands for which we are sent completion
+  functions, so we are 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.
-  
+  send it to us.
+
+- File bugs, enhancement requests (preferably with patches attached) at
+  the project tracker at https://alioth.debian.org/projects/bash-completion/
+  Sending them to the developers list usually works too, but bits are more
+  likely to fall through the cracks that way compared to the tracker.
+
+- Use printf(1) instead of echo(1) for portability reasons, and be sure to
+  invoke commands that are often found aliased (such as ls or grep etc)
+  using the "command" (or "builtin") command as appropriate.
+
 -- 
-Ian Macdonald
-ian@caliban.org
+bash-completion developers
+bash-completion-devel@lists.alioth.debian.org