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: Wed, 7 Jun 2017 07:05:16 -0700 (PDT)	[thread overview]
Message-ID: <490eb522-8de7-43d5-820b-bb088ab7fa29@default> (raw)
In-Reply-To: <0d081c78-3e64-4cc3-afdd-471b49f21f24@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.
> 
> Please look up the difference between "intention" and "current situation".

There may be some examples in the "current situation"
where the doc string text and the text in the Elisp manual
are identical.  That is hardly how I would characterize
"the current situation".  Laziness and sloppiness happens.
And there might even be a few cases where having the exact
same text is not inappropriate.

But in general the "current situation" jibes well, I think,
with the "intention": doc string and manual are generally
_not_ exactly the same - their presentations, and to some
extent their content, are different.

> > Some of the information is often the same; that's all.
> 
> That's called "duplication".

INFORMATION.  Yes, much of the _information_ is duplicated.
Of course.  Almost all of the information contained in doc
strings is in the Elisp manual.

The text/presentation is different.  The contexts are
different.  The readers are often different.  A reader's
intention in consulting them is often different.

> > 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 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.
> 
> We have different manuals, with different goals.
> 
> The fact that docstrings often describe the interactive case (when it
> exists) doesn't make them necessarily targeted at the end user. Just
> exhaustive.

The question about interactive use is a one of emphasis
and audience.  Interactive use is presented _first_ in
doc strings.  The aim in presenting it is not merely to
be exhaustive.  It's about whom the different docs are
presented to and what the aims typically are in reading
them.  And yes, that involves judgment calls.

We are not (and should not be) aiming only at reducing
emacs-dev maintenance time.  We are (and should be)
aiming at the best possible help for Emacs users,
including Lisp users.

That involves trade-offs, of course.  What it does not
involve is throwing up our hands and saying "Too hard,
bothersome, and error prone.  Let's just write it once -
one size fits all - and reuse the same thing for both
Elisp manual and doc string."  (As if that were a new
idea...)

Doc/help has been extremely important to the Emacs
project since Day One.  It's part of the mantra:
self-documenting editor.

And a lot of care and time has been spent, including
by some of the most qualified and knowledgable Emacs
developers, getting it right, where "right" means
paying attention to the differences among the roles
of doc string, Emacs manual, and Elisp manual.

I'm pretty sure that those who have long held a high
priority for the quality of Emacs doc, including in
particular RMS and Eli, do not share a reductive,
JavaDoc-like view of it.  I can't speak for them, of
course.  Perhaps they will care to speak up; perhaps not.

In any case, I've given my opinion about this: using
only a JavaDoc-like approach to Emacs doc would be a
step backward, not forward.  That does not mean that
there can never be any reuse (we do that with `apropos'
functions, for example).  It means that human judgment
is called for.



  parent reply	other threads:[~2017-06-07 14:05 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
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 [this message]
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=490eb522-8de7-43d5-820b-bb088ab7fa29@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.