[nongnu] elpa/bash-completion a2da7b910b 235/313: Updated README to push for bash-completion-use-separate-processes.

[ELPA Syncer]

branch: elpa/bash-completion
commit a2da7b910bea706a16070dc93fd515a99c5ca0a1
Author: Stephane Zermatten <szermatt@gmx.net>
Commit: Stephane Zermatten <szermatt@gmx.net>

    Updated README to push for bash-completion-use-separate-processes.
    
    New installations should set bash-completion-use-separate-processes to
    nil.
---
 .gitignore         |  1 +
 README.md          | 73 +++++++++++++++++++++++++++++++++++-------------------
 bash-completion.el | 71 ++++++++++++++++++++++++++++++++++------------------
 3 files changed, 96 insertions(+), 49 deletions(-)

diff --git a/.gitignore b/.gitignore
index 90fdcfb681..7afe8e39c4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 *.elc
+README.html
 .cask
 test/.set-bash-prog.el
diff --git a/README.md b/README.md
index 43ad912aec..ed89d2eae5 100644
--- a/README.md
+++ b/README.md
@@ -34,16 +34,28 @@ the default) and by calling
 1. copy bash-completion.el into a directory that's on Emacs load-path
 2. add this into your .emacs file:
 
+```elisp
+        (setq bash-completion-use-separate-processes nil)
         (autoload 'bash-completion-dynamic-complete
           "bash-completion"
           "BASH completion hook")
         (add-hook 'shell-dynamic-complete-functions
           'bash-completion-dynamic-complete)
+```
 
   or simpler, but forces you to load this file at startup:
 
+```elisp
+        (setq bash-completion-use-separate-processes nil)
         (require 'bash-completion)
         (bash-completion-setup)
+```
+
+  NOTE: Setting `bash-completion-use-separate-processes` to nil on new
+  installations is recommended. It might become the default in future
+  versions of `bash-completion.el. See the section
+  
[bash-completion-use-separate-processes](#bash-completion-use-separate-processes)
+  for more details.
 
 3. reload your .emacs (M-x `eval-buffer') or restart
 
@@ -55,44 +67,32 @@ launches a new bash process.
 You'll get better results if you turn on programmable bash completion.
 On Ubuntu, this means running:
 
+```sh
     sudo apt-get install bash-completion
+```
 
 and then adding this to your .bashrc:
 
+```sh
     . /etc/bash_completion
+```
 
-NOTE: The following paragraph are not relevant when
-`bash-completion-use-separate-processes` is nil.
-
-Right after enabling programmable bash completion, and whenever you
-make changes to you .bashrc, call `bash-completion-reset' to make
-sure bash completion takes your new settings into account.
-
-Loading /etc/bash_completion often takes time, and is not necessary
-in shell mode, since completion is done by a separate process, not
-the process shell-mode process.
-
-To turn off bash completion when running from emacs but keep it on
-for processes started by bash-completion.el, add this to your .bashrc:
+## bash-completion-use-separate-processes
 
-    if [[ ( -z "$INSIDE_EMACS" || "$EMACS_BASH_COMPLETE" = "t" ) &&\
-         -f /etc/bash_completion ]]; then
-      . /etc/bash_completion
-    fi
-
-Emacs sets the environment variable INSIDE_EMACS to the processes
-started from it. Processes started by bash-completion.el have
-the environment variable EMACS_BASH_COMPLETE set to t.
+TL;DR Set `bash-completion-use-separate-processes` to `nil` and avoid
+the issues and complications described in this section.
 
-## CAVEATS
+When `bash-completion-use-separate-processes` is `t`, completion runs
+in a separate process from the shell process. 
 
-NOTE: This section is not relevant when
-`bash-completion-use-separate-processes` is nil.
+This might be useful in some cases, as it allows interrupting slow
+completions, when necessary.
 
-Using a separate process for doing the completion has several
+However using a separate process for doing the completion has several
 important disadvantages:
 
 - bash completion is slower than standard emacs completion
+- it relies on directory tracking working correctly on Emacs
 - the first completion can take a long time, since a new bash process
   needs to be started and initialized
 - the separate process is not aware of any changes made to bash
@@ -108,6 +108,29 @@ important disadvantages:
   of a new alias, you need to add it to .bashrc and restart the
   completion process using `bash-completion-reset'.
 
+When using separate processes, right after enabling programmable bash
+completion, and whenever you make changes to you .bashrc, call
+`bash-completion-reset' to make sure bash completion takes your new
+settings into account.
+
+Loading /etc/bash_completion often takes time, and is not necessary
+in shell mode, since completion is done by a separate process, not
+the process shell-mode process.
+
+To turn off bash completion when running from emacs but keep it on
+for processes started by bash-completion.el, add this to your .bashrc:
+
+```bash
+    if [[ ( -z "$INSIDE_EMACS" || "$EMACS_BASH_COMPLETE" = "t" ) &&\
+         -f /etc/bash_completion ]]; then
+      . /etc/bash_completion
+    fi
+```
+
+Emacs sets the environment variable INSIDE_EMACS to the processes
+started from it. Processes started by bash-completion.el have
+the environment variable EMACS_BASH_COMPLETE set to t.
+
 ## COMPATIBILITY
 
 bash-completion.el is known to work with Bash 3 and 4, on Emacs,
diff --git a/bash-completion.el b/bash-completion.el
index 4cac5a4932..cf12f08552 100644
--- a/bash-completion.el
+++ b/bash-completion.el
@@ -54,6 +54,7 @@
 ;;
 ;; 1. copy bash-completion.el into a directory that's on Emacs load-path
 ;; 2. add this into your .emacs file:
+;;   (setq bash-completion-use-separate-processes nil)
 ;;   (autoload 'bash-completion-dynamic-complete \"bash-completion\"
 ;;     \"BASH completion hook\")
 ;;   (add-hook 'shell-dynamic-complete-functions
@@ -62,7 +63,14 @@
 ;;   or simpler, but forces you to load this file at startup:
 ;;
 ;;   (require 'bash-completion)
+;;   (setq bash-completion-use-separate-processes nil)
 ;;   (bash-completion-setup)
+;; 
+;;   NOTE: Setting `bash-completion-use-separate-processes` to nil on new
+;;   installations is recommended. It might become the default in future
+;;   versions of `bash-completion.el. See the section
+;;   
[bash-completion-use-separate-processes](#bash-completion-use-separate-processes)
+;;   for more details.
 ;;
 ;; 3. reload your .emacs (M-x `eval-buffer') or restart
 ;;
@@ -77,42 +85,57 @@
 ;; and then adding this to your .bashrc:
 ;;   . /etc/bash_completion
 ;;
-;; Right after enabling programmable bash completion, and whenever you
-;; make changes to you .bashrc, call `bash-completion-reset' to make
-;; sure bash completion takes your new settings into account.
-;;
-;; Loading /etc/bash_completion often takes time, and is not necessary
-;; in shell mode, since completion is done by a separate process, not
-;; the process shell-mode process.
-;;
-;; To turn off bash completion when running from emacs but keep it on
-;; for processes started by bash-completion.el, add this to your .bashrc:
-;; if [[ ( -z "$INSIDE_EMACS" || "$EMACS_BASH_COMPLETE" = "t" ) &&\
-;;      -f /etc/bash_completion ]]; then
-;;   . /etc/bash_completion
-;; fi
-;;
-;; Emacs sets the environment variable INSIDE_EMACS to the processes
-;; started from it. Processes started by bash-completion.el have
-;; the environment variable EMACS_BASH_COMPLETE set to t.
-;;
-;; CAVEATS
-;;
-;; Using a separate process for doing the completion has several
+;; CAVEAT
+;; 
+;; TL;DR Set `bash-completion-use-separate-processes` to `nil` and avoid
+;; the issues and complications described in this section.
+;; 
+;; When `bash-completion-use-separate-processes` is `t`, completion runs
+;; in a separate process from the shell process. 
+;; 
+;; This might be useful in some cases, as it allows interrupting slow
+;; completions, when necessary.
+;; 
+;; However using a separate process for doing the completion has several
 ;; important disadvantages:
+;; 
 ;; - bash completion is slower than standard emacs completion
+;; - it relies on directory tracking working correctly on Emacs
 ;; - the first completion can take a long time, since a new bash process
 ;;   needs to be started and initialized
 ;; - the separate process is not aware of any changes made to bash
 ;;   in the current buffer.
 ;;   In a standard terminal, you could do:
-;;     $ alias myalias=ls
-;;     $ myal<TAB>
+;; 
+;;         $ alias myalias=ls
+;;         $ myal<TAB>
+;; 
 ;;   and bash would propose the new alias.
 ;;   Bash-completion.el cannot do that, as it is not aware of anything
 ;;   configured in the current shell. To make bash-completion.el aware
 ;;   of a new alias, you need to add it to .bashrc and restart the
 ;;   completion process using `bash-completion-reset'.
+;; 
+;; When using separate processes, right after enabling programmable bash
+;; completion, and whenever you make changes to you .bashrc, call
+;; `bash-completion-reset' to make sure bash completion takes your new
+;; settings into account.
+;; 
+;; Loading /etc/bash_completion often takes time, and is not necessary
+;; in shell mode, since completion is done by a separate process, not
+;; the process shell-mode process.
+;; 
+;; To turn off bash completion when running from emacs but keep it on
+;; for processes started by bash-completion.el, add this to your .bashrc:
+;; 
+;;     if [[ ( -z "$INSIDE_EMACS" || "$EMACS_BASH_COMPLETE" = "t" ) &&\
+;;          -f /etc/bash_completion ]]; then
+;;       . /etc/bash_completion
+;;     fi
+;; 
+;; Emacs sets the environment variable INSIDE_EMACS to the processes
+;; started from it. Processes started by bash-completion.el have
+;; the environment variable EMACS_BASH_COMPLETE set to t.
 ;;
 ;; COMPATIBILITY
 ;;