all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
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.



  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.