bug#62836: [PATCH] Provide an example of using fuzzier completion.

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[Spencer Baugh]

[-- Attachment #1: Type: text/plain, Size: 509 bytes --]

Tags: patch


Hopefully a useful documentation improvement.



In GNU Emacs 29.0.60 (build 3, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.15.12, Xaw scroll bars) of 2023-03-13 built on
 igm-qws-u22796a
Repository revision: e759905d2e0828eac4c8164b09113b40f6899656
Repository branch: emacs-29
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: CentOS Linux 7 (Core)

Configured using:
 'configure --with-x-toolkit=lucid --with-modules
 --with-gif=ifavailable'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Provide-an-example-of-using-fuzzier-completion.patch --]
[-- Type: text/patch, Size: 1803 bytes --]

From b8d081b19cb46965c6fc170253702c53d53f2ee2 Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh@janestreet.com>
Date: Fri, 14 Apr 2023 10:58:17 -0400
Subject: [PATCH] Provide an example of using fuzzier completion.

In my experience, new users of vanilla Emacs often complain about the
lack of fuzzy completion by default.  However, the "basic" completion
style provides a decent amount of fuzziness out of the box.  We should
explain this a little more to users.  (I myself have often had to
explain this.)

* doc/emacs/mini.texi (Completion Example):
Provide an example of using more advanced "basic" completion.
---
 doc/emacs/mini.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 6fb312ec321..812218d1ab2 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -326,6 +326,20 @@ Completion Example
   Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to
 enter @samp{auto-fill-mode}.
 
+  @key{TAB} also works while point is not at the end of the
+minibuffer.  If you type @kbd{M-x a u t o c m o d e}, then @kbd{C-b}
+several times to move point back before the @samp{mode}, you can hit
+@key{TAB} to insert text between @samp{autoc} and @samp{mode}
+so that the minibuffer contains @code{autoconf-mode}.
+
+  When point is not at the end of the minibuffer and you hit
+@kbd{TAB}, completion will fill in text both at point and at the end
+of the minibuffer.  So you could also type @kbd{M-x a u t o c m o},
+@kbd{C-b} twice to move point back before the @samp{mo}, and then
+@key{TAB} will insert the text @samp{onf-} at point and @samp{de} at
+the end of the minibuffer, so that the minibuffer contains
+@code{autoconf-mode}.
+
 @node Completion Commands
 @subsection Completion Commands
 
-- 
2.30.2

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Date: Fri, 14 Apr 2023 11:01:54 -0400
> 
> >From b8d081b19cb46965c6fc170253702c53d53f2ee2 Mon Sep 17 00:00:00 2001
> From: Spencer Baugh <sbaugh@janestreet.com>
> Date: Fri, 14 Apr 2023 10:58:17 -0400
> Subject: [PATCH] Provide an example of using fuzzier completion.
> 
> In my experience, new users of vanilla Emacs often complain about the
> lack of fuzzy completion by default.  However, the "basic" completion
> style provides a decent amount of fuzziness out of the box.  We should
> explain this a little more to users.  (I myself have often had to
> explain this.)

Are the examples you suggest to add really considered as "fuzzy
completion"?

> +  @key{TAB} also works while point is not at the end of the
> +minibuffer.  If you type @kbd{M-x a u t o c m o d e}, then @kbd{C-b}
> +several times to move point back before the @samp{mode}, you can hit
> +@key{TAB} to insert text between @samp{autoc} and @samp{mode}
> +so that the minibuffer contains @code{autoconf-mode}.
> +
> +  When point is not at the end of the minibuffer and you hit
> +@kbd{TAB}, completion will fill in text both at point and at the end
> +of the minibuffer.  So you could also type @kbd{M-x a u t o c m o},
> +@kbd{C-b} twice to move point back before the @samp{mo}, and then
> +@key{TAB} will insert the text @samp{onf-} at point and @samp{de} at
> +the end of the minibuffer, so that the minibuffer contains
> +@code{autoconf-mode}.

I'd prefer to have only the second example, as it demonstrates the
more general behavior, which includes the one described by the first
example.

Also, we use @kbd{M-x autocmo}, without the spaces between characters,
in such cases.  (It is actually enough to type "M-x autocm" followed
by a single C-b, to show the behavior in this case.)

Please be consistent about your markup: if you use @samp{onf-},
pleased also use @samp{autoconf-mode}.

Finally, please use @kbd{@key{TAB}} in the context that calls for the
user to press the TAB key.

Thanks.

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[sbaugh]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Spencer Baugh <sbaugh@janestreet.com>
>> Date: Fri, 14 Apr 2023 11:01:54 -0400
>> 
>> >From b8d081b19cb46965c6fc170253702c53d53f2ee2 Mon Sep 17 00:00:00 2001
>> From: Spencer Baugh <sbaugh@janestreet.com>
>> Date: Fri, 14 Apr 2023 10:58:17 -0400
>> Subject: [PATCH] Provide an example of using fuzzier completion.
>> 
>> In my experience, new users of vanilla Emacs often complain about the
>> lack of fuzzy completion by default.  However, the "basic" completion
>> style provides a decent amount of fuzziness out of the box.  We should
>> explain this a little more to users.  (I myself have often had to
>> explain this.)
>
> Are the examples you suggest to add really considered as "fuzzy
> completion"?

True, this feature isn't fuzzy completion at all.  But in my experience
it is a partial substitute for fuzzy completion - it solve some of the
same use cases.  (for example, if you know two substrings of the string
you're trying to complete, you can use fuzzy completion to find the
target string or you can use this feature)

>> +  @key{TAB} also works while point is not at the end of the
>> +minibuffer.  If you type @kbd{M-x a u t o c m o d e}, then @kbd{C-b}
>> +several times to move point back before the @samp{mode}, you can hit
>> +@key{TAB} to insert text between @samp{autoc} and @samp{mode}
>> +so that the minibuffer contains @code{autoconf-mode}.
>> +
>> +  When point is not at the end of the minibuffer and you hit
>> +@kbd{TAB}, completion will fill in text both at point and at the end
>> +of the minibuffer.  So you could also type @kbd{M-x a u t o c m o},
>> +@kbd{C-b} twice to move point back before the @samp{mo}, and then
>> +@key{TAB} will insert the text @samp{onf-} at point and @samp{de} at
>> +the end of the minibuffer, so that the minibuffer contains
>> +@code{autoconf-mode}.
>
> I'd prefer to have only the second example, as it demonstrates the
> more general behavior, which includes the one described by the first
> example.

Agreed, makes sense.

> Also, we use @kbd{M-x autocmo}, without the spaces between characters,
> in such cases.  (It is actually enough to type "M-x autocm" followed
> by a single C-b, to show the behavior in this case.)
>
> Please be consistent about your markup: if you use @samp{onf-},
> pleased also use @samp{autoconf-mode}.
>
> Finally, please use @kbd{@key{TAB}} in the context that calls for the
> user to press the TAB key.

Hm, the text already present in the "Completion Example" section doesn't
use @kbd{@key{TAB}}, should it be doing that?

Here's the revised version incorporating all of these:

  @key{TAB} also works while point is not at the end of the
minibuffer.  In that case, it will fill in text both at point and at
the end of the minibuffer.  If you type @kbd{M-x autocm}, then press
@kbd{C-b} to move point before the @samp{m}, you can type
@kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
at the end of the minibuffer, so that the minibuffer contains
@samp{autoconf-mode}.

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[Eli Zaretskii]

> From: sbaugh@catern.com
> Date: Sat, 15 Apr 2023 22:22:09 +0000 (UTC)
> Cc: Spencer Baugh <sbaugh@janestreet.com>, 62836@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Finally, please use @kbd{@key{TAB}} in the context that calls for the
> > user to press the TAB key.
> 
> Hm, the text already present in the "Completion Example" section doesn't
> use @kbd{@key{TAB}}, should it be doing that?

Those are mistakes--these 2 paragraphs:

    If you type @key{TAB} again immediately, it cannot determine the
  next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
  does not add any characters; instead, @key{TAB} displays a list of all
  possible completions in another window.

    Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
  the only command name that starts with this is @code{auto-fill-mode}.
  If you now type @key{TAB}, completion fills in the rest of the
  argument @samp{auto-fill-mode} into the minibuffer.

should use @kbd{@key{TAB}} where they say "when you type".  Feel free
to fix those blunders as part of the patch.

> Here's the revised version incorporating all of these:
> 
>   @key{TAB} also works while point is not at the end of the
> minibuffer.  In that case, it will fill in text both at point and at
> the end of the minibuffer.  If you type @kbd{M-x autocm}, then press
> @kbd{C-b} to move point before the @samp{m}, you can type
> @kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
> at the end of the minibuffer, so that the minibuffer contains
> @samp{autoconf-mode}.

LGTM, thanks.

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[Spencer Baugh]

[-- Attachment #1: Type: text/plain, Size: 1710 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:
>> From: sbaugh@catern.com
>> Date: Sat, 15 Apr 2023 22:22:09 +0000 (UTC)
>> Cc: Spencer Baugh <sbaugh@janestreet.com>, 62836@debbugs.gnu.org
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > Finally, please use @kbd{@key{TAB}} in the context that calls for the
>> > user to press the TAB key.
>> 
>> Hm, the text already present in the "Completion Example" section doesn't
>> use @kbd{@key{TAB}}, should it be doing that?
>
> Those are mistakes--these 2 paragraphs:
>
>     If you type @key{TAB} again immediately, it cannot determine the
>   next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
>   does not add any characters; instead, @key{TAB} displays a list of all
>   possible completions in another window.
>
>     Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
>   the only command name that starts with this is @code{auto-fill-mode}.
>   If you now type @key{TAB}, completion fills in the rest of the
>   argument @samp{auto-fill-mode} into the minibuffer.
>
> should use @kbd{@key{TAB}} where they say "when you type".  Feel free
> to fix those blunders as part of the patch.
>
>> Here's the revised version incorporating all of these:
>> 
>>   @key{TAB} also works while point is not at the end of the
>> minibuffer.  In that case, it will fill in text both at point and at
>> the end of the minibuffer.  If you type @kbd{M-x autocm}, then press
>> @kbd{C-b} to move point before the @samp{m}, you can type
>> @kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
>> at the end of the minibuffer, so that the minibuffer contains
>> @samp{autoconf-mode}.
>
> LGTM, thanks.

Cool, here's the patch then:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Give-an-example-of-completion-with-point-not-at-end-.patch --]
[-- Type: text/x-patch, Size: 2445 bytes --]

From 592541aaec70400e69f27d9f2f2a6972f203e30f Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh@janestreet.com>
Date: Tue, 18 Apr 2023 18:03:36 -0400
Subject: [PATCH] Give an example of completion with point not at end of
 minibuffer

This can be a useful substitute for full-on fuzzy completion, as
provided by other completion styles and completion packages.

* doc/emacs/mini.texi (Completion Example): Give an example of
completion with point not at end of minibuffer.  Also, use
@kbd{@key{TAB}} when telling the user to hit TAB.
---
 doc/emacs/mini.texi | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 812218d1ab2..c75d68b4f69 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -313,14 +313,14 @@ Completion Example
 called @code{authorize-me} was defined, Emacs could only complete
 as far as @samp{aut}.)
 
-  If you type @key{TAB} again immediately, it cannot determine the
-next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
-does not add any characters; instead, @key{TAB} displays a list of all
-possible completions in another window.
+  If you type @kbd{@key{TAB}} again immediately, it cannot determine
+the next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So
+it does not add any characters; instead, @key{TAB} displays a list of
+all possible completions in another window.
 
   Next, type @kbd{-f}.  The minibuffer now contains @samp{auto-f}, and
 the only command name that starts with this is @code{auto-fill-mode}.
-If you now type @key{TAB}, completion fills in the rest of the
+If you now type @kbd{@key{TAB}}, completion fills in the rest of the
 argument @samp{auto-fill-mode} into the minibuffer.
 
   Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to
@@ -340,6 +340,14 @@ Completion Example
 the end of the minibuffer, so that the minibuffer contains
 @code{autoconf-mode}.
 
+  @key{TAB} also works while point is not at the end of the
+minibuffer.  In that case, it will fill in text both at point and at
+the end of the minibuffer.  If you type @kbd{M-x autocm}, then press
+@kbd{C-b} to move point before the @samp{m}, you can type
+@kbd{@key{TAB}} to insert the text @samp{onf-} at point and @samp{ode}
+at the end of the minibuffer, so that the minibuffer contains
+@samp{autoconf-mode}.
+
 @node Completion Commands
 @subsection Completion Commands
 
-- 
2.30.2

bug#62836: [PATCH] Provide an example of using fuzzier completion.

[Eli Zaretskii]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Cc: sbaugh@catern.com,  62836@debbugs.gnu.org
> Date: Tue, 18 Apr 2023 18:07:26 -0400
> 
> > LGTM, thanks.
> 
> Cool, here's the patch then:

Thanks.  It failed to apply (I guess the patch was not against the
current repository?).  So I applied it manually (to the emacs-29
branch).

Thanks.