Imported Upstream version 1.90upstream/1.90

1 files changed, 30 insertions, 36 deletions

diff --git a/README b/README
index 71758cd0..428f2947 100644
--- a/README
+++ b/README
@@ -8,11 +8,10 @@ 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
+[[ $PS1 && -f /usr/share/bash-completion/bash-completion ]] && \
+    . /usr/share/bash-completion/bash-completion
 
-(if you happen to have *only* bash >= 3.2 installed, see further if not)
+(if you happen to have *only* bash >= 4.1 installed, see further if not)
 
 If you don't have the package readily available for your distribution, or
 you simply don't want to use one, you can install bash completion using the
@@ -30,19 +29,22 @@ mechanism, i.e. does not automatically source shell scripts in it, you
 can source the $sysconfdir/profile.d/bash_completion.sh script in
 /etc/bashrc or ~/.bashrc.
 
+The profile.d script provides a configuration file hook that can be
+used to prevent loading bash_completion on per user basis when it's
+installed system wide.  To do this, turn off programmable completion
+with "shopt -u progcomp" in $XDG_CONFIG_HOME/bash_completion
+(~/.config/bash_completion if $XDG_CONFIG_HOME is not set), and turn
+it back on for example in ~/.bashrc if you want to use programmable
+completion for other purposes.
+
 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
+In that case, you can 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
 ---------------
@@ -68,24 +70,11 @@ 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.
+III.
 
 If you are seeing 'unbound variable' warnings from bash when hitting
 <Tab>, this is because you have either 'set -u' or 'set -o nounset'
@@ -125,10 +114,17 @@ 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.
+   Install it in one of the directories pointed to by
+   bash-completion's pkgconfig file variables.  There are two
+   alternatives: the recommended one is 'completionsdir' (get it with
+   "pkg-config --variable=completionsdir bash-completion") from which
+   completions are loaded on demand based on invoked commands' names,
+   so be sure to name your completion file accordingly, and to include
+   for example symbolic links in case the file provides completions
+   for more than one command.  The other one which is present for
+   backwards compatibility reasons is 'compatdir' (get it with
+   "pkg-config --variable=compatdir bash-completion") from which files
+   are loaded when bash_completion is loaded.
 
 Q. I use CVS in combination with passwordless ssh access to my remote
    repository. How can I have the cvs command complete on remotely
@@ -291,12 +287,10 @@ guidelines in mind:
   start interpreters. Use lightweight programs such as grep(1), awk(1)
   and sed(1).
 
-- Use the full power of bash >= 3.2. We no longer support earlier bash
+- Use the full power of bash >= 4.1. 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.
+  added since bash 4.1, since not everyone will be able to use them.
 
   For example, extended globs often enable you to avoid the use of
   external programs, which are expensive to fork and execute, so do
@@ -374,10 +368,10 @@ guidelines in mind:
 
 - 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').
+  origin/master branch), and send them preferably with "git
+  send-email".  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