From: Philipp Stephani <p.stephani2@gmail.com>
To: Drew Adams <drew.adams@oracle.com>,
Nicolas Petton <nicolas@petton.fr>, Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Making DOC argument of define-minor-mode optional
Date: Wed, 28 Dec 2016 17:25:11 +0000 [thread overview]
Message-ID: <CAArVCkQba7RoWa+tB2UtNaex6=SEGMT=ZxmSedM0tyP9jXhG3Q@mail.gmail.com> (raw)
In-Reply-To: <CAArVCkQadt3LTCeUJEKMNqHok5=XNxpC_pAaGuDRipjXY+W8Kw@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 1994 bytes --]
Philipp Stephani <p.stephani2@gmail.com> schrieb am So., 27. Nov. 2016 um
22:13 Uhr:
> Drew Adams <drew.adams@oracle.com> schrieb am Mi., 23. Nov. 2016 um
> 17:35 Uhr:
>
> > >> the docstring created by define-minor-mode with nil DOC is useful
> > >> and often better than what users write.
> > >> Should DOC therefore be optional?
> > >
> > > Not sure we would like to educate Lisp programmers to stop
> > > thinking about good doc strings.
> >
> > I agree.
>
> Me too. And definers of user-facing things, such as
> defcustom and defface, do require DOC. Other definers,
> such as defconst and defvar, do not require it.
>
> On the other hand, OP raises a real issue, I think.
>
> I'd be in favor of (somehow) automatically having the
> definer-provided DOC be augmented by a link that shows
> the generic `define-minor-mode' doc, or similar.
>
> IOW:
>
> 1. Definers should need to provide a DOC string (even if
> they can fake it with "", which is not encouraged).
>
> 2. Users of the mode should have access to the generic
> information also. It should be sufficient that the
> DOC in the definition provides mode-specific information.
> It should not need to tell users general things about
> using a minor mode.
>
>
> That sounds like a good approach.
>
Do you have a good idea how to design the interface for this? I was
thinking about something like this: Create a new help type, "mode",
analogous to "variable" and "function". The documentation for the mode
would be different from the toggle command and the mode variable, which
would get a generic docstring. C-h o and C-h m would show the mode
docstring instead of the toggle command docstring. The mode docstring would
contain only a description of the mode itself, not the toggle command.
The primary downside is that many mode docstrings are written to be
applicable to the toggle command. Maybe `define-minor-mode' could grow a
:doc keyword argument for the mode docstring to preserve backward
compatibility.
[-- Attachment #2: Type: text/html, Size: 3503 bytes --]
next prev parent reply other threads:[~2016-12-28 17:25 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-23 10:04 Making DOC argument of define-minor-mode optional Philipp Stephani
2016-11-23 15:50 ` Eli Zaretskii
2016-11-23 15:59 ` Nicolas Petton
2016-11-23 16:35 ` Drew Adams
2016-11-27 21:13 ` Philipp Stephani
2016-12-28 17:25 ` Philipp Stephani [this message]
2016-12-29 0:44 ` 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='CAArVCkQba7RoWa+tB2UtNaex6=SEGMT=ZxmSedM0tyP9jXhG3Q@mail.gmail.com' \
--to=p.stephani2@gmail.com \
--cc=drew.adams@oracle.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=nicolas@petton.fr \
/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.