From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Ilya N. Golubev" Newsgroups: gmane.emacs.bugs Subject: shell completion documentation [Re: comint loses prompt boundary] Date: Tue, 12 Dec 2006 21:07:23 +0300 Message-ID: <87slflasys.fsf@mo.msk.ru> References: <16k64g20tu.fsf@mo.msk.ru> <59ejumjzz2.fsf@mo.msk.ru> <843bazvd1b.fsf@mo.msk.ru> NNTP-Posting-Host: dough.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1166000516 1088 80.91.229.10 (13 Dec 2006 09:01:56 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 13 Dec 2006 09:01:56 +0000 (UTC) Cc: rms@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Dec 13 10:01:54 2006 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by dough.gmane.org with esmtp (Exim 4.50) id 1GuPzt-0002Jc-HZ for geb-bug-gnu-emacs@m.gmane.org; Wed, 13 Dec 2006 10:01:53 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GuPzt-0006PB-5I for geb-bug-gnu-emacs@m.gmane.org; Wed, 13 Dec 2006 04:01:53 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1GuC2Y-0006lO-0E for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2006 13:07:42 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1GuC2U-0006eX-Nv for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2006 13:07:41 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1GuC2U-0006eD-Hh for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2006 13:07:38 -0500 Original-Received: from [62.213.85.9] (helo=d-fens.mopniei.ru) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA:32) (Exim 4.52) id 1GuC2S-0006Sa-EV; Tue, 12 Dec 2006 13:07:37 -0500 Original-Received: from d-fens.mopniei.ru (localhost.localdomain [127.0.0.1]) by d-fens.mopniei.ru (8.13.7/8.13.7) with ESMTP id kBCI7OE6010476 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 12 Dec 2006 21:07:24 +0300 Original-Received: (from gin@localhost) by d-fens.mopniei.ru (8.13.7/8.13.7/Submit) id kBCI7NPA010475; Tue, 12 Dec 2006 21:07:23 +0300 X-Authentication-Warning: d-fens.mopniei.ru: gin set sender to gin@mo.msk.ru using -f Original-To: bug-gnu-emacs@gnu.org X-Mailman-Approved-At: Wed, 13 Dec 2006 04:01:43 -0500 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:15452 Archived-At: On Sun, 10 Sep 2006 21:37:04 +0400 in wrote about `comint-dynamic-complete' (<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