[nongnu] elpa/bash-completion 0210d346f1 279/313: Make bash-completion-use-separate-processes default to nil.

[ELPA Syncer]

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

    Make bash-completion-use-separate-processes default to nil.
    
    Starting with this change, bash-completion.el reuses the bash shell
    process of the current buffer whenever it looks like it can.
---
 README.md          |  55 ++++++----------------------
 bash-completion.el | 104 +++++++++++++++--------------------------------------
 2 files changed, 40 insertions(+), 119 deletions(-)

diff --git a/README.md b/README.md
index f6b5244e24..69081196c1 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,6 @@ prompts, such as the prompt started by `compile`, add the hook
 For example:
 
 ```elisp
-        (setq bash-completion-use-separate-processes nil)
         (autoload 'bash-completion-dynamic-complete
           "bash-completion"
           "BASH completion hook")
@@ -46,19 +45,23 @@ For example:
 or simpler, but forces you to load bash-completion 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.
-  
 After that reload your .emacs (M-x `eval-buffer') or restart.
 
+When called from a bash shell buffer,
+`bash-completion-dynamic-complete` communicates with the current shell
+to reproduce, as closely as possible the normal bash auto-completion,
+available on full terminals.
+
+When called from non-shell buffers, such as the prompt of M-x compile,
+`bash-completion-dynamic-complete` creates a separate bash process
+just for doing completion. Such processes have the environment
+variable `EMACS_BASH_COMPLETE` set to `t`, to help distinguish them
+from normal shell processes.
+
 ### Completion at point
 
 Additionally, you can enable bash completion in any buffer that contains bash 
@@ -92,42 +95,6 @@ and bind `bash-completion-from-eshell` to a custom shortcut.
    (point) t))
 ```
 
-## bash-completion-use-separate-processes
-
-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
-always runs in a separate process from the shell process. When it is 
-nil and when using shell-mode, bash-completion can use the same 
-bash process as shell mode, when it is available.
-
-Running a separate process just for completion has several downsides:
-
-- 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>
-
-  and bash would propose the new alias.
-  
-  Bash-completion.el can only do that if completion and shell are
-  running in the same process. 
-
-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.
-
-Emacs sets the environment variable INSIDE_EMACS to the processes
-started from it. Local processes started by bash-completion.el have
-the environment variable EMACS_BASH_COMPLETE set to t.
-
 ## CONTRIBUTING
 
 To report bugs, features or even to ask questions, please open an 
[issue](https://github.com/szermatt/emacs-bash-completion/issues). To 
contribute code or documentation, please open a [pull 
request](https://github.com/szermatt/emacs-bash-completion/pulls). 
diff --git a/bash-completion.el b/bash-completion.el
index 660c1fbb86..3feff28b0c 100644
--- a/bash-completion.el
+++ b/bash-completion.el
@@ -54,7 +54,6 @@
 ;;
 ;; 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
@@ -63,15 +62,8 @@
 ;;   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
 ;;
 ;; Once this is done, use <TAB> as usual to do dynamic completion from
@@ -79,67 +71,30 @@
 ;; for M-x `compile'. Note that the first completion is slow, as emacs
 ;; launches a new bash process.
 ;;
-;; You'll get better results if you turn on programmable bash completion.
-;; On Ubuntu, this means running:
-;;   sudo apt-get install bash-completion
-;; and then adding this to your .bashrc:
+;; Naturally, you'll get better results if you turn on programmable
+;; bash completion in your shell. Depending on how your system is set
+;; up, this might requires calling:
 ;;   . /etc/bash_completion
+;; from your ~/.bashrc.
 ;;
-;; 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>
-;; 
-;;   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.
+;; When called from a bash shell buffer,
+;; `bash-completion-dynamic-complete' communicates with the current shell
+;; to reproduce, as closely as possible the normal bash auto-completion,
+;; available on full terminals.
+;;
+;; When called from non-shell buffers, such as the prompt of M-x
+;; compile, `bash-completion-dynamic-complete' creates a separate bash
+;; process just for doing completion. Such processes have the
+;; environment variable EMACS_BASH_COMPLETE set to t, to help
+;; distinguish them from normal shell processes.
+;;
+;; See the documentation of the function
+;; `bash-completion-dynamic-complete-nocomint' to do bash completion
+;; from other buffers or completion engines.
 ;;
 ;; COMPATIBILITY
 ;;
-;; bash-completion.el is known to work with Bash 3 and 4, on Emacs,
+;; bash-completion.el is known to work with Bash 3, 4 and 5, on Emacs,
 ;; starting with version 24.3, under Linux and OSX. It does not work
 ;; on XEmacs.
 ;;
@@ -174,17 +129,14 @@ BASH completion is only available in the environment for 
which
   :type '(boolean)
   :group 'bash-completion)
 
-(defcustom bash-completion-use-separate-processes t
+(defcustom bash-completion-use-separate-processes nil
   "Enable/disable the use of separate processes to perform completion.
 
-When set to a non-nil value, separate processes will be used to
-perform completion. If nil, the process associated with the
-current buffer is used to perform completion. Even when this
-variable is set to nil, a separate process can be used to perform
-completion when:
-- the current buffer is not a comint buffer
-- no bash process is associated with the current buffer
-- an error occurred while trying to get completions"
+When set to a non-nil value, separate processes will always be
+used to perform completion. If nil, process associated with the
+current buffer will be used to perform completion from a shell
+buffer associated to a bash shell, and otherwise a separate process
+will be started to do completion."
   :type 'boolean
   :group 'bash-completion)
 
@@ -288,8 +240,10 @@ explanation.")
 (defvar bash-completion-output-buffer " *bash-completion*"
   "Buffer storing completion results.
 
-This variable is not used when
-`bash-completion-use-separate-processes' is non-nil.")
+This buffer is only used when creating separate processes for
+performing completion. See
+`bash-completion-use-separate-processes' for further
+explanation.")
 
 ;;; ---------- Internal variables and constants