[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
shell completion documentation [Re: comint loses prompt boundary]
From: |
Ilya N. Golubev |
Subject: |
shell completion documentation [Re: comint loses prompt boundary] |
Date: |
Tue, 12 Dec 2006 21:07:23 +0300 |
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
- shell completion documentation [Re: comint loses prompt boundary],
Ilya N. Golubev <=
- field movement fix [Re: comint loses prompt boundary], Ilya N. Golubev, 2006/12/13
- Re: shell completion documentation [Re: comint loses prompt boundary], Richard Stallman, 2006/12/14
- Re: shell completion documentation, Ilya N. Golubev, 2006/12/15
- Re: shell completion documentation, Richard Stallman, 2006/12/16
- Re: shell completion documentation, Ilya N. Golubev, 2006/12/19
- Re: shell completion documentation, Richard Stallman, 2006/12/20
- what makes read it? [Re: shell completion documentation], Ilya N. Golubev, 2006/12/20