[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings and elisp reference
From: |
Eli Zaretskii |
Subject: |
Re: docstrings and elisp reference |
Date: |
Wed, 07 Jun 2017 08:28:25 +0300 |
> From: Dmitry Gutov <address@hidden>
> 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.
- Re: docstrings and elisp reference, (continued)
- Re: docstrings and elisp reference, Richard Stallman, 2017/06/09
- Re: docstrings and elisp reference, Joost Kremers, 2017/06/06
- Re: docstrings and elisp reference, Stefan Monnier, 2017/06/07
- Re: docstrings and elisp reference, Yuri Khan, 2017/06/07
- Re: docstrings and elisp reference, Stefan Monnier, 2017/06/07
- RE: docstrings and elisp reference, Drew Adams, 2017/06/07
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/07
- Re: docstrings and elisp reference, Dmitry Gutov, 2017/06/06
- RE: docstrings and elisp reference, Drew Adams, 2017/06/06
- Re: docstrings and elisp reference, Dmitry Gutov, 2017/06/06
- Re: docstrings and elisp reference,
Eli Zaretskii <=
- Re: docstrings and elisp reference, Dmitry Gutov, 2017/06/17
- Re: docstrings and elisp reference, Alan Mackenzie, 2017/06/17
- Re: docstrings and elisp reference, Dmitry Gutov, 2017/06/17
- Re: docstrings and elisp reference, Alan Mackenzie, 2017/06/17
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/17
- Re: docstrings and elisp reference, Richard Stallman, 2017/06/18
- Re: docstrings and elisp reference, Richard Stallman, 2017/06/17
- Re: docstrings and elisp reference, John Wiegley, 2017/06/20
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/17
- Re: docstrings and elisp reference, Stefan Monnier, 2017/06/17