From: Eli Zaretskii <eliz@gnu.org>
To: Stefan Monnier <monnier@iro.umontreal.ca>
Cc: 11348@debbugs.gnu.org
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 [thread overview]
Message-ID: <83zk9m4wwe.fsf@gnu.org> (raw)
In-Reply-To: <jwvy5p7bkjz.fsf-monnier+emacs@gnu.org>
> From: Stefan Monnier <monnier@iro.umontreal.ca>
> 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.
next prev parent reply other threads:[~2012-05-05 12:47 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-04-26 11:09 bug#11348: 24.0.95; TAB-completion in shell-command produces d:\/foo on MS-Windows Eli Zaretskii
2012-05-04 7:10 ` Eli Zaretskii
2012-05-04 14:29 ` Chong Yidong
2012-05-04 14:54 ` Eli Zaretskii
2012-05-04 15:07 ` Drew Adams
2012-05-04 15:36 ` Chong Yidong
2012-05-04 15:02 ` Eli Zaretskii
2012-05-04 15:46 ` Chong Yidong
2012-05-04 17:01 ` Eli Zaretskii
2012-05-04 17:59 ` Stefan Monnier
2012-05-04 18:15 ` Eli Zaretskii
2012-05-04 23:32 ` Stefan Monnier
2012-05-05 0:22 ` Drew Adams
2012-05-05 12:47 ` Eli Zaretskii [this message]
2012-05-05 4:20 ` Stefan Monnier
2012-05-05 6:33 ` Eli Zaretskii
2012-05-07 8:01 ` Chong Yidong
2012-05-07 17:40 ` Eli Zaretskii
2012-05-07 15:27 ` Stefan Monnier
2012-05-07 15:44 ` Drew Adams
2012-05-07 16:11 ` Chong Yidong
2012-05-08 0:27 ` Stefan Monnier
2012-05-08 18:56 ` Eli Zaretskii
2012-05-09 17:22 ` Stefan Monnier
2012-05-09 18:07 ` Eli Zaretskii
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83zk9m4wwe.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=11348@debbugs.gnu.org \
--cc=monnier@iro.umontreal.ca \
/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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.