bug#11348: 24.0.95; TAB-completion in shell-command produces d:\/foo on MS-Windows

[Eli Zaretskii <eliz@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.