Documentation style

Documentation style

[Alexander Pohoyda]

I re-read the Documentation section in the manual, but didn't
find the answer.

Is there a reason to document variables like this:

(defvar abcd nil "\
*Some variable..")

or is it *fully* equivalent to this:

(defvar abcd nil
  "Some variable..")

?


-- 
Alexander Pohoyda <alexander.pohoyda@gmx.net>
PGP Key fingerprint: 7F C9 CC 5A 75 CD 89 72  15 54 5F 62 20 23 C6 44

Re: Documentation style

[Luc Teirlinck]

Alexander Pohoyda wrote:

   I re-read the Documentation section in the manual, but didn't
   find the answer.

   Is there a reason to document variables like this:

   (defvar abcd nil "\
   *Some variable..")

   or is it *fully* equivalent to this:

   (defvar abcd nil
     "Some variable..")

The answer is at the end of `(elisp)Autoload':

    The backslash and newline immediately following the double-quote are a
    convention used only in the preloaded uncompiled Lisp files such as
    `loaddefs.el'; they tell `make-docfile' to put the documentation
    string in the `etc/DOC' file.  *Note Building Emacs::.  See also the
    commentary in `lib-src/make-docfile.c'.

Sincerely,

Luc.

Re: Documentation style

[Stefan Monnier]

>    I re-read the Documentation section in the manual, but didn't
>    find the answer.

>    Is there a reason to document variables like this:

>    (defvar abcd nil "\
>    *Some variable..")

>    or is it *fully* equivalent to this:

>    (defvar abcd nil
>      "Some variable..")

> The answer is at the end of `(elisp)Autoload':

>     The backslash and newline immediately following the double-quote are a
>     convention used only in the preloaded uncompiled Lisp files such as
>     `loaddefs.el'; they tell `make-docfile' to put the documentation
>     string in the `etc/DOC' file.  *Note Building Emacs::.  See also the
>     commentary in `lib-src/make-docfile.c'.

Yup, and it has a corresponding piece of code in lread.c such that if we
read such a string before we've dumped Emacs, the reader returns 0 instead
of returning the string (because it assumes that this is a docstring that
will be later on filled from the DOC file by Snarf-documentation).

I've always disliked this kludge.  We should probably strip make-docfile.c
of all the elisp handling and instead we should fill the DOC while dumping
Emacs (i.e. functions like `defun' and `autoload' should add the docstring
to the DOC file), so the recognition of docstrings and their replacement by
a reference to the DOC file are done at the same place and are thus known to
be correct.


        Stefan

Re: Documentation style

[Richard Stallman]

    I've always disliked this kludge.  We should probably strip make-docfile.c
    of all the elisp handling and instead we should fill the DOC while dumping
    Emacs (i.e. functions like `defun' and `autoload' should add the docstring
    to the DOC file), so the recognition of docstrings and their replacement by
    a reference to the DOC file are done at the same place and are thus known to
    be correct.

This would not make things any better for users.  I would rather see
progress on things that will provide a benefit to the users.

Meanwhile, for right now what we should focus on readying a new
release.