[nongnu] elpa/bash-completion fd7e0e6fbe 078/313: added documentation

[ELPA Syncer]

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

    added documentation
---
 bash-completion.el | 104 ++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 80 insertions(+), 24 deletions(-)

diff --git a/bash-completion.el b/bash-completion.el
index fe20bafe87..c5b7590111 100644
--- a/bash-completion.el
+++ b/bash-completion.el
@@ -1,54 +1,110 @@
 ;;; bash-completion.el --- BASH completion for the shell buffer
 
+;; Author: Stephane Zermatten <szermatt@gmx.net>
 
 ;;; Commentary:
 ;;
-;; TODO(szermatt)
+;; This file defines dynamic completion hooks for shell-mode and
+;; shell-command that are based on bash completion.
 ;;
-;; .bashrc:
+;; Bash completion for emacs:
+;; - is aware of bash builtins, aliases and functions
+;; - does file expansion inside of colon-separated variables
+;;   and after redirections (> or <)
+;; - escapes special characters when expanding file names
+;; - is configurable through programmable bash completion
+;;
+;; When the first completion is requested in shell model or a shell
+;; command, bash-completion.el starts a separate bash
+;; process. Bash-completion.el then uses this process to do the actual
+;; completion and includes it into emacs completion suggestions.
+;;
+;; INSTALLATION
+;;
+;; 1. copy bash-completion.el into a directory that's on emacs load-path
+;; 2. add this into your .emacs file:
+;;   (autoload 'bash-completion-dynamic-complete \"bash-completion\"
+;;     \"BASH completion hook\")
+;;   (add-hook 'shell-dynamic-complete-functions
+;;     'bash-completion-dynamic-complete)
+;;   (add-hook 'shell-command-complete-functions
+;;     'bash-completion-dynamic-complete))
+;; 3. reload your .emacs (M-x eval-buffer) or restart
+;;
+;; Once this is done, use <TAB> as usual do dynamic completion from
+;; shell mode or a shell command minibuffer, such as the one started
+;; for `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:
+;;   . /etc/bash_completion
+;;
+;; Once this is done, and whenever you make changes to you .bashrc,
+;; call `bash-completion-restart' 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 shel-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:
-;; (autoload 'bash-completion-dynamic-complete \"bash-completion\"
-;;   \"BASH completion hook\")
-;; (add-hook 'shell-dynamic-complete-functions
-;;       'bash-completion-dynamic-complete)
-;; (add-hook 'shell-command-complete-functions
-;;       'bash-completion-dynamic-complete))
+;; 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.
 ;;
-;; Interactive command:
-;; 'bash-completion-reset`
+;; CAVEATS
 ;;
-;; Tried on:
+;; Using a separate process for doing the completion has several
+;; important disadvantages:
+;; - bash completion is slower than standard emacs completion
+;; - 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-restart'.
 ;;
-;; Emacs:
+;; COMPATIBILITY
 ;;
-;; GNU Emacs 22.3.1 (Aquamacs 1.7)
-;; GNU Emacs 22.1.1 (OSX 10.5)
-;; GNU Emacs 22.1.1 (Ubuntu Dapper)
-;; GNU Emacs 23.0.94.1 (custom build)
-;;    Workaround for this version: Disable minibuffer messages.
-;;    (defun minibuffer-message (message &rest args))
+;; bash-completion.el is quite sensitive to the OS and BASH version.
+;; This package is known to work on the following environment:
+;;   GNU Emacs 22.3.1 (Aquamacs 1.7)
+;;   GNU Emacs 22.1.1 (OSX 10.5)
+;;   GNU Emacs 22.1.1 (Ubuntu 8.04)
+;;   GNU Emacs 23.0.94.1 (Ubuntu 8.10)
 ;;
+;; and using the following bash versions:
+;;   BASH 3.2.17
+;;   BASH 3.2.32
 ;;
-;; Environments:
-;; OSX 10.5
-;; Ubuntu 8.04
-;; Ubuntu 8.10
+;; bash-completion.el does not works on XEmacs.
 ;;
 
 ;;; History:
 ;;
+;; Current version:
 ;; $Id$
+;;
 
 (require 'comint)
 
 ;;; Code:
 
-
 ;;; ---------- Customization
 (defgroup bash-completion nil
   "BASH configurable command-line completion "