all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Michael Heerdegen <michael_heerdegen@web.de>
Cc: 31311@debbugs.gnu.org
Subject: bug#31311: 27.0; doc of `pcase'
Date: Sun, 29 Apr 2018 12:43:14 -0700 (PDT)	[thread overview]
Message-ID: <e0575fb9-2402-4b33-a744-db08efd4bd1c@default> (raw)
In-Reply-To: <87a7tlluye.fsf@web.de>

> > Perhaps you can at least remove the incomprehensible and
> > seemingly unrelated text (I cited) that appears at the end
> > of the doc string, as a start.
> 
> This is not unrelated: These are the docs for additional pcase patterns
> defined elsewhere: pcase is extensible, and the pattern listing part in
> the docstring is generated dynamically.  As a result of that conception
> it may not read very fluently as a whole, but it's definitely nothing we
> want to remove.

Sorry, but that extra (dynamically generated?) text at the
end makes no sense at all to me.  I don't have a clue what
it's trying to convey.  To me it's just noise that can only
confuse, not help, users.

If there is some core meaning behind it then great.  In
that case there is a potential for it to say something.

That's not happening at all now, I think.  For the time
being, i.e., until someone can translate that core meaning
(what you really expect it to be trying to say) into
understandable text, it should be removed.  Please consider
moving it to a TODO item somewhere, if you like.  But maybe
others disagree and only I have trouble seeing what that
text is all about.

Beyond that, if it is about showing examples of defining
additional `pcase' patterns in the Emacs code then I
don't think that kind of thing belongs in a doc string -
certainly not multiple such examples.

Even in the Elisp manual, I'd expect only a simple example
of defining a `pcase' pattern, in the node itself.  If it
were thought to really be helpful then there could perhaps
also be a note to see the code of this or that function.
But I really don't expect that that should be necessary.
Do we do that anywhere else?

Either it is simple to define your own `pcase' patterns
or it is not.  If it is, then no such extra examples
should be needed.  If it's not, then can't we make it
easier to define your own patterns (change the product,
not just the doc)?

From what you are saying, it sounds to me like what users
need to make sense of `pcase' is a blog article, showing
examples etc. and building up from simple to complex.
I'd rather encourage someone to write that than for us
to try to cram such info into a doc string or manual node.
 
> We clearly have some deficiencies, but the situation IMHO really is not
> as horrible as Eli's sarcasm suggests.

FWIW, I don't see what Eli wrote as sarcasm.  I do see it
as negative, nearly despondent.  But sarcasm involves some
element of humor, irony, or satire, which I don't find there.

In any case, there are two different problems being
discussed so far in this thread: (1) the doc is bad, and
(2) it has been given insufficient love.

This bug is really about #1.  But according to Eli, #1
likely won't be fixed because of #2.  Dunno whether he
is right, but #1 is the problem to report.





  reply	other threads:[~2018-04-29 19:43 UTC|newest]

Thread overview: 61+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <<b5d5bbd5-f90c-4836-9307-7a74ad0b2320@default>
     [not found] ` <<83wowqrmp8.fsf@gnu.org>
2018-04-29 17:02   ` bug#31311: 27.0; doc of `pcase' Drew Adams
2018-04-29 17:16     ` Eli Zaretskii
2018-04-29 18:38     ` Michael Heerdegen
2018-04-29 19:43       ` Drew Adams [this message]
2018-04-29 20:00         ` Michael Heerdegen
     [not found] <<<b5d5bbd5-f90c-4836-9307-7a74ad0b2320@default>
     [not found] ` <<<83wowqrmp8.fsf@gnu.org>
     [not found]   ` <<9cd18e10-8f14-4a49-a3a4-ed9d50afe860@default>
     [not found]     ` <<83sh7erl01.fsf@gnu.org>
2018-04-29 17:26       ` Drew Adams
2018-04-29 16:03 Drew Adams
2018-04-29 16:39 ` Eli Zaretskii
2018-04-29 18:31   ` Michael Heerdegen
2018-04-29 18:45     ` Eli Zaretskii
2018-04-29 20:05       ` Michael Heerdegen
2018-04-30  2:36         ` Eli Zaretskii
2018-04-30 11:20           ` Noam Postavsky
2018-04-30 13:35             ` Thien-Thi Nguyen
2018-04-30 16:58               ` Drew Adams
2018-04-30 18:04               ` Michael Heerdegen
2018-05-01  9:41                 ` Thien-Thi Nguyen
2018-04-30 19:31               ` Eli Zaretskii
2018-05-12 11:18                 ` Thien-Thi Nguyen
2018-05-12 13:54                   ` Michael Heerdegen
2018-05-15 14:24                     ` Thien-Thi Nguyen
2018-05-15 15:16                       ` Michael Heerdegen
2018-05-16 10:43                         ` Thien-Thi Nguyen
2018-05-16 15:18                           ` Michael Heerdegen
2018-05-20 18:59                             ` Thien-Thi Nguyen
2018-05-23 13:55                               ` Drew Adams
2018-05-23 15:42                                 ` Eli Zaretskii
2018-05-23 15:28                               ` Eli Zaretskii
2018-05-23 19:16                                 ` Thien-Thi Nguyen
2018-05-24 16:23                                   ` Eli Zaretskii
2018-05-26  7:58                                     ` Thien-Thi Nguyen
2018-05-24 23:13                                   ` Noam Postavsky
2018-05-26  9:01                                     ` Thien-Thi Nguyen
2018-05-26 15:26                                       ` Drew Adams
2018-05-27  8:22                                         ` Thien-Thi Nguyen
2018-05-27  8:41                                           ` Thien-Thi Nguyen
2018-05-27 13:31                                           ` Drew Adams
2018-05-27 14:12                                           ` Noam Postavsky
2018-05-27 16:16                                           ` Eli Zaretskii
2018-05-27 16:26                                             ` Eli Zaretskii
2018-05-27 16:32                                               ` Andreas Schwab
2018-05-27 17:30                                                 ` Eli Zaretskii
2018-05-27 17:45                                                   ` Andreas Schwab
2018-05-27 17:42                                               ` Thien-Thi Nguyen
2018-05-28  7:25                                               ` Nicolas Petton
2018-05-28  7:33                                                 ` Nicolas Petton
2018-05-28  8:27                                                 ` Eli Zaretskii
2018-05-28  9:32                                                   ` Nicolas Petton
2018-05-12 13:56                   ` Noam Postavsky
2018-05-15 14:37                     ` Thien-Thi Nguyen
2019-08-25 12:56               ` Michael Heerdegen
2018-04-30 14:28             ` Eli Zaretskii
2018-04-29 22:59 ` Drew Adams
2018-04-29 23:16   ` Noam Postavsky
2018-04-29 23:28     ` Drew Adams
2018-04-30  0:29 ` Michael Heerdegen
2018-04-30  2:47   ` Drew Adams
2018-04-30  7:48     ` Thien-Thi Nguyen
2018-05-21 17:04 ` Thien-Thi Nguyen
2022-04-29 13:48 ` Lars Ingebrigtsen
2022-04-29 14:39   ` Drew Adams

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=e0575fb9-2402-4b33-a744-db08efd4bd1c@default \
    --to=drew.adams@oracle.com \
    --cc=31311@debbugs.gnu.org \
    --cc=michael_heerdegen@web.de \
    /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.