all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Documentation style
@ 2004-10-15 16:30 Alexander Pohoyda
  2004-10-15 18:40 ` Luc Teirlinck
  0 siblings, 1 reply; 4+ messages in thread
From: Alexander Pohoyda @ 2004-10-15 16:30 UTC (permalink / raw)


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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Documentation style
  2004-10-15 16:30 Documentation style Alexander Pohoyda
@ 2004-10-15 18:40 ` Luc Teirlinck
  2004-10-15 19:40   ` Stefan Monnier
  0 siblings, 1 reply; 4+ messages in thread
From: Luc Teirlinck @ 2004-10-15 18:40 UTC (permalink / raw)
  Cc: emacs-devel

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.

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Documentation style
  2004-10-15 18:40 ` Luc Teirlinck
@ 2004-10-15 19:40   ` Stefan Monnier
  2004-10-16 13:52     ` Richard Stallman
  0 siblings, 1 reply; 4+ messages in thread
From: Stefan Monnier @ 2004-10-15 19:40 UTC (permalink / raw)
  Cc: alexander.pohoyda, emacs-devel

>    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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Documentation style
  2004-10-15 19:40   ` Stefan Monnier
@ 2004-10-16 13:52     ` Richard Stallman
  0 siblings, 0 replies; 4+ messages in thread
From: Richard Stallman @ 2004-10-16 13:52 UTC (permalink / raw)
  Cc: teirllm, alexander.pohoyda, emacs-devel

    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.

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2004-10-16 13:52 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-10-15 16:30 Documentation style Alexander Pohoyda
2004-10-15 18:40 ` Luc Teirlinck
2004-10-15 19:40   ` Stefan Monnier
2004-10-16 13:52     ` Richard Stallman

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.