From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: changing the doc string using property `variable-documentation' Date: Sat, 5 Sep 2009 14:32:11 -0700 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1252186349 27870 80.91.229.12 (5 Sep 2009 21:32:29 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 5 Sep 2009 21:32:29 +0000 (UTC) To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 05 23:32:23 2009 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Mk2ru-0006Jw-Mi for ged-emacs-devel@m.gmane.org; Sat, 05 Sep 2009 23:32:22 +0200 Original-Received: from localhost ([127.0.0.1]:59977 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Mk2ru-0006Uf-5h for ged-emacs-devel@m.gmane.org; Sat, 05 Sep 2009 17:32:22 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Mk2rp-0006UM-DI for emacs-devel@gnu.org; Sat, 05 Sep 2009 17:32:17 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Mk2rk-0006Tn-Ps for emacs-devel@gnu.org; Sat, 05 Sep 2009 17:32:16 -0400 Original-Received: from [199.232.76.173] (port=44266 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Mk2rk-0006Tj-LQ for emacs-devel@gnu.org; Sat, 05 Sep 2009 17:32:12 -0400 Original-Received: from acsinet11.oracle.com ([141.146.126.233]:58021) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Mk2rk-0007qu-4Y for emacs-devel@gnu.org; Sat, 05 Sep 2009 17:32:12 -0400 Original-Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n85LX7UF030906 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 5 Sep 2009 21:33:08 GMT Original-Received: from abhmt010.oracle.com (abhmt010.oracle.com [141.146.116.19]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n85LW77I017438 for ; Sat, 5 Sep 2009 21:32:07 GMT Original-Received: from dradamslap1 (/141.144.224.66) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 05 Sep 2009 14:32:06 -0700 X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 Thread-Index: AcorJLNp8Qce8vEDRe6ARkqwrBG2mQDSskUw X-Source-IP: abhmt010.oracle.com [141.146.116.19] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090205.4AA2D8D6.02AD:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) 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: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:115059 Archived-At: Resending (with missing ' typo corrected). Is there a byte compiler bug here? What's the (logical) relation between the vacuous `defvar' and updating the doc string? (Why?) If there is byte-compiler no bug here, shouldn't this use of `defvar' be documented, as the (weird) cliche for updating a doc string at top level? Should there be something along the lines of `defadvice' for variables, to let you update a variable's doc string? What about the apparently erroneous cc-vars.el comment? -----Original Message----- From: Drew Adams Sent: Tuesday, September 01, 2009 9:53 AM You can use `defadvice' to add a bit of text to the existing doc string of an existing function. But AFAIK there is no way to use `defadvice' to replace or add to the doc string of a variable. This seems to be what's called for (for replacing). Correct me if this is not the best approach: (put 'foovar 'variable-documentation "The new doc string") However, when I put that at the top level of a library that `require''s the library that defines `foovar', it does not seem to be taken into account. `C-h v' always shows the original doc string. It doesn't matter whether I load the source file or the byte-compiled file that has this code. The following seems to work, but I don't understand why it would make any difference: (when t (put 'foovar 'variable-documentation "The new doc string")) (Actually, it was tried with (require 'xxx) instead of t.) Grepping the Emacs source files, I found a better solution, in `cc-vars.el'. It's apparently enough to add a vacuous `defvar': (defvar foovar) (put 'foovar 'variable-documentation "The new doc string") I don't understand why that would be, or how this works (or why it doesn't work without the `defvar', especially since the library with the real `defvar' was already loaded/required). So that's what I'm using now. Is this in fact the best way to accomplish this? If not, what is? I'd also be grateful for an explanation of what's going on (e.g. why the `put' doesn't work at top level without the vacuous `defvar'). Thx. -- P.S. I think this comment in cc-vars.el is wrong. It seems to work for me also in prior versions (e.g. Emacs 20). ;; C-h v will read this documentation only for versions of GNU ;; Emacs from 22.1.