From: John Shahid <jvshahid@gmail.com>
To: Stefan Monnier <monnier@IRO.UMontreal.CA>
Cc: 10754@debbugs.gnu.org
Subject: bug#10754: define-minor-mode and doc of derived mode
Date: Wed, 20 Jun 2018 19:33:24 +0000 [thread overview]
Message-ID: <87efh1xngb.fsf@gmail.com> (raw)
In-Reply-To: <jwvmuvscivv.fsf-monnier+emacs@gnu.org>
Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
>>> I think we can avoid it by looking for the presence of ARG in
>>> the docstring
>> I think this can work, but it doesn't feel very elegant or obvious from
>> the pov of the caller of `define-minor-mode'. What's wrong with adding
>> an extra keyword arg ?
>
> I think in the long term (asymptotically), the arg is unneeded.
> But if we add the arg, the long term will be that *all* calls will use
> the arg, so we'll never be able to get rid of it.
I'm worried about minor modes that don't even mention the argument. Not
sure if that should be a concern since they should be documenting the
ARG in the first place. I can provide examples, but the Emacs codebase
has a few of those.
>
> I'd be OK with an arg of the form :dont-add-arg-paragraph (for those
> hypothetical cases where the paragraph is undesirable) but not
> :add-arg-paragraph.
Sounds good. I will make this change and reply with a patch.
>
>>> (or by simply always adding it, and then going through
>>> the various minor modes and remove the corresponding text from their
>>> docstrings).
>> I think this change needs to be backward compatible. There could be
>> other callers that aren't packaged with Emacs.
>
> Having the same text twice in the output of `C-h f` is fairly harmless
> in my opinion. We've had similar situations where `C-h v` automatically
> adds text like "this is only for interactive use" even tho the docstring
> may already say it.
>
>
> Stefan
next prev parent reply other threads:[~2018-06-20 19:33 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-02-07 18:02 bug#10754: define-minor-mode and doc of derived mode Glenn Morris
2012-02-07 20:27 ` Glenn Morris
2018-06-07 11:20 ` John Shahid
2018-06-07 13:46 ` Drew Adams
2018-06-08 2:25 ` John Shahid
2018-06-08 21:45 ` John Shahid
2018-06-16 10:52 ` Eli Zaretskii
2018-06-16 17:23 ` Stefan Monnier
2018-06-17 15:55 ` John Shahid
2018-06-17 18:31 ` Stefan Monnier
2018-06-17 19:45 ` John Shahid
2018-06-17 21:00 ` Stefan Monnier
2018-06-17 23:19 ` John Shahid
2018-06-18 13:47 ` Stefan Monnier
2018-06-20 19:33 ` John Shahid [this message]
2018-06-20 21:55 ` Stefan Monnier
2018-06-27 21:26 ` John Shahid
2018-06-27 21:31 ` John Shahid
2018-06-29 1:02 ` Stefan Monnier
2018-06-29 13:45 ` John Shahid
2018-06-29 13:55 ` Stefan Monnier
2018-06-29 14:52 ` John Shahid
2018-06-29 15:12 ` Noam Postavsky
2018-06-29 15:48 ` John Shahid
2018-06-30 7:55 ` Eli Zaretskii
2018-06-30 20:44 ` John Shahid
2018-07-02 3:36 ` Stefan Monnier
2018-06-30 7:56 ` 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=87efh1xngb.fsf@gmail.com \
--to=jvshahid@gmail.com \
--cc=10754@debbugs.gnu.org \
--cc=monnier@IRO.UMontreal.CA \
/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).