bug#4563: 23.1; Doc for partial completion and completion styles

bug#4563: 23.1; Doc for partial completion and completion styles

[Drew Adams]

1. In the Emacs manual, add index entries for the predefined
completion styles: `basic', `partial-completion', `emacs22', and
`emacs21'.  Add index entries for partial completion (which covers
more than the completion style `partial-completion').
 
2. Node `Completion Commands' says that `*' matches any
character. AFAICT, this is incorrect. Instead, it matches any sequence
of characters (including an empty sequence).
 
3. The overall, default completion matching algorithm is described (in
node `Completion Commands'), but there is nothing there that indicates
which parts of this algorithm correspond to which parts of the default
value of option `completion-styles'.
 
There is thus no way for readers to know what the effect is of
including `partial-completion' (for example) in `completion-styles'.
That option is not even mentioned here, but it is central to the
behavior of completion, which this node describes.  There is no way
for readers to know how to change the default completion behavior -
there is not even a cross reference to node `Completion Options'.
 
4. The description in `Completion Commands' seems to imply that
characters `-' and ` ' have an effect only when "partial completion"
rules apply (presumably, that means when `partial-completion' is
included in `completion-styles', but there is no explanation here of
what "partial completion" is or what governs it).
 
That's OK as far as it goes (those two chars), but the description in
this node also seems to imply that `*' always has an effect, which is
incorrect.  AFAIK, `*' is part of the `partial-completion' style - if
you remove that style from `completion-styles', then `*' does not have
the effect described. The text covering `*' needs to be part of the
discussion of partial completion, to reduce its apparent scope.
 
5. `completion-styles' needs better documentation. It is mentioned in
node `Completion Options', but the description is not sufficient to
help users.  Each of the predefined completion styles needs to be
described.
 
For example, users should know what the effect is of including style
`emacs22' or `partial-completion'. It is not enough to describe the
overall effect of the default set of `completion-styles' - each style
should be described, so that users can effectively customize
`completion-styles'. That's the point of having a user option, and not
simply hard-coding the behavior.
 
6. The doc string of `completion-styles' is inadequate in this regard
also. It says simply "List of completion styles to use."
 
 
 
In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

bug#4563: 23.1; Doc for partial completion and completion styles

[Chong Yidong]

The documentation for completion styles has been completed in the trunk,
so this bug report is out of date; closing.