From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#11348: 24.0.95; TAB-completion in shell-command produces d:\/foo on MS-Windows Date: Sat, 05 May 2012 15:47:45 +0300 Message-ID: <83zk9m4wwe.fsf@gnu.org> References: <83obqeiwb0.fsf@gnu.org> <83mx5n6ceu.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: dough.gmane.org 1336222220 22054 80.91.229.3 (5 May 2012 12:50:20 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 5 May 2012 12:50:20 +0000 (UTC) Cc: 11348@debbugs.gnu.org To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat May 05 14:50:19 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1SQeRG-0001eS-Tv for geb-bug-gnu-emacs@m.gmane.org; Sat, 05 May 2012 14:50:19 +0200 Original-Received: from localhost ([::1]:59354 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SQeRG-00060z-Bx for geb-bug-gnu-emacs@m.gmane.org; Sat, 05 May 2012 08:50:18 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:55412) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SQeRD-00060M-7s for bug-gnu-emacs@gnu.org; Sat, 05 May 2012 08:50:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SQeRB-0003FE-6P for bug-gnu-emacs@gnu.org; Sat, 05 May 2012 08:50:14 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:35810) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SQeRB-0003F7-2q for bug-gnu-emacs@gnu.org; Sat, 05 May 2012 08:50:13 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1SQeSv-0001ad-U3 for bug-gnu-emacs@gnu.org; Sat, 05 May 2012 08:52:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 05 May 2012 12:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 11348 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 11348-submit@debbugs.gnu.org id=B11348.13362223076087 (code B ref 11348); Sat, 05 May 2012 12:52:01 +0000 Original-Received: (at 11348) by debbugs.gnu.org; 5 May 2012 12:51:47 +0000 Original-Received: from localhost ([127.0.0.1]:36844 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1SQeSh-0001a7-0F for submit@debbugs.gnu.org; Sat, 05 May 2012 08:51:47 -0400 Original-Received: from mtaout21.012.net.il ([80.179.55.169]:55077) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1SQeSd-0001Zs-4f for 11348@debbugs.gnu.org; Sat, 05 May 2012 08:51:45 -0400 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0M3J00A00VF9JE00@a-mtaout21.012.net.il> for 11348@debbugs.gnu.org; Sat, 05 May 2012 15:49:46 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.210.75]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M3J00A1HVMYGA70@a-mtaout21.012.net.il>; Sat, 05 May 2012 15:49:46 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:59782 Archived-At: > From: Stefan Monnier > Cc: 11348@debbugs.gnu.org > Date: Fri, 04 May 2012 19:32:41 -0400 > > >> > Perhaps Stefan could at some point add some documentation about the > >> > internals, that would allow mere mortals such as myself debug the > >> > completion code. > >> I'd love to, but I'm much too deeply in it to know what needs more > >> documentation, so fire away your questions and I'll reply with > >> comments&docstrings. > > A useful beginning would be some overview of the design and > > AFAIK that's in the lispref Where exactly? The only place I found is the "Completion" section and what's under it. If this is what you meant, then this part of the manual documents how to _use_ the APIs; it does not describe the design and the internals. And neither should it, IMO: the lipsref manual is meant for Lisp programmers, not for Emacs maintainers. If any place in that manual is suitable for the kind of information I'm looking for, it's the "Internals" appendix. Commentary in the code is an even better place. As for lispref, some parts of what's written need to be clarified. For example, in "Programmed Completion": `(boundaries . SUFFIX)' This specifies a `completion-boundaries' operation. The function should return `(boundaries START . END)', where START is the position of the beginning boundary in the specified string, and END is the position of the end boundary in SUFFIX. This should at least include a cross-reference to where completion-boundaries are described; without that, it's not even clear what "boundaries" are being referenced here and what exactly is SUFFIX. `metadata' This specifies a request for information about the state of the current completion. The function should return an alist, as described below. The alist may contain any number of elements. Does the last sentence mean that not all of the elements "described below" should always be returned? If so, when to return which ones? `category' The value should be a symbol describing what kind of text the completion function is trying to complete. If the symbol matches one of the keys in `completion-category-overrides', the usual completion behavior is overridden. *Note Completion Variables::. A list of available categories is missing here. Also, this begs the question "what will the caller do with the category?", so you should at least say something about that. `annotation-function' The value should be a function for "annotating" completions. The function should take one argument, STRING, which is a possible completion. It should return a string, which is displayed after the completion STRING in the `*Completions*' buffer. This is not clear at all. What are "annotations" in this context, and what are the possible uses by the caller of the annotations returned by the function? The reference to *Completions* buffer is no more than a hint, and falls short of clarifying the issue (I couldn't figure out what is "displayed after the completion STRING"). Also, are there any standard functions that can be reused for this? if so, name them. `cycle-sort-function' The value should be a function for sorting completions, when `completion-cycle-threshold' is non-`nil' and the user is cycling through completion alternatives. *Note Completion Options: (emacs)Completion Options. Its argument list and return value are the same as for `display-sort-function'. Again, if there are standard cycling functions available, name them. > > description of the control and data flow in several popular use-cases. > > Not sure what that could look like. Would the following be helpful? Yes, very. A list of completion predicates used for completing on the most popular objects (files, buffers, shell commands, etc.) would also be extremely useful. > For completion--file-name-table, after hitting TAB, here's the > general way it is supposed to work (seen from the completion-table): ^^^^^^^^^^^^^^^^ What is that "completion-table" you refer to here? > - the `metadata' method is called, so the caller can know which > completion styles should be used, as well as whether escaping/quoting > should take place. How does the caller know about escaping/quoting from metadata? Thanks.