From: Drew Adams <drew.adams@oracle.com>
To: Dmitry Gutov <dgutov@yandex.ru>,
Stephen Leake <stephen_leake@stephe-leake.org>,
emacs-devel <emacs-devel@gnu.org>
Subject: RE: docstrings and elisp reference
Date: Tue, 6 Jun 2017 14:21:12 -0700 (PDT) [thread overview]
Message-ID: <3d5a1ca0-645f-421f-8044-f344c586705d@default> (raw)
In-Reply-To: <13fd66c8-b22b-5b87-bd8c-34dbe0c7ec38@yandex.ru>
> > they should not duplicate each other.
>
> Then you have something else in mind than the current
> situation with documentation in Emacs.
No, you do, if you think the intention now is that
they duplicate each other. It never has been.
Some of the information is often the same; that's all.
The presentation and context of use are different.
The level of detail is often different. (Sometimes
there is more detail in the manual; sometimes there
is more in a doc string.)
In particular, doc strings are written as user help.
The interactive use, if any, is typically described
first, and from the point of an interactive user.
Not so, the Elisp manual.
The doc string for a command tells a user what it
does and how a prefix arg changes the behavior.
In many cases the user need have no little or no
knowledge of Emacs Lisp.
The Elisp doc for a command tells a Lisp programmer
what the function and its parameters are, and
describes their behavior. It might or might not
mention that one of the parameters corresponds to
the prefix arg when called interactively.
Different contexts; different purposes; not
necessarily the same readers or readers with the
same immediate goal.
next prev parent reply other threads:[~2017-06-06 21:21 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-05 21:26 docstrings and elisp reference Jean-Christophe Helary
2017-06-06 0:09 ` Tino Calancha
2017-06-06 5:10 ` Jean-Christophe Helary
2017-06-06 15:03 ` Eli Zaretskii
2017-06-06 20:25 ` Stephen Leake
2017-06-06 20:36 ` Drew Adams
2017-06-08 2:29 ` Etienne Prud’homme
2017-06-08 3:48 ` Jean-Christophe Helary
2017-06-08 5:39 ` Chad Brown
2017-06-08 8:12 ` Jean-Christophe Helary
2017-06-08 15:11 ` Eli Zaretskii
2017-06-08 15:42 ` Jean-Christophe Helary
2017-06-09 0:25 ` Chad Brown
2017-06-08 18:29 ` Etienne Prud’homme
2017-06-09 4:10 ` Richard Stallman
2017-06-08 15:18 ` Eli Zaretskii
2017-06-08 18:10 ` Etienne Prud’homme
2017-06-08 19:14 ` Eli Zaretskii
2017-06-08 20:07 ` Drew Adams
2017-06-08 20:22 ` Etienne Prud’homme
2017-06-08 22:44 ` Jean-Christophe Helary
2017-06-09 4:10 ` Richard Stallman
2017-06-09 5:20 ` Etienne Prud’homme
2017-06-09 7:08 ` Eli Zaretskii
2017-06-09 8:27 ` Yuri Khan
2017-06-09 9:38 ` Eli Zaretskii
2017-06-09 12:21 ` Eli Zaretskii
2017-06-09 12:32 ` Yuri Khan
2017-06-09 13:46 ` Eli Zaretskii
2017-06-09 19:24 ` Etienne Prud’homme
2017-06-10 1:06 ` Jean-Christophe Helary
2017-06-10 11:36 ` Nikolay Kudryavtsev
2017-06-10 14:26 ` Drew Adams
2017-06-10 3:19 ` Richard Stallman
2017-06-10 7:31 ` Eli Zaretskii
2017-06-11 2:43 ` Richard Stallman
2017-06-11 2:44 ` Richard Stallman
2017-06-11 15:18 ` Stefan Monnier
2017-06-12 2:52 ` Richard Stallman
2017-06-12 3:27 ` Stefan Monnier
2017-06-13 3:25 ` Richard Stallman
2017-06-10 8:22 ` Yuri Khan
2017-06-10 3:19 ` Richard Stallman
2017-06-06 20:45 ` Joost Kremers
2017-06-07 13:03 ` Stefan Monnier
2017-06-07 13:23 ` Yuri Khan
2017-06-07 13:31 ` Stefan Monnier
2017-06-07 14:18 ` Drew Adams
2017-06-07 15:43 ` Eli Zaretskii
2017-06-06 20:47 ` Dmitry Gutov
2017-06-06 21:21 ` Drew Adams [this message]
2017-06-06 21:50 ` Dmitry Gutov
2017-06-07 5:28 ` Eli Zaretskii
2017-06-17 12:46 ` Dmitry Gutov
2017-06-17 13:04 ` Alan Mackenzie
2017-06-17 13:55 ` Dmitry Gutov
2017-06-17 20:14 ` Alan Mackenzie
2017-06-18 2:32 ` Eli Zaretskii
2017-06-18 19:52 ` Richard Stallman
2017-06-17 22:13 ` Richard Stallman
2017-06-20 18:05 ` John Wiegley
2017-06-17 14:10 ` Eli Zaretskii
2017-06-17 15:13 ` Stefan Monnier
2017-06-17 18:59 ` Paul Eggert
2017-06-17 14:52 ` Drew Adams
2017-06-19 18:31 ` Thien-Thi Nguyen
2017-06-07 14:05 ` Drew Adams
2017-06-07 14:27 ` Drew Adams
2017-06-08 1:27 ` Richard Stallman
2017-06-06 22:42 ` Richard Stallman
2017-06-06 22:49 ` Dmitry Gutov
2017-06-07 5:20 ` 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=3d5a1ca0-645f-421f-8044-f344c586705d@default \
--to=drew.adams@oracle.com \
--cc=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
--cc=stephen_leake@stephe-leake.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.