[patch] Add a reference to eww-search-words to the manual

[patch] Add a reference to eww-search-words to the manual

[Jean-Christophe Helary]

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

I have a small patch that adds a line to the manual to show the reader 
how to do a web search with the region.

I had to actually search the web to learn how to do that :)
https://irreal.org/blog/?p=5609



-- 
Jean-Christophe Helary
@jchelary@emacs.ch
https://sr.ht/~brandelune/



[-- Attachment #2: 0001-Add-reference-to-eww-search-words-in-the-manual.patch --]
[-- Type: application/octet-stream, Size: 1193 bytes --]

From 5022dd602b75b76ac41ea62e178c37a7deb04ab2 Mon Sep 17 00:00:00 2001
From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
Date: Thu, 16 May 2024 17:36:14 +0900
Subject: [PATCH] Add reference to eww-search-words in the manual

---
 doc/misc/eww.texi | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi
index eec6b3c3299..dd480ddbcb3 100644
--- a/doc/misc/eww.texi
+++ b/doc/misc/eww.texi
@@ -83,8 +83,10 @@ Basics
 @findex eww
 @findex eww-open-file
 @vindex eww-search-prefix
+@findex eww-search-words
 @cindex eww
 @cindex Web Browsing
+@cindex Web Search
   You can open a URL or search the web with the command @kbd{M-x eww}.
 If the input doesn't look like a URL or domain name the web will be
 searched via @code{eww-search-prefix}.  The default search engine is
@@ -97,6 +99,10 @@ Basics
 buffer instead of reusing the default one, which is normally called
 @file{*eww*}.
 
+  You can also directly search the region by invoking @kbd{M-s M-w}
+(@code{eww-search-words}). If the region is empty, EWW will act as if
+you invoked it directly.
+
 @findex eww-quit
 @findex eww-reload
 @findex eww-copy-page-url
-- 
2.44.0

Re: [patch] Add a reference to eww-search-words to the manual

[Eli Zaretskii]

> Date: Thu, 16 May 2024 09:15:33 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> 
> I have a small patch that adds a line to the manual to show the reader 
> how to do a web search with the region.

We already document that, just in a different place: "Word Search".

I don't think this feature belongs to "Basics", it's too advanced and
too "niche".

Re: [patch] Add a reference to eww-search-words to the manual

[Jean-Christophe Helary]

> On May 16, 2024, at 21:01, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Thu, 16 May 2024 09:15:33 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> 
>> I have a small patch that adds a line to the manual to show the reader
>> how to do a web search with the region.
> 
> We already document that, just in a different place: "Word Search".

Why is it not in the web browser section?

I checked the EWW manual, did not find the answer, checked the web and 
found it.

But none of the web searches that pointed at the GNU manuals gave the 
section you mention.


> I don't think this feature belongs to "Basics", it's too advanced and
> too "niche".

Searching the web for strings is advanced and "niche" ?


-- 
Jean-Christophe Helary
@jchelary@emacs.ch
https://sr.ht/~brandelune/

Re: [patch] Add a reference to eww-search-words to the manual

[Eli Zaretskii]

> Date: Thu, 16 May 2024 13:04:56 +0000
> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
> Cc: emacs-devel@gnu.org
> 
> > We already document that, just in a different place: "Word Search".
> 
> Why is it not in the web browser section?

Because it isn't a Web-browsing feature, in its essence.

> I checked the EWW manual, did not find the answer, checked the web and 
> found it.
> 
> But none of the web searches that pointed at the GNU manuals gave the 
> section you mention.

The recommended way of finding the relevant stuff quickly in an Info
manual is by using the 'i' command.  Like so:

  i word search RET

or like so:

  i eww-search-words RET

or (if you don't know in which Info manual to look), like so:

  M-x info-apropos RET word search RET

> > I don't think this feature belongs to "Basics", it's too advanced and
> > too "niche".
> 
> Searching the web for strings is advanced and "niche" ?

No searching for a word on Web from Emacs is.  It definitely is NOT
"basics" of using Emacs.

Re: [patch] Add a reference to eww-search-words to the manual

[Jean-Christophe Helary]

> On May 16, 2024, at 22:44, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> Date: Thu, 16 May 2024 13:04:56 +0000
>> From: Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
>> Cc: emacs-devel@gnu.org
>> 
>>> We already document that, just in a different place: "Word Search".
>> 
>> Why is it not in the web browser section?
> 
> Because it isn't a Web-browsing feature, in its essence.
> 
>> I checked the EWW manual, did not find the answer, checked the web and
>> found it.
>> 
>> But none of the web searches that pointed at the GNU manuals gave the
>> section you mention.
> 
> The recommended way of finding the relevant stuff quickly in an Info
> manual is by using the 'i' command.  Like so:
> 
>  i word search RET

i web search RET

leads to nothing.

Maybe a cindex item in that section would be nice then.

>>> I don't think this feature belongs to "Basics", it's too advanced and
>>> too "niche".
>> 
>> Searching the web for strings is advanced and "niche" ?
> 
> No searching for a word on Web from Emacs is.  It definitely is NOT
> "basics" of using Emacs.

That's the reason I put it in the EWW manual and not the Emacs manual.

-- 
Jean-Christophe Helary
@jchelary@emacs.ch
https://sr.ht/~brandelune/

Re: [patch] Add a reference to eww-search-words to the manual

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> From 5022dd602b75b76ac41ea62e178c37a7deb04ab2 Mon Sep 17 00:00:00 2001
> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Thu, 16 May 2024 17:36:14 +0900
> Subject: [PATCH] Add reference to eww-search-words in the manual
>
> ---
>  doc/misc/eww.texi | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi
> index eec6b3c3299..dd480ddbcb3 100644
> --- a/doc/misc/eww.texi
> +++ b/doc/misc/eww.texi
> @@ -83,8 +83,10 @@ Basics
>  @findex eww
>  @findex eww-open-file
>  @vindex eww-search-prefix
> +@findex eww-search-words
>  @cindex eww
>  @cindex Web Browsing
> +@cindex Web Search
>    You can open a URL or search the web with the command @kbd{M-x eww}.
>  If the input doesn't look like a URL or domain name the web will be
>  searched via @code{eww-search-prefix}.  The default search engine is
> @@ -97,6 +99,10 @@ Basics
>  buffer instead of reusing the default one, which is normally called
>  @file{*eww*}.
>
> +  You can also directly search the region by invoking @kbd{M-s M-w}
> +(@code{eww-search-words}). If the region is empty, EWW will act as if
> +you invoked it directly.
> +
>  @findex eww-quit
>  @findex eww-reload
>  @findex eww-copy-page-url
> --
> 2.44.0

I'm not sure that we should mention this at the very top of the "Basics"
section in the EWW manual.  It seems less "basic" than things like
moving back and forward in browsing history, which would be mentioned
after `eww-search-words` with your patch.

Perhaps this command belongs in the "Advanced" rather than the "Basic"
section of the EWW manual?  Or further down in the "Basics" section?

BTW, in the future, please send patches to the bug-gnu-emacs list so
that we don't lose track of them.

Re: [patch] Add a reference to eww-search-words to the manual

[Jean-Christophe Helary]

> On May 19, 2024, at 7:11, Stefan Kangas <stefankangas@gmail.com> wrote:

> Perhaps this command belongs in the "Advanced" rather than the "Basic"
> section of the EWW manual?  Or further down in the "Basics" section?

A web browser is really an information search device for the web. And 
the region is one of the most basic objects in Emacs.

I have no opinion on where to place that information, but not having it 
in the EWW manual is weird.

Also a “web search” is not a “words search”. There should be a “web 
search” cindex in the Emacs section that Eli mentioned.

> BTW, in the future, please send patches to the bug-gnu-emacs list so
> that we don't lose track of them.

I’ll do. Sorry.

If you have a suggestion for an appropriate position in the EWW manual, 
I’ll send a patch.


-- 
Jean-Christophe Helary
@jchelary@emacs.ch
https://sr.ht/~brandelune/

Re: [patch] Add a reference to eww-search-words to the manual

[Stefan Kangas]

Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>
writes:

> If you have a suggestion for an appropriate position in the EWW manual,
> I’ll send a patch.

How about at the very start of the "Advanced" section?

On a related note, the EWW manual could probably do with major
restructuring into sections with titles that better describe its various
features.