Re: Documentation style

[Stefan Monnier <monnier@iro.umontreal.ca>]

>    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