Mercurial > emacs
view lisp/docref.el @ 22241:0a93e911af6b
(byte-boolean-vars): Add print-escape-nonascii.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 25 May 1998 20:31:58 +0000 |
parents | ac1673121774 |
children |
line wrap: on
line source
;;; docref.el --- Simple cross references for Elisp documentation strings ;; Copyright (C) 1994 Free Software Foundation, Inc. ;; Author: Vadim Geshel <vadik@unas.cs.kiev.ua> ;; Created: 12 Jul 1994 ;; Keywords: docs, help, lisp ;; original name was cross-ref.el. ;; This file is part of GNU Emacs. ;; GNU Emacs is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation; either version 2, or (at your option) ;; any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, ;; Boston, MA 02111-1307, USA. ;;; Commentary: ;; This package allows you to use a simple form of cross references in ;; your Emacs Lisp documentation strings. Cross-references look like ;; \\(type@[label@]data), where type defines a method for retrieving ;; reference information, data is used by a method routine as an argument, ;; and label "represents" the reference in text. If label is absent, data ;; is used instead. ;; ;; Special reference labeled `back', when present, can be used to return ;; to the previous contents of help buffer. ;; ;; Cross-referencing currently is intended for use in doc strings only ;; and works only in temporary buffers (created by `with-output-to-temp-buffer'). ;; List of temp buffers in which cross-referencing is to be active is specified ;; by variable DOCREF-BUFFERS-LIST, which contains only "*Help*" by default. ;; ;; Documentation strings for this package's functions and variables can serve ;; as examples of usage. ;; ;;; Customization: ;; ;; See source. The main customization variable is `docref-methods-alist'. ;; It consists of (type . function) pairs, where type is a string which ;; corresponds to type in cross-references and function is called with ;; one argument - reference `data' - when a reference is activated. ;; ;;; Installation: ;; ;; Place this file somewhere in your load-path, byte-compiled it, and add ;; (require 'cross-ref) ;; to your .emacs. ;;; Code: ;; User customizable variables (defgroup docref nil "Simple cross references for Elisp documentation strings." :prefix "docref-" :group 'help :group 'lisp :group 'docs) (defcustom docref-highlight-p t "*If non-nil, \\(f@docref-subst) highlights cross-references. Under window system it highlights them with face defined by \\(v@docref-highlight-face), on character terminal highlighted references look like cross-references in info mode." :type 'boolean :group 'docref) (defcustom docref-highlight-face 'highlight "*Face used to highlight cross-references (used by \\(f@docref-subst))" :type 'face :group 'docref) (defcustom docref-methods-alist '(("f" . docref-describe-function) ; reference to a function documentation ("v" . docref-describe-variable) ; reference to a variable documentation ("F" . docref-read-file) ; reference to a file contents ("s" . docref-use-string) ; reference to a string ("V" . docref-use-variable-value) ; reference to variable value ("0" . beep)) ; just highlighted text "Alist which maps cross-reference ``types'' to retrieval functions. The car of each element is a string that serves as `type' in cross-references. \(See \\(f@docref-subst)). The cdr is a function of one argument, to be called to find this reference." :type '(repeat (cons string function)) :group 'docref) (defcustom docref-back-label "\nback" "Label to use by \\(f@docref-subst) for the go-back reference." :type 'string :group 'docref) (defvar docref-back-reference nil "If non-nil, this is a go-back reference to add to the current buffer. The value specifies how to go back. It should be suitable for use as the second argument to \\(f@docref-insert-label). \\(f@docref-subst) uses this to set up the go-back reference.") (defvar docref-last-active-buffer) ;;;###autoload (defun docref-setup () "Process docref cross-references in the current buffer. See also \\(f@docref-subst)." (interactive) (docref-subst (current-buffer)) (docref-mode)) (defvar docref-mode-map nil) (or docref-mode-map (let ((map (make-sparse-keymap))) (define-key map [mouse-2] 'docref-follow-mouse) (define-key map "\C-c\C-b" 'docref-go-back) (define-key map "\C-c\C-c" 'docref-follow) (setq docref-mode-map map))) (defun docref-mode () "Major mode for help buffers that contain cross references. To follow a reference, move to it and type \\[docref-follow], or use \\[docref-follow-mouse]. The command \\[docref-go-back] can used to go back to where you came from." (interactive) (kill-all-local-variables) (setq major-mode 'docref-mode) (setq mode-name "Docref") (use-local-map docref-mode-map) (run-hooks 'docref-mode)) (defun docref-subst (buf) "Parse documentation cross-references in buffer BUF. Find cross-reference information in a buffer and highlight them with face defined by \\(v@docref-highlight-face). Cross-reference has the following format: \\ (TYPE[@LABEL]@DATA), where TYPE defines method used to retrieve xref data (like reading from file or calling \\(f@describe-function)), DATA is an argument to this method \(like file name or function name), and LABEL is displayed in text using \\(v@docref-highlight-face). The special reference `back' can be used to return back. The variable \\(v@docref-back-label) specifies the label to use for that. See \\(v@docref-methods-alist) for currently defined methods." (interactive "b") (save-excursion (set-buffer buf) (goto-char (point-min)) ;; The docref-seen property indicates that we have processed this ;; buffer's contents already, so don't do it again. (if (not (get-text-property (point-min) 'docref-seen)) (let ((old-modified (buffer-modified-p))) (while (re-search-forward "[\\](\\([^\)\@]+\\)\\(@[^\)\@]+\\)?@\\([^\)]*\\))" nil t) (let* ((start (match-beginning 0)) (type (buffer-substring (match-beginning 1) (match-end 1))) (data (buffer-substring (match-beginning 3) (match-end 3))) (label (if (match-beginning 2) (buffer-substring (+ (match-beginning 2) 1) (match-end 2)) data))) (replace-match "" t) (docref-insert-label label (cons type data)))) ;; Make a back-reference in this buffer, if desired. ;; (This is true if called from docref-follow.) (if docref-back-reference (progn (goto-char (point-max)) (put-text-property (point-min) (1+ (point-min)) 'docref-back-position (point)) (docref-insert-label docref-back-label docref-back-reference))) (put-text-property (point-min) (1+ (point-min)) 'docref-seen t) (set-buffer-modified-p old-modified))))) (defun docref-insert-label (string ref) (let ((label (concat string)) (pos (point))) ;; decorate the label (let ((leading-space-end (save-match-data (if (string-match "^\\([ \t\n]+\\)" label) (match-end 1) 0))) (trailing-space-start (save-match-data (if (string-match "\\([ \t\n]+\\)$" label) (match-beginning 1) (length label))))) (if docref-highlight-p (if (not window-system) (setq label (concat (substring label 0 leading-space-end) "(*note " (substring label leading-space-end trailing-space-start) ")" (substring label trailing-space-start))) ;; window-system (put-text-property leading-space-end trailing-space-start 'face docref-highlight-face label))) (put-text-property 0 (length label) 'docref ref label) (insert label)))) (defun docref-follow-mouse (click) "Follow the cross-reference that you click on." (interactive "e") (save-excursion (let* ((start (event-start click)) (window (car start)) (pos (car (cdr start))) (docref-last-active-buffer (current-buffer))) (set-buffer (window-buffer window)) (docref-follow pos)))) (defun docref-go-back () "Go back to the previous contents of help buffer." (interactive) (let ((pos (get-text-property (point-min) 'docref-back-position))) (if pos (docref-follow pos) (error "No go-back reference")))) (defun docref-follow (&optional pos) "Follow cross-reference at point. For the cross-reference format, see \\(f@docref-subst). The special reference named `back' can be used to return back" (interactive) (or pos (setq pos (point))) (let ((docref-data (get-text-property pos 'docref))) (if docref-data ;; There is a reference at point. Follow it. (let* ((type (car docref-data)) (name (cdr docref-data)) (method (assoc type docref-methods-alist)) (cur-contents (buffer-string)) (opoint (point)) (docref-back-reference (cons "s" cur-contents)) success) (if (null method) (error "Unknown cross-reference type: %s" type)) (unwind-protect (save-excursion (funcall (cdr method) name) (setq success t)) (or success (progn ;; (cdr method) got an error. ;; Put back the text that we had. (erase-buffer) (insert cur-contents) (goto-char opoint))) (set-buffer-modified-p nil)))))) ;; Builtin methods for accessing a reference. (defun docref-describe-function (data) (save-excursion (if (boundp 'docref-last-active-buffer) (set-buffer docref-last-active-buffer)) (describe-function (intern data)))) (defun docref-describe-variable (data) (save-excursion (if (boundp 'docref-last-active-buffer) (set-buffer docref-last-active-buffer)) (describe-variable (intern data)))) (defun docref-read-file (data) (with-output-to-temp-buffer (buffer-name) (erase-buffer) (insert-file-contents (expand-file-name data)))) (defun docref-use-string (data) (with-output-to-temp-buffer (buffer-name) (erase-buffer) (insert data))) (defun docref-use-variable-value (data) (let ((sym (intern data))) (with-output-to-temp-buffer (buffer-name) (erase-buffer) (princ (symbol-value sym))))) (provide 'docref) ;;; docref.el ends here