bug#41006: 26.3; regular expressions documentation

[jan via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

Well there's a name I recognise!  Wasn't expecting that.

Anyway, allow me to push back slightly.  I have long ago training in
user interfaces, but I'm no expert.

To transmit info it has to be, among other things, 'evident' or
'obvious'.  In this case I'd say that means visible.
Section "15.6 Syntax of Regular Expressions" is very visible.  It's
easily navigable up and down by mouse or keyboard, also the scroll bar
gives clearer indication of how much there is and where you are on the
page.  Great stuff.
Even better it's easy to browse 'exhaustively' - if I start at the top
of the page and into the bottom I know I've covered everything.  I
find that property very useful as I do *a lot* of technical reading.

But it's only showing about half the information.  There is no evident
indication that there is more.  I'm not the first person to get
confused by this
(<http://emacs.1067599.n8.nabble.com/regex-question-td75006.html> "The
answer you seek seems to be in a separate section (Regexp Backslash),
at least in the version I am currently using" - that took about 15
seconds to find).

If you combine  both sections together it would be visible and
exhaustive.  Whether it would be too long is something I can't answer,
but my opinion would be it's okay (based purely on my evidence-free
opinion).

If you don't want to combine them then make the other half reasonably
visible (it's rather odd that the top of the section points you at
"(elisp)Regular Expressions" but not to backslash section).  About the
only evidence there is a second section,  is right at the very top in
the breadcrumbs (Next: Regexp Backslash) and a little hint at the end
("...since backslashes can legitimately precede these characters where
they _have_ special meaning, as in...").

Specifically may have suggests that the start that currently looks like this:

"
15.6 Syntax of Regular Expressions
==================================

This section (and this manual in general)...
"

perhaps have a direct link to the next section, like this

"
15.6 Syntax of Regular Expressions
==================================

Non-Backslash Regular Expressions   <--- dead link because you're here
Backslash Regular Expressions (more regexp syntax)  <--- live link

This section (and this manual in general)...
"

And perhaps repeat that link at the end of that help page as well.

Or something else.  Whatever you think works, assuming you even think
I have a point.

regards

jan



On 03/05/2020, Richard Stallman <rms@gnu.org> wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > 1. Suggest emacs' excellent documentation should not distinguish
> between
>   > Regexps and Regexp Backslash in the manual.
>   > That is, these 2 should be combined:
>
> When a node is too long, browsing in Info becomes inconvenient.
> Therefore, we look for a reading way to split up the node.
>
> We found that way to split up the node on regexps.
> There is no logical _need_ to split the topic that way, but it is not
> unreasonable, so it was a valid solution to the overlongness.
>
> I expect that many nodes are too long now, and we should look for
> reasonable ways to split them.
>
> --
> Dr Richard Stallman
> Chief GNUisance of the GNU Project (https://gnu.org)
> Founder, Free Software Foundation (https://fsf.org)
> Internet Hall-of-Famer (https://internethalloffame.org)
>
>
>