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: changing the doc string using property `variable-documentation' Date: Tue, 1 Sep 2009 09:53:16 -0700 Message-ID: <61F7D8EAE62B4D3F9FA423635C3D9821@us.oracle.com> 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 1251824112 15703 80.91.229.12 (1 Sep 2009 16:55:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 1 Sep 2009 16:55:12 +0000 (UTC) To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Sep 01 18:55:05 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 1MiWdL-0000Hw-NO for ged-emacs-devel@m.gmane.org; Tue, 01 Sep 2009 18:55:04 +0200 Original-Received: from localhost ([127.0.0.1]:57770 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MiWdL-0005oI-9d for ged-emacs-devel@m.gmane.org; Tue, 01 Sep 2009 12:55:03 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MiWdF-0005mz-G8 for emacs-devel@gnu.org; Tue, 01 Sep 2009 12:54:57 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MiWdA-0005jV-8k for emacs-devel@gnu.org; Tue, 01 Sep 2009 12:54:56 -0400 Original-Received: from [199.232.76.173] (port=35593 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MiWd9-0005jQ-VY for emacs-devel@gnu.org; Tue, 01 Sep 2009 12:54:51 -0400 Original-Received: from rcsinet11.oracle.com ([148.87.113.123]:63672 helo=rgminet11.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MiWd9-00014D-GS for emacs-devel@gnu.org; Tue, 01 Sep 2009 12:54:51 -0400 Original-Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n81GrakK023404 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 1 Sep 2009 16:53:38 GMT Original-Received: from abhmt008.oracle.com (abhmt008.oracle.com [141.146.116.17]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n81Gr5wt031805 for ; Tue, 1 Sep 2009 16:53:06 GMT Original-Received: from dradamslap1 (/141.144.170.14) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 01 Sep 2009 09:53:04 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcorJLNp8Qce8vEDRe6ARkqwrBG2mQ== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt008.oracle.com [141.146.116.17] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4A9D5171.0158: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:114950 Archived-At: 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.