RE: docstrings and elisp reference

[Drew Adams <drew.adams@oracle.com>]

> >>> 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.