1 ;;; docref.el --- Simple cross references for Elisp documentation strings
3 ;; Copyright (C) 1994 Free Software Foundation, Inc.
5 ;; Author: Vadim Geshel <vadik@unas.cs.kiev.ua>
6 ;; Created: 12 Jul 1994
7 ;; Keywords: docs, help, lisp
8 ;; original name was cross-ref.el.
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software; you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 2, or (at your option)
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs; see the file COPYING. If not, write to the
24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
25 ;; Boston, MA 02111-1307, USA.
29 ;; This package allows you to use a simple form of cross references in
30 ;; your Emacs Lisp documentation strings. Cross-references look like
31 ;; \\(type@[label@]data), where type defines a method for retrieving
32 ;; reference information, data is used by a method routine as an argument,
33 ;; and label "represents" the reference in text. If label is absent, data
36 ;; Special reference labeled `back', when present, can be used to return
37 ;; to the previous contents of help buffer.
39 ;; Cross-referencing currently is intended for use in doc strings only
40 ;; and works only in temporary buffers (created by `with-output-to-temp-buffer').
41 ;; List of temp buffers in which cross-referencing is to be active is specified
42 ;; by variable DOCREF-BUFFERS-LIST, which contains only "*Help*" by default.
44 ;; Documentation strings for this package's functions and variables can serve
45 ;; as examples of usage.
49 ;; See source. The main customization variable is `docref-methods-alist'.
50 ;; It consists of (type . function) pairs, where type is a string which
51 ;; corresponds to type in cross-references and function is called with
52 ;; one argument - reference `data' - when a reference is activated.
56 ;; Place this file somewhere in your load-path, byte-compiled it, and add
57 ;; (require 'cross-ref)
62 ;; User customizable variables
64 "Simple cross references for Elisp documentation strings."
70 (defcustom docref-highlight-p t
71 "*If non-nil, \\(f@docref-subst) highlights cross-references.
72 Under window system it highlights them with face defined by
73 \\(v@docref-highlight-face), on character terminal highlighted references
74 look like cross-references in info mode."
78 (defcustom docref-highlight-face
'highlight
79 "*Face used to highlight cross-references (used by \\(f@docref-subst))"
83 (defcustom docref-methods-alist
84 '(("f" . docref-describe-function
) ; reference to a function documentation
85 ("v" . docref-describe-variable
) ; reference to a variable documentation
86 ("F" . docref-read-file
) ; reference to a file contents
87 ("s" . docref-use-string
) ; reference to a string
88 ("V" . docref-use-variable-value
) ; reference to variable value
89 ("0" . beep
)) ; just highlighted text
90 "Alist which maps cross-reference ``types'' to retrieval functions.
92 The car of each element is a string that serves as `type' in cross-references.
93 \(See \\(f@docref-subst)). The cdr is a function of one argument,
94 to be called to find this reference."
95 :type
'(repeat (cons string function
))
98 (defcustom docref-back-label
"\nback"
99 "Label to use by \\(f@docref-subst) for the go-back reference."
103 (defvar docref-back-reference nil
104 "If non-nil, this is a go-back reference to add to the current buffer.
105 The value specifies how to go back. It should be suitable for use
106 as the second argument to \\(f@docref-insert-label).
107 \\(f@docref-subst) uses this to set up the go-back reference.")
109 (defvar docref-last-active-buffer
)
112 (defun docref-setup ()
113 "Process docref cross-references in the current buffer.
114 See also \\(f@docref-subst)."
116 (docref-subst (current-buffer))
119 (defvar docref-mode-map nil
)
121 (let ((map (make-sparse-keymap)))
122 (define-key map
[mouse-2
] 'docref-follow-mouse
)
123 (define-key map
"\C-c\C-b" 'docref-go-back
)
124 (define-key map
"\C-c\C-c" 'docref-follow
)
125 (setq docref-mode-map map
)))
127 (defun docref-mode ()
128 "Major mode for help buffers that contain cross references.
129 To follow a reference, move to it and type \\[docref-follow], or use
130 \\[docref-follow-mouse]. The command \\[docref-go-back] can used to go
131 back to where you came from."
133 (kill-all-local-variables)
134 (setq major-mode
'docref-mode
)
135 (setq mode-name
"Docref")
136 (use-local-map docref-mode-map
)
137 (run-hooks 'docref-mode
))
139 (defun docref-subst (buf)
140 "Parse documentation cross-references in buffer BUF.
142 Find cross-reference information in a buffer and
143 highlight them with face defined by \\(v@docref-highlight-face).
145 Cross-reference has the following format: \\ (TYPE[@LABEL]@DATA), where
146 TYPE defines method used to retrieve xref data (like reading from file or
147 calling \\(f@describe-function)), DATA is an argument to this method
148 \(like file name or function name), and LABEL is displayed in text using
149 \\(v@docref-highlight-face).
151 The special reference `back' can be used to return back.
152 The variable \\(v@docref-back-label) specifies the label to use for that.
154 See \\(v@docref-methods-alist) for currently defined methods."
158 (goto-char (point-min))
159 ;; The docref-seen property indicates that we have processed this
160 ;; buffer's contents already, so don't do it again.
161 (if (not (get-text-property (point-min) 'docref-seen
))
162 (let ((old-modified (buffer-modified-p)))
163 (while (re-search-forward "[\\](\\([^\)\@]+\\)\\(@[^\)\@]+\\)?@\\([^\)]*\\))"
165 (let* ((start (match-beginning 0))
166 (type (buffer-substring (match-beginning 1) (match-end 1)))
167 (data (buffer-substring (match-beginning 3) (match-end 3)))
169 (if (match-beginning 2)
170 (buffer-substring (+ (match-beginning 2) 1) (match-end 2))
173 (docref-insert-label label
(cons type data
))))
175 ;; Make a back-reference in this buffer, if desired.
176 ;; (This is true if called from docref-follow.)
177 (if docref-back-reference
179 (goto-char (point-max))
180 (put-text-property (point-min) (1+ (point-min))
181 'docref-back-position
(point))
182 (docref-insert-label docref-back-label docref-back-reference
)))
183 (put-text-property (point-min) (1+ (point-min)) 'docref-seen t
)
184 (set-buffer-modified-p old-modified
)))))
186 (defun docref-insert-label (string ref
)
187 (let ((label (concat string
))
189 ;; decorate the label
190 (let ((leading-space-end (save-match-data
191 (if (string-match "^\\([ \t\n]+\\)" label
)
194 (trailing-space-start (save-match-data
195 (if (string-match "\\([ \t\n]+\\)$" label
)
198 (if docref-highlight-p
199 (if (not window-system
)
201 (concat (substring label
0 leading-space-end
)
203 (substring label leading-space-end trailing-space-start
)
205 (substring label trailing-space-start
)))
207 (put-text-property leading-space-end
209 'face docref-highlight-face label
)))
210 (put-text-property 0 (length label
) 'docref ref label
)
213 (defun docref-follow-mouse (click)
214 "Follow the cross-reference that you click on."
217 (let* ((start (event-start click
))
219 (pos (car (cdr start
)))
220 (docref-last-active-buffer (current-buffer)))
221 (set-buffer (window-buffer window
))
222 (docref-follow pos
))))
224 (defun docref-go-back ()
225 "Go back to the previous contents of help buffer."
227 (let ((pos (get-text-property (point-min) 'docref-back-position
)))
230 (error "No go-back reference"))))
232 (defun docref-follow (&optional pos
)
233 "Follow cross-reference at point.
234 For the cross-reference format, see \\(f@docref-subst).
235 The special reference named `back' can be used to return back"
237 (or pos
(setq pos
(point)))
238 (let ((docref-data (get-text-property pos
'docref
)))
240 ;; There is a reference at point. Follow it.
241 (let* ((type (car docref-data
))
242 (name (cdr docref-data
))
243 (method (assoc type docref-methods-alist
))
244 (cur-contents (buffer-string))
246 (docref-back-reference (cons "s" cur-contents
))
249 (error "Unknown cross-reference type: %s" type
))
252 (funcall (cdr method
) name
)
256 ;; (cdr method) got an error.
257 ;; Put back the text that we had.
259 (insert cur-contents
)
261 (set-buffer-modified-p nil
))))))
263 ;; Builtin methods for accessing a reference.
265 (defun docref-describe-function (data)
267 (if (boundp 'docref-last-active-buffer
)
268 (set-buffer docref-last-active-buffer
))
269 (describe-function (intern data
))))
271 (defun docref-describe-variable (data)
273 (if (boundp 'docref-last-active-buffer
)
274 (set-buffer docref-last-active-buffer
))
275 (describe-variable (intern data
))))
277 (defun docref-read-file (data)
278 (with-output-to-temp-buffer (buffer-name)
280 (insert-file-contents (expand-file-name data
))))
282 (defun docref-use-string (data)
283 (with-output-to-temp-buffer (buffer-name)
287 (defun docref-use-variable-value (data)
288 (let ((sym (intern data
)))
289 (with-output-to-temp-buffer (buffer-name)
291 (princ (symbol-value sym
)))))
295 ;;; docref.el ends here