* changing the doc string using property `variable-documentation'
@ 2009-09-01 16:53 Drew Adams
2009-09-02 2:58 ` Stephen J. Turnbull
0 siblings, 1 reply; 4+ messages in thread
From: Drew Adams @ 2009-09-01 16:53 UTC (permalink / raw
To: emacs-devel
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* changing the doc string using property `variable-documentation'
2009-09-01 16:53 Drew Adams
@ 2009-09-02 2:58 ` Stephen J. Turnbull
2009-09-02 3:24 ` Drew Adams
0 siblings, 1 reply; 4+ messages in thread
From: Stephen J. Turnbull @ 2009-09-02 2:58 UTC (permalink / raw
To: Drew Adams; +Cc: emacs-devel
Drew Adams writes:
> (put foovar 'variable-documentation "The new doc string")
Should that be 'foovar? `put' is a function.
^ permalink raw reply [flat|nested] 4+ messages in thread
* RE: changing the doc string using property `variable-documentation'
2009-09-02 2:58 ` Stephen J. Turnbull
@ 2009-09-02 3:24 ` Drew Adams
0 siblings, 0 replies; 4+ messages in thread
From: Drew Adams @ 2009-09-02 3:24 UTC (permalink / raw
To: 'Stephen J. Turnbull'; +Cc: emacs-devel
> > (put foovar 'variable-documentation "The new doc string")
>
> Should that be 'foovar? `put' is a function.
Yes, sorry; that's what I meant. Thx.
^ permalink raw reply [flat|nested] 4+ messages in thread
* RE: changing the doc string using property `variable-documentation'
@ 2009-09-05 21:32 Drew Adams
0 siblings, 0 replies; 4+ messages in thread
From: Drew Adams @ 2009-09-05 21:32 UTC (permalink / raw
To: emacs-devel
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2009-09-05 21:32 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2009-09-05 21:32 changing the doc string using property `variable-documentation' Drew Adams
-- strict thread matches above, loose matches on Subject: below --
2009-09-01 16:53 Drew Adams
2009-09-02 2:58 ` Stephen J. Turnbull
2009-09-02 3:24 ` Drew Adams
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.