[Top][All Lists]

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]