[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: docstrings and elisp reference
From: |
Drew Adams |
Subject: |
RE: docstrings and elisp reference |
Date: |
Tue, 6 Jun 2017 14:21:12 -0700 (PDT) |
> > 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.
Some of the information is often the same; that's all.
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.
The doc string for a command tells a user what it
does and how a prefix arg changes the behavior.
In many cases the user need have no little or no
knowledge of Emacs Lisp.
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.
Different contexts; different purposes; not
necessarily the same readers or readers with the
same immediate goal.
- Re: docstrings and elisp reference, (continued)
- Re: docstrings and elisp reference, Richard Stallman, 2017/06/12
- Re: docstrings and elisp reference, Yuri Khan, 2017/06/10
- 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 <=
- Re: docstrings and elisp reference, Dmitry Gutov, 2017/06/06
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/07
- 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