Re: docstrings and elisp reference

[Eli Zaretskii <eliz@gnu.org>]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 7 Jun 2017 00:50:23 +0300
> 
> On 6/7/17 12:21 AM, Drew Adams wrote:
> >>> 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 is a difference, that's true.  But the fact that reality is
different from the ideal doesn't mean we should give up the ideal, at
least not lightly.  And we certainly should consider whether the
alternative proposal will produce a far worse situation than what we
have today.  Once again, I suggest that you take a good look at
manuals of GnuTLS and Guile, they are produced using the methodology
that you propose.  That is our future if we go that way.  Do you
really like the result?

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

You are overloading the meaning of "duplication".  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.

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

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.