From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Documentation style Date: Fri, 15 Oct 2004 15:40:33 -0400 Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Message-ID: References: <87y8i8t03j.fsf@oak.pohoyda.family> <200410151840.i9FIeit09642@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1097869274 31474 80.91.229.6 (15 Oct 2004 19:41:14 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 15 Oct 2004 19:41:14 +0000 (UTC) Cc: alexander.pohoyda@gmx.net, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Oct 15 21:41:04 2004 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1CIXwl-0004zV-00 for ; Fri, 15 Oct 2004 21:41:04 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CIY3v-0002K8-JW for ged-emacs-devel@m.gmane.org; Fri, 15 Oct 2004 15:48:27 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CIY3n-0002Js-NZ for emacs-devel@gnu.org; Fri, 15 Oct 2004 15:48:19 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CIY3n-0002Jb-9l for emacs-devel@gnu.org; Fri, 15 Oct 2004 15:48:19 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CIY3n-0002JY-6l for emacs-devel@gnu.org; Fri, 15 Oct 2004 15:48:19 -0400 Original-Received: from [132.204.24.67] (helo=mercure.iro.umontreal.ca) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CIXwJ-00082x-Co for emacs-devel@gnu.org; Fri, 15 Oct 2004 15:40:36 -0400 Original-Received: from hidalgo.iro.umontreal.ca (hidalgo.iro.umontreal.ca [132.204.27.50]) by mercure.iro.umontreal.ca (Postfix) with ESMTP id 1124D8282A3; Fri, 15 Oct 2004 15:40:35 -0400 (EDT) Original-Received: from asado.iro.umontreal.ca (asado.iro.umontreal.ca [132.204.24.84]) by hidalgo.iro.umontreal.ca (Postfix) with ESMTP id 6E2404AC70D; Fri, 15 Oct 2004 15:40:33 -0400 (EDT) Original-Received: by asado.iro.umontreal.ca (Postfix, from userid 20848) id 368CE8CA23; Fri, 15 Oct 2004 15:40:33 -0400 (EDT) Original-To: Luc Teirlinck In-Reply-To: <200410151840.i9FIeit09642@raven.dms.auburn.edu> (Luc Teirlinck's message of "Fri, 15 Oct 2004 13:40:44 -0500 (CDT)") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/21.3.50 (gnu/linux) X-DIRO-MailScanner-Information: Please contact the ISP for more information X-DIRO-MailScanner: Found to be clean X-DIRO-MailScanner-SpamCheck: n'est pas un polluriel, SpamAssassin (score=0, requis 5) X-MailScanner-From: monnier@iro.umontreal.ca X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:28451 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:28451 > 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