all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: "Mattias Engdegård" <mattiase@acm.org>, jan <rtm443x@googlemail.com>
Cc: Richard Stallman <rms@gnu.org>, 41006@debbugs.gnu.org
Subject: bug#41006: 26.3; regular expressions documentation
Date: Sun, 3 May 2020 13:08:14 -0700 (PDT)	[thread overview]
Message-ID: <824a1116-8e91-409f-95ff-69ef168a359d@default> (raw)
In-Reply-To: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org>

> The disposition of the regexp documentation could be improved, yes.
> Currently it's arranged by syntax, which is the implementor's view,
> rather than by function, which is the user's.

FWIW, I disagree with that characterization.

Especially when it comes to the doc for regexp
patterns, as a user I want it to be organized
according to syntax.  A regexp (regardless of
the particular syntax system used for regexps
in a given language) is very much about syntax.

And if you try to organize the content instead
by the functions performed by different regexp
constructs (syntax) or their combinations, then
there are a zillion, conflicting possibilities.

A given such "use" organization might be perfect
for user U1 when looking for help with use case
C1, but it won't be so great for user U2 or even
for U1 when looking for help with a different use
case.

That's the trouble with use-case/task-oriented
doc.  Everyone thinks it's a great idea: "If I
just had some doc that directly addressed this
particular problem...".  And it is a great idea
as far as it goes.  But in general it is not a
good way to structure doc.  A set of tasks/use
cases is not easily structured in a useful way
for users.  Searching the doc can help, but
that's about it.

The Elisp manual is a combination of reference
doc (what) with user-guide doc (how-to).  Guide
doc can usefully include task help.  But guide
doc necessarily supplements - stands on top of -
reference doc; it's no substitute for it.

And when it comes to regexp doc in the Elisp
manual, we need solid reference doc, first and
foremost.  And the best organization for it in
this case is in terms of regexp syntax.

That doesn't mean that we can't _also_ have
some guidance (how-to) doc, which directly
addresses _using_ regexps: what you can (and
can't) do with them, and examples of how to
make best use of them in certain cases.

(Just one opinion.)





  parent reply	other threads:[~2020-05-03 20:08 UTC|newest]

Thread overview: 50+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-01 19:06 bug#41006: 26.3; regular expressions documentation jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-03  3:40 ` Richard Stallman
2020-05-03 10:31   ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-03 13:07 ` Mattias Engdegård
2020-05-03 14:00   ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-03 20:08   ` Drew Adams [this message]
2020-05-03 20:31     ` Stefan Kangas
2020-05-04  1:00       ` Drew Adams
2020-05-05  2:56       ` Richard Stallman
2020-05-05 10:05         ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-05 16:51           ` Mattias Engdegård
2020-05-05 18:20         ` Stefan Kangas
2020-05-05 18:40           ` Drew Adams
2020-05-05 19:04             ` Stefan Kangas
2020-05-05 19:42               ` Drew Adams
2020-05-05 21:23                 ` Stefan Kangas
2020-05-05 21:37                   ` Drew Adams
2020-05-07  2:40                   ` Richard Stallman
2020-05-09  3:48               ` Richard Stallman
2020-05-07  2:41             ` Richard Stallman
2020-05-07  3:17               ` Drew Adams
2020-05-08  2:51                 ` Richard Stallman
2020-05-07 10:31               ` Stefan Kangas
2020-05-07  2:41           ` Richard Stallman
2020-05-07  3:18             ` Drew Adams
2020-05-07 10:32             ` Stefan Kangas
2020-05-08  2:49               ` Richard Stallman
2020-05-08  6:47                 ` Eli Zaretskii
2020-05-08 10:10                   ` Stefan Kangas
2020-05-08 10:31                     ` Eli Zaretskii
2020-05-08 18:17                       ` Stefan Kangas
2020-05-08 18:47                         ` Eli Zaretskii
2020-05-08 20:09                           ` Stefan Kangas
2020-05-08 10:04                 ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-09  3:56                   ` Richard Stallman
2020-05-08 16:49                 ` Drew Adams
2020-05-09  3:53                   ` Richard Stallman
2020-05-09  3:54                   ` Richard Stallman
2020-05-07  2:41           ` Richard Stallman
2020-05-04  3:10   ` Richard Stallman
2020-05-04  9:13     ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-05  2:56       ` Richard Stallman
2020-05-05 10:02         ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-05 17:12     ` Mattias Engdegård
2020-05-05 17:40       ` Eli Zaretskii
2020-05-05 17:50         ` jan via Bug reports for GNU Emacs, the Swiss army knife of text editors
2020-05-05 18:09         ` Stefan Kangas
2020-05-05 18:23           ` Eli Zaretskii
2020-05-07  2:42       ` Richard Stallman
2022-04-29 12:22 ` Lars Ingebrigtsen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=824a1116-8e91-409f-95ff-69ef168a359d@default \
    --to=drew.adams@oracle.com \
    --cc=41006@debbugs.gnu.org \
    --cc=mattiase@acm.org \
    --cc=rms@gnu.org \
    --cc=rtm443x@googlemail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.