bug#70217: [PATCH] Add substring-partial-completion style

[Eli Zaretskii <eliz@gnu.org>]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: 70217@debbugs.gnu.org,  monnier@iro.umontreal.ca
> Date: Sat, 25 May 2024 17:22:14 -0400
> 
> > This is a user option, so the doc string should be understandable by
> > users, not just by Lisp programmers who tinker with completion stuff.
> 
> OK, reworded that docstring heavily.  Maybe it's better now?

See below.

> > Also, this new option should be in NEWS, I think.
> 
> Added to NEWS and documentation, and the same for the new possible
> values of completion-styles.

Thanks.

> ++++
> +*** 'completion-styles' now can contain lists of bindings
                                                            ^
A period is missing there

> +An element of 'completion-styles' can be a symbol naming a completion
> +style in 'completion-styles-alist'.  Now it can also be a list of the

This is better rephrased like this:

  In addition to being a symbol naming a completion style, an element
  of 'completion-styles' can now be a list of the form...

> +form '(style ((variable value) ...))' where style is a symbol naming a

We usually up-case the meta-syntactic variables in these cases, so

   (STYLE ((VARIABLE VALUE) ...)

> +completion style.  'variable' will be bound to 'value' (without

Up-case "variable" and "value", and don't quote them.

> +evaluating it) while the style is executing.  This allows duplicating a
> +completion style with different values for completion-affecting

Not "duplicating" (which sounds negative), but something like
"multiple references to the same style".

> +An element can also be a list of the form \"(style ((variable value)
> +...))\".  \"style\" must be a symbol listed in
> +`completion-styles-alist', followed by a `let'-style list of
> +variable/value pairs.  \"variable\" will be bound to \"value\" (without
> +evaluating it) while the style is handling completion.  This allows
> +repeating the same style with different configurations.

Here, too, up-case STYLE, VARIABLE, and VALUE, and don't quote them,
since they are not literal symbols, they are "placeholders" --
references to something else.

> +(defcustom completion-pcm-anchored t
> +  "If non-nil, PCM matches only against the start of completions.

What is a "PCM"?  And what are "completions"?  I'm guessing you meant
something like

  If non-nil, completion candidates must match at beginning of completed string.

> +For example: when the string being completed is \"b/c\",
> +\"bbb/ccc\" is a valid completion according to
> +partial-completion.  If this is nil, then \"aaa/bbb/ccc\" and
> +\"aaabbb/ccc\" are also valid completions."

Isn't this not the best example?  "b/c" does NOT match "bbb/ccc" at
the beginning.  Or what am I missing?

Thanks.