RE: docstrings and elisp reference

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

> > The original proposal was for a literal copying of the same  
> > text.  Drew was talking about duplicating the information,
> > but expressed in a different, sometimes very different, form.
> 
> And my problem is that it's very often expressed in a very
> similar form, if not copied verbatim.

What is your problem with such similarity?  That it is only
sometimes similar and not always identical?  That it is at
all similar and not totally different?

Sometimes there is no need for the presentation to be very
different; sometimes a difference makes sense.

And nothing says that every existing doc string is perfect.
Those that are apparently problematic to you, because
similar, might well be candidates for improvement.  Their
being "very similar" might be wholly appropriate, or it
might just represent inattention or laziness.

You seem to be missing the point that manual and doc string
can have different uses and purposes.  You seem to think
that when they differ that's a waste, and when they are the
same that's a waste because the text could have been reused
automatically.

Look not at the similarity or difference of this or that
function description.  Think about the difference in how
the two can be used.  It is _that_ difference that informs
possible differences or similarities of text.

A written news article is not a video clip.  Both might
tell the same story, in part or in whole, but they might
well tell it differently.  Same or similar message; but
often different delivery/presentation.

> > This doesn't really resolve the issue pointed out by Drew.
> > And that is only one of the issues, there are others, also
> > valid ones.
> 
> Drew said docstrings are mostly for the interactive case.

No.  I never said any such thing.  You are either
misreading or misrepresenting.

I said:

  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.

That says nothing about doc strings being "mostly for
the interactive case."  It says that a doc string about
a _command_ presents the command _first_ in its use as
a command, that is, interactively.

> That's wildly inaccurate:

It's wildly inaccurate for you to say that "Drew said
docstrings are mostly for the interactive case."

> as an Elisp programmer, I almost always look at the
> docstrings and comments, but very rarely at the manuals.
> Many others do the same.

We all look at doc strings.  And many of us look at
comments - and the code that is commented.  Doc strings
are typically the most immediate help for users - and
that includes Lisp programmers.

Doc strings are not only, or even primarily, "for the
interactive case".  Doc strings are not manuals, and
manuals are not doc strings - that's all.  They have
purposes that can be different but can overlap.

Doc strings are user help, including but not limited
to help for non-Lisp users.  Interactive use of a
command is described first in a doc string because the
main purpose of a command is to be used interactively.

Hard to believe this is not obvious to us all, by now.
Video is not newsprint.  A song is not a painting.
A garden is not an essay.

But perhaps it is not obvious to you because, as you
say, you "very rarely" consult the manuals?  If doc
strings and comments suffice for you, then why worry
about this question at all?

Is it just because _you_ don't want to be bothered
maintaining the manual?  If so, and if you feel that
strongly, then don't bother.  Someone else will do
it - or it won't get done.  Either way, you need not
get bothered by it, if that's your problem.

> my problem is that it's very often expressed in
> a very similar form, if not copied verbatim.

Don't worry.

Emacs has always put importance on its manuals, as
well as its doc strings.  I hope it will long
continue to do so, whoever participates in developing
and maintaining it.

But sure, there have always been those participants
who are more, and others who are less, concerned about
doc/help, including comments, doc strings, and manuals.
Nothing says that each contributor needs to be equally
interested in every possible way of contributing.

What's wrong is to mistake one's own interests, which
are typically limited (parochial), for the broader
interests of Emacs as a whole.  Just because you might
rarely read the manuals, that's not a reason for Emacs
to drop development of manuals or reduce their quality.