This page describes package Lisp:xray.el, by ViniciusJoseLatorre.
Sometimes you need to see the internal structures to understand what is going on. This package provides a way to display internal Emacs object structures in a temporary buffer.
For good performance, be sure to byte-compile Lisp:xray.el, e.g.
M-x byte-compile-file <give the path to xray.el when prompted>
This will generate xray.elc, which will be loaded instead of xray.el.
Lisp:xray.el was tested with GNU Emacs 21.3.50.1.
I don’t know if still is compatible with XEmacs.
To use xray, insert in your ~/.emacs:
(require 'xray)
And type, for example:
M-x xray-symbol RET describe-function RET
Or:
M-: (xray-symbol 'describe-function) RET
Or:
M-x global-set-key RET C-c x xray-symbol RET C-c x describe-function RET
The following buffer (*Symbol X-Ray*) is shown:
SYMBOL
describe-function
apropos : *Documentation* *Apropos* *Info*
key bindings : C-h f C-h d menu-bar help-menu describe describe-function
file : help
function cell : *Interactive-Compiled-Lisp-Function*
value cell : void
property list cell:
(event-symbol-element-mask (describe-function 0)
event-symbol-elements (describe-function)
modifier-cache ((0 . describe-function)))The entries on apropos, key bindings, file and function cell are links to other help buffers. The key bindings (C-h f, C-h d, etc.) points to a key description (if you click on C-h f, it’s the same as typing C-h k C-h f), the file (help) points to the position on file help.el where describe-function is defined, and the function cell points to a function description (if you click, it’s the same as typing C-h f describe-function). So, if you click on any link, you get more related information.
As in a help buffer, when you follow the links, it’ll appear at end of buffer a [back] button. You can go back by clicking with mouse-2 the [back] button or by typing C-c C-b on xray (or help) buffer.
The following objects may be shown:
‘xray-on-click’) ‘xray-on-mode-line-click’) ‘xray-click/key’) ‘xray-symbol’) ‘xray-position’) ‘xray-buffer’) ‘xray-window’) ‘xray-frame’) ‘xray-marker’) ‘xray-overlay’) ‘xray-screen’) ‘xray-faces’) ‘xray-hooks’) ‘xray-features’) As a suggestion for key bindings:
(global-set-key [f1] 'xray-click/key) (define-key help-map [?\C-m] 'xray-click/key) ; RET (define-key help-map [down-mouse-1] 'xray-on-click) (define-key help-map [mode-line down-mouse-1] 'xray-on-mode-line-click)
Maybe the following key bindings are useful:
(define-key help-map "o" 'edit-options) ; in `options.el' (define-key help-map "u" 'manual-entry) ; in `man.el' (define-key help-map "\C-l" 'locate-library) (define-key help-map "\C-a" 'apropos) (define-key help-map "\M-a" 'apropos-documentation) (define-key help-map "\M-\C-a" 'tags-apropos)
There are three function set for interfacing:
KIND MAIN INTERFACE HELP INTERFACE EHELP INTERFACE (`xray.el') (`help.el') (`ehelp.el')
Symbol `xray-symbol' `xray-help-symbol' `xray-ehelp-symbol' Position `xray-position' `xray-help-position' `xray-ehelp-position' Buffer `xray-buffer' `xray-help-buffer' `xray-ehelp-buffer' Window `xray-window' `xray-help-window' `xray-ehelp-window' Frame `xray-frame' `xray-help-frame' `xray-ehelp-frame' Marker `xray-marker' `xray-help-marker' `xray-ehelp-marker' Overlay `xray-overlay' `xray-help-overlay' `xray-ehelp-overlay' Screen `xray-screen' `xray-help-screen' `xray-ehelp-screen' Faces `xray-faces' `xray-help-faces' `xray-ehelp-faces' Hooks `xray-hooks' `xray-help-hooks' `xray-ehelp-hooks' Features `xray-features' `xray-help-features' `xray-ehelp-features'
The MAIN INTERFACE uses ‘xray-electric-p’ (see Options) to decide if it invokes HELP INTERFACE (when it’s nil) or EHELP INTERFACE (when it’s non-nil).
Below it’s shown a brief description of xray options, please, see the options declaration in the code for a long documentation.
‘xray-property-alist’ ‘xray-property-recursive-list’ ‘xray-maximum-depth’ ‘xray-value-threshold’ ‘xray-buffer-name’ ‘xray-apropos-do-all’ ‘xray-info-level’ ‘xray-apropos-format’ ‘apropos’.‘xray-electric-p’ To set the above options you may:
a. insert the code in your ~/.emacs, like:
(setq xray-property-alist '((some-prop . display-some-prop)))
This method preserves your default settings when you enter a new Emacs session.
b. or use ‘set-variable’ in your Emacs session, like:
M-x set-variable RET xray-property-alist RET '((some-prop . display-some-prop)) RET
This method preserves your settings only during the current Emacs session.
c. or use customization, for example:
Help option,Customize,Browse Customization Groups,Development group,Internal group,Xray groupxray options.This way, you may choose if the settings are kept or not when you leave out the current Emacs session.
d. or see the option value:
C-h v xray-property-alist RET
and click the customize hypertext button.
This way, you may choose if the settings are kept or not when you leave out the current Emacs session.
e. or invoke:
M-x xray-customize RET
and then customize xray options.
This way, you may choose if the settings are kept or not when you leave out the current Emacs session.
Thanks to Juanma Barranquero <lektu@uol.com.br> for ehelp.el suggestion and for ‘line-number-display-limit’ meaning in Emacs 21.
Thanks to DrewAdams for key bindings suggestions and for sending Lisp:help+.el package which inspired ‘xray-click/key’, ‘xray-display-click/key’, ‘xray-on-click’ and ‘xray-on-mode-line-click’ functions.
Thanks to Arnaldo Mandel <am@ime.usp.br> for documentation corrections.