all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Eli Zaretskii <eliz@gnu.org>, Drew Adams <drew.adams@oracle.com>
Cc: 25106@debbugs.gnu.org, larsi@gnus.org
Subject: bug#25106: 24.5; easy-menu doc strings
Date: Sun, 28 Jul 2019 11:04:24 -0700 (PDT)	[thread overview]
Message-ID: <c2e5ef78-5143-4dc6-9577-943e7e48de39@default> (raw)
In-Reply-To: <<835znmks9v.fsf@gnu.org>>

> > 1. Doc string of `easy-mmode-defmap' says it defines
> >    a constant whose value has the form of the return
> >    value of `easy-mmode-define-keymap'.
> 
> No, it says that the constant's value is the _result_ of
> easy-mmode-define-keymap.

Correct.  Which implies that its form is the same.

The question raised by the report is how to know
what form the returned keymap has.

> It says nothing about the form of the keymap.

Exactly.  That's the problem reported.

It invites a reader, in effect, to go check the
doc of `easy-mmode-define-keymap'.  See if that
describes the form of the return value.

Going there, you find that there's no description
of it (beyond it being a keymap).  Your recourse
is to go to the code, even though easy-menu returns
a specific form of keymap, which its doc could
just as well specify.

If `easy-mmode-define-keymap' specified the form
of the keymap it returns then there would be no
difficulty.  It doesn't.  That's what this request
is about: help users by describing the particular
form of the keymap.

> So there's no mystery to solve here.

Mystery, no.  Suggested doc improvement, yes.

> Please always assume that your arguments were
> considered in good faith, and the decision, if
> you don't like it, was not meant to disregard
> your views in any way,

No, of course not.  No one said anything about
that.  I'm sure Lars acted in good faith - never
questioned that.

> it just disagreed with you.

Disagreement about whether the problem should be
addressed is normal - a judgment call.  People
judge things differently.  Nothing wrong with that.

It's a fact that the form of the keymap returned
isn't given in the doc string.  The enhancement
request suggests that it would help users if it
were.

I certainly understand that someone can decide
that a particular enhancement need not or should
not be made.

I replied to Lars's request to point out the doc
string(s) in question.  He looked for that and
didn't find it.

If that was the reason for closing (as he stated)
then pointing out the doc strings (as requested)
is appropriate, as is requesting that (given this
more specific information) the problem be fixed.

There could be other reasons to close the request.
I replied to the only reason given so far, saying
where the doc difficulty is.

Please consider adding the form of the returned
keymap to the doc string.  Just a request.

As for revisiting a closed report: maybe take a
look at #25195, which was also followed up on
after being closed as wont-fix.  The subsequent
discussion apparently caused Lars to change his
mind.

And no, nothing in that discussion put in question
Lars's good faith.  And yes, we're all appreciative
of the work Lars has been doing, revisiting old
bug reports.  I'm particularly grateful that many
of the problems I reported are now getting fixed.

Lars is moving quickly and carefully through many,
many bug reports, trying his best to quickly decide
their fate.  I don't think any of us has baked-in,
closed opinions - we're all open to new information
or new arguments pro & con.  This is a process.





       reply	other threads:[~2019-07-28 18:04 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <<45826813-d92b-4769-8ba1-a09c51349b3d@default>
     [not found] ` <<87r26bittq.fsf@mouse.gnus.org>
     [not found]   ` <<7acd55b6-689a-45bb-917b-0b7cff901c28@default>
     [not found]     ` <<m3mugy5vpv.fsf@gnus.org>
     [not found]       ` <<90eacb4e-822b-4af6-addb-e7d22b68310b@default>
     [not found]         ` <<835znmks9v.fsf@gnu.org>
2019-07-28 18:04           ` Drew Adams [this message]
2019-07-29 14:51             ` bug#25106: 24.5; easy-menu doc strings Noam Postavsky
2016-12-04 17:06 Drew Adams
2019-07-27 11:46 ` Lars Ingebrigtsen
2019-07-27 17:06   ` Drew Adams
2019-07-28  9:55     ` Lars Ingebrigtsen
2019-07-28 16:40       ` Drew Adams
2019-07-28 17:01         ` Eli Zaretskii

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=c2e5ef78-5143-4dc6-9577-943e7e48de39@default \
    --to=drew.adams@oracle.com \
    --cc=25106@debbugs.gnu.org \
    --cc=eliz@gnu.org \
    --cc=larsi@gnus.org \
    /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.