Re: Proposal: font lock for `describe-variable`

[Tino Calancha <tino.calancha@gmail.com>]

On Sat, 8 Oct 2016, Tianxiang Xiong wrote:

> Here's a version that fixes a few issues:
Thank you very much.

i have tested your patch and i have several comments.

I)
If you plan to fontify `describe-variable' then you should fontify
`describe-function' as well.  Before your patch, the output of
these two functions looks similar.  It would be confusing if
'd-v' uses `font-lock-doc-face' and 'd-f' do not.

II)
You dropped the button with label 'below' which appears when the
variable value is very long.  Please, add this button.
See examples below.

III)
The condition to consider a variable value long in your patch is
different.  In the example below, your patch shows a long var
value at the beginning, but without applying your patch it is shown
at the end.  I guess, you are defining 'large' as a value
composed of >= 3000 characters.  Please keep same definition
of variable being large as before your patch.

IV) Wouldn't be possible to show all the buttons with face 'button?
Even buttons inside the doc string.  Before your patch is visually
very clear where there is a button; after your patch is less
clear because all doc string shows face `font-lock-doc-face'.

IV) The message 'Global value is', sometimes get confused and shows
things like:
global value is Documentation:
or
global value is Automatically becomes buffer-local when set.
See examples below.

VI) I found one inconsistency between using `F1-v' and `F1-o'
with a Elisp variable: they might report different variable
value after your patch.
See examples below.

Personally i like how Emacs currently shows 'd-v' and 'd-f'.
They look also consistent with `describe-mode'.  I don't
see the necessity to apply the fontifications in your patch.
But this is just my opinion.  Others may think differently.


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
EXAMPLES
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Save following in a file /tmp/test.el
;;;;;;;;;;;;;;;;;;;;;  FILE BEGIN  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defvar-local test-var nil
   "Variable to test Xion patch.

When its value is long, `describe-variable' shows it at the end of
the *Help* buffer; in that case, there is one button with label
'below': pushing this button sets point to the buffer position
where the value is shown.

You should get the same documentation with `describe-symbol'.

Note that there is also a button in `describe-variable': pushing
it will show the documentation for describe-variable.  This button
has face 'button, different from the rest of the text which shows
face 'default: that help users to visualize that there is a button.")
(setq test-var '(("/tmp/"
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "a"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "b"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "c"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "d"))
 		  ((foo . 3)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "e"))
 		  ((foo . 3)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "f"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "g"))
 		  ((foo . 3)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "h"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "i"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "j"))
 		  ((foo . 2)
 		   (bar . "123")
 		   (baz . "456")
 		   (qux . "k")))))
;;;;;;;;;;;;;;;;;;;;;  FILE END  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Compare w/ and w/o your patch:
[A]
emacs -Q -l /tmp/test.el
F1-v test-var RET
;; w/ patch: value appears at the beginning; value is non-nil.
;; w/o patch: value appears at end; button below is present.

F1-o test-var RET
;; w/ patch: value is nil.
;; w/o patch: value appears at end: same as using `F1-v'
;;            button below is present.

[B]
emacs -Q
M-: (dired source-directory) RET
* /
M-: (save-excursion (mapc 'dired-maybe-insert-subdir (dired-get-marked-files))) RET
F1-v dired-subdir-alist RET
;; w/ patch: value appears at the beginning
;; w/o patch: value appears at the end; button 'below' OK.

;;; Add more subdirs
* /
M-: (save-excursion (mapc 'dired-maybe-insert-subdir (dired-get-marked-files))) RET
F1-v dired-subdir-alist RET
;; w/ patch: value appears at the end; no button 'below'.
;; w/o patch: value appears at the end; button 'below' OK.