From: "Ilya N. Golubev" <gin@mo.msk.ru>
Cc: rms@gnu.org
Subject: shell completion documentation [Re: comint loses prompt boundary]
Date: Tue, 12 Dec 2006 21:07:23 +0300 [thread overview]
Message-ID: <87slflasys.fsf@mo.msk.ru> (raw)
In-Reply-To: comint_field_movement_fix@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
next prev parent reply other threads:[~2006-12-12 18:07 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2006-09-06 20:32 comint loses prompt boundary Ilya N. Golubev
2006-09-06 20:41 ` comint loses prompt boundary in cvs, too Ilya N. Golubev
[not found] ` <E1GLRDD-0000mS-2D@fencepost.gnu.org>
[not found] ` <59ejumjzz2.fsf@mo.msk.ru>
[not found] ` <E1GLjTm-0000cp-DO@fencepost.gnu.org>
[not found] ` <843bazvd1b.fsf@mo.msk.ru>
[not found] ` <comint_field_movement_fix@mo.msk.ru>
2006-12-12 18:07 ` Ilya N. Golubev [this message]
2006-12-12 18:08 ` field movement fix [Re: comint loses prompt boundary] Ilya N. Golubev
2006-12-15 16:11 ` field movement fix: `NEWS' change Ilya N. Golubev
2006-12-14 5:29 ` shell completion documentation [Re: comint loses prompt boundary] Richard Stallman
2006-12-14 17:51 ` shell completion documentation Ilya N. Golubev
2006-12-15 21:24 ` Richard Stallman
2006-12-15 23:48 ` bug reports vs manuals [Re: shell completion documentation] Ilya N. Golubev
2006-12-16 20:04 ` shell completion documentation Richard Stallman
2006-12-18 19:06 ` Ilya N. Golubev
2006-12-20 13:00 ` Richard Stallman
2006-12-20 20:59 ` what makes read it? [Re: shell completion documentation] Ilya N. Golubev
[not found] ` <mailman.1817.1166000505.2155.bug-gnu-emacs@gnu.org>
2006-12-13 15:39 ` shell completion documentation [Re: comint loses prompt boundary] Miles Bader
2006-12-13 18:07 ` Ilya N. Golubev
2006-12-14 3:49 ` Miles Bader
2006-12-15 23:48 ` comint loses prompt boundary Ilya N. Golubev
2006-08-24 17:15 ` checking for fields Ilya N. Golubev
2006-08-25 20:25 ` Richard Stallman
[not found] ` <02473b3c6f4154-gin@mo.msk.ru>
[not found] ` <02473b40868335-gin@mo.msk.ru>
2006-08-28 17:47 ` Ilya N. Golubev
2006-08-29 11:47 ` Richard Stallman
2006-08-29 20:30 ` pretest downloads [Re: checking for fields] Ilya N. Golubev
2006-08-30 17:58 ` Richard Stallman
2006-12-18 15:56 ` customizing inhibit-field-text-motion [Re: comint loses prompt boundary] Ilya N. Golubev
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87slflasys.fsf@mo.msk.ru \
--to=gin@mo.msk.ru \
--cc=rms@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).