From: Drew Adams <drew.adams@oracle.com>
To: Eli Zaretskii <eliz@gnu.org>, Drew Adams <drew.adams@oracle.com>
Cc: 29373@debbugs.gnu.org
Subject: bug#29373: 24.5; doc string of `self-insert-uses-region-functions'
Date: Fri, 24 Nov 2017 09:33:42 -0800 (PST) [thread overview]
Message-ID: <ea29280d-86a7-4a9a-b6fa-f57842da342c@default> (raw)
In-Reply-To: <<83y3mv8v1r.fsf@gnu.org>>
> Sometimes it's impossible to limit a line to 70 characters without
> incurring worse problems. This is one such case.
I don't see any such "worse problems" in this case.
Without any change to the wording (which does need
to be changed), this shows no "worse problems":
Special hook to tell if `self-insert-command' will use the region.
It must be called via `run-hook-with-args-until-success' with no
arguments.
Any `post-self-insert-command' which consumes the region should
register a function on this hook so that things like
`delete-selection-mode' can refrain from consuming the region.
> > > > The doc string is close to incomprehensible.
> > >
> > > Such derogatory remarks are best kept out of bug reports.
> > > The facts are grave enough to tell we should fix this.
> >
> > Nothing derogatory intended.
>
> That sentence could simply be omitted without any effect on the
> report. May I suggest that you try to refrain from such unneeded
> remarks?
>
> > That's a summary of the problem - lack of clarity overall.
>
> "Lack of clarity" would be fine (although it, too, adds nothing).
> "Incomprehensible" is not a summary.
"Incomprehensible" was not the summary I used.
"Close to incomprehensible" is the summary I used.
I stand by that characterization, as one user
reporting a doc problem: to me, the doc string was
close to incomprehensible. You might not find it so.
It's understandable that a new doc string might not
have had the attention it deserves, and so is not
as clear as it could be.
To me, this one was not really understandable.
Perhaps you prefer the statement, "I don't
understand this doc string, and I think others
may also have trouble making sense of it."
And no, I don't think that such a statement adds
nothing, even if it is better if accompanied by
guesses about the meaning, suggestions for
improvement, or pointing out particular places
that are especially problematic for the reporter.
If a reporter has no clue what is meant and no
clue what parts are particularly unclear, the
simple report that a doc string is unclear to
that reporter can help. We can disagree about
this, of course.
But my guess is that if you agree with the
reporter after reading such an incomplete "Huh?"
report then the aim is reached. And if you
disagree with the reporter - the doc is clear
to you, even if the reporter doesn't understand
it at all - it is still good that the perceived
problem was reported, and no harm was done.
We can disagree about this too, of course.
next parent reply other threads:[~2017-11-24 17:33 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <<<d8b52361-9340-4a18-b2fd-557c78c382d7@default>
[not found] ` <<<83h8tk9chp.fsf@gnu.org>
[not found] ` <<86584c33-6e52-4cf5-8e22-bb9952b296b2@default>
[not found] ` <<83y3mv8v1r.fsf@gnu.org>
2017-11-24 17:33 ` Drew Adams [this message]
2017-11-25 23:56 ` bug#29373: 24.5; doc string of `self-insert-uses-region-functions' Noam Postavsky
[not found] <<d8b52361-9340-4a18-b2fd-557c78c382d7@default>
[not found] ` <<83h8tk9chp.fsf@gnu.org>
2017-11-24 16:43 ` Drew Adams
2017-11-24 17:07 ` Eli Zaretskii
2017-11-21 2:56 Drew Adams
2017-11-24 10:50 ` 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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ea29280d-86a7-4a9a-b6fa-f57842da342c@default \
--to=drew.adams@oracle.com \
--cc=29373@debbugs.gnu.org \
--cc=eliz@gnu.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 public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).