shell completion documentation [Re: comint loses prompt boundary]

["Ilya N. Golubev" <gin@mo.msk.ru>]

On Sun, 10 Sep 2006 21:37:04 +0400 in <Re: comint loses prompt
boundary> wrote about `comint-dynamic-complete' <test case>
(<843bazvd1b.fsf@mo.msk.ru>).

> It should be obvious from documentation; if it is not, it is bug in
> documentation.  Writing such a case is largely like writing a section
> of tutorial.  Will do so - in my copious free time.

Emacs manual actually only briefly mentions command completion,
without describing it in any useful way - both in version 21.4a and in
cvs head as of 2006-11-23.  So instead of writing tutorial, just
fixing this obvious documentation bug.

The patch is for cvs head as of 2006-11-23.  Note that it describes
command completion behavior as it *should* be, deliberately not saying
how it currently breaks if `inhibit-field-text-motion' is not `nil'.

	Document comint / shell completion properly.
	* misc.texi (Shell Completion): New node.
	(Shell Mode): Reference to it, instead of trying to describe all
	of completion features in place.
	(Shell):
	* emacs.texi (Top): Update node listings.

diff -ru man/emacs.texi man/emacs.texi
--- man/emacs.texi	2006-11-23 15:56:14.000000000 +0300
+++ man/emacs.texi	2006-12-06 05:36:22.710110720 +0300
@@ -762,6 +762,7 @@
 * Shell Prompts::       Two ways to recognize shell prompts.
 * Shell History::       Repeating previous commands in a shell buffer.
 * Directory Tracking::  Keeping track when the subshell changes directory.
+* Shell Completion::    Getting Emacs to do the typing for user.
 * Shell Options::       Options for customizing Shell mode.
 * Terminal emulator::   An Emacs window as a terminal emulator.
 * Term Mode::           Special Emacs commands used in Term mode.
diff -ru man/misc.texi man/misc.texi
--- man/misc.texi	2006-11-23 15:56:14.000000000 +0300
+++ man/misc.texi	2006-12-06 07:13:29.233344552 +0300
@@ -345,6 +345,7 @@
 * Shell Prompts::          Two ways to recognize shell prompts.
 * History: Shell History.  Repeating previous commands in a shell buffer.
 * Directory Tracking::     Keeping track when the subshell changes directory.
+* Completion: Shell Completion.  Getting Emacs to do the typing for user.
 * Options: Shell Options.  Options for customizing Shell mode.
 * Terminal emulator::      An Emacs window as a terminal emulator.
 * Term Mode::              Special Emacs commands used in Term mode.
@@ -521,18 +522,9 @@
 @item @key{TAB}
 @kindex TAB @r{(Shell mode)}
 @findex comint-dynamic-complete
-Complete the command name or file name before point in the shell buffer
-(@code{comint-dynamic-complete}).  @key{TAB} also completes history
-references (@pxref{History References}) and environment variable names.
-
-@vindex shell-completion-fignore
-@vindex comint-completion-fignore
-The variable @code{shell-completion-fignore} specifies a list of file
-name extensions to ignore in Shell mode completion.  The default
-setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
-ignore file names ending in @samp{~}, @samp{#} or @samp{%}.  Other
-related Comint modes use the variable @code{comint-completion-fignore}
-instead.
+Complete text before point in the shell buffer
+(@code{comint-dynamic-complete}); for details, see @ref{Shell
+Completion}.
 
 @item M-?
 @kindex M-? @r{(Shell mode)}
@@ -972,6 +964,54 @@
 alternative and more aggressive method of tracking changes in the
 current directory.
 
+@node Shell Completion
+@subsection Shell Mode Completion
+
+The @code{comint-dynamic-complete} command (@key{TAB} in Shell mode),
+like many other Shell mode commands, comes from general-purpose Comint
+mode (@pxref{Shell Mode}).  The exact set of completion features thus
+entirely depends on current buffer mode.  The only thing common
+between them is that completion command looks at text before point and
+attempts to complete it.  The rest of this section describes
+completion features in Shell mode only.  For completion features in
+other modes, see their respective descriptions, if any.
+
+@findex comint-replace-by-expanded-history
+@findex shell-dynamic-complete-environment-variable
+@findex shell-dynamic-complete-command
+@findex shell-replace-by-expanded-directory
+@findex comint-dynamic-complete-filename
+  Shell mode attempts completion treating text as history reference
+(@code{comint-replace-by-expanded-history}) (@pxref{History
+References}), environment variable name
+(@code{shell-dynamic-complete-environment-variable}), in turn.  If
+word before point is exactly at the beginning of shell command and
+does not contain directory separators, completion of command name is
+attempted (@code{shell-dynamic-complete-command}).  Directory stack
+references are expanded (@code{shell-replace-by-expanded-directory}).
+If none of these produces a match, file name completion is attempted
+(@code{comint-dynamic-complete-filename}).
+
+@vindex shell-completion-execonly
+  For purposes of command completion, the beginning of shell command
+is defined as where @code{shell-backward-command} (@pxref{Shell Mode})
+gets if @code{inhibit-field-text-motion} is @code{nil}.  Commands are
+searched in directories from @code{exec-path} (@pxref{Subprocess
+Creation,,,elisp, The Emacs Lisp Reference Manual}).  (Shell mode has
+no idea whatsoever of commands defined in shell subprocess itself,
+through functions, aliases and like.)  Unless
+@code{shell-completion-execonly} is @code{nil}, only executable files
+are considered as completion candidates.
+
+@vindex shell-completion-fignore
+@vindex comint-completion-fignore
+When attempting to complete file names, the variable
+@code{shell-completion-fignore} specifies a list of file name
+extensions to ignore.  The default setting is @code{nil}, but some
+users prefer @code{("~" "#" "%")} to ignore file names ending in
+@samp{~}, @samp{#} or @samp{%}.  Other related Comint modes use the
+variable @code{comint-completion-fignore} instead.
+
 @node Shell Options
 @subsection Shell Mode Options