🚀 go-pugleaf

>>>>> "Kresten" == Kresten Krab Thorup <krab@IESD.AUC.DK> writes:

	Kresten> Recently I had the need to let the documentation for a
	Kresten> function be changed dynamically, as it depended on a
	Kresten> list, that could be changed by the user.

	Kresten> This is somewhat like the \{keymap} etc. functions that
	Kresten> may be invoked from within a documentation string, but I
	Kresten> think it would be fine if one could evaluate any
	Kresten> function, using a syntax somewhat like that.

	Kresten> As far as I can see, this is not possible in Emacs, but
	Kresten> why not?

Why not modify the documentation strings for the applicable functions
when the list gets changed?  Or periodically check the value of the
list to see if its been changed, and set the docstrings at that time?
Maybe you could even redefine (documentation) to check the list first?
If you can do that part of the problem (figure out when the docstring
needs changing), modifying a function's documentation string is not
hard at all, though it won't be automatic like a \{} syntax.  My
supercite package changes the documentation strings of a buffer's
major-mode, and it works for both read-only and read-write symbols.

Below my siggy are two functions from supercite (sc.el in 2.2 --
coming soon to a newsgroup near you).  It may not be exactly what
you're looking for, but I hope it helps a bit.

-Barry

"When in doubt, cout."

-------------------- cut here --------------------

(defun sc-snag-all-keybindings ()
  "Snag all keybindings in major-mode's current keymap."
  (let* ((curkeymap (current-local-map))
	 (symregexp ".*sc-.*\n")
	 (docstring (substitute-command-keys "\\{curkeymap}"))
	 (start 0)
	 (maxend (length docstring))
	 (spooge ""))
    (while (and (< start maxend)
		(string-match symregexp docstring start))
      (setq spooge (concat spooge (substring docstring
					     (match-beginning 0)
					     (match-end 0))))
      (setq start (match-end 0)))
    spooge))

(defun sc-spoogify-docstring ()
  "Modifies (makes into spooge) the docstring for the current major mode.
This will leach the keybinding descriptions for supercite onto the end
of the current major mode's docstring.  If major mode is preloaded,
this function will first make a copy of the list associated with the
mode, then modify this copy."
  (let* ((symfunc (symbol-function major-mode))
	 (doc-cdr (nthcdr 2 symfunc))
	 (doc-str (documentation major-mode)))
    (cond
     ;; is a docstring even provided?
     ((not (stringp doc-str)))
     ;; have we already leached on?
     ((string-match "Supercite" doc-str))
     ;; lets build the new doc string
     (t
      (let ((newdoc-str (concat doc-str "

The major mode for this buffer has been modified to include the
Supercite 2.2 package for handling attributions and citations of
original messages in email replies.  For more information on this
package, type \"\\[sc-describe]\" (see below).  The following keys are
bound to Supercite commands:

"
				(sc-snag-all-keybindings))))
	(condition-case nil
	    (setcar doc-cdr newdoc-str)
	  (error
	   ;; the major mode must be preloaded, make a copy first
	   (setq symfunc (copy-sequence (symbol-function major-mode))
		 doc-cdr (nthcdr 2 symfunc))
	   (setcar doc-cdr newdoc-str)
	   (fset major-mode symfunc)
	   )))))))