blob: 43d9688accba19dbc14618bb11e659c53290d19d [file] [log] [blame]
Daniel Veillardca989762001-06-23 17:39:29 +00001;;; libxml-doc.el - look up libxml-symbols and start browser on documentation
Daniel Veillardc310d562000-06-23 18:32:15 +00002
Daniel Veillardca989762001-06-23 17:39:29 +00003;; Author: Felix Natter <fnatter@gmx.net>, Geert Kloosterman <geertk@ai.rug.nl>
Daniel Veillardc310d562000-06-23 18:32:15 +00004;; Created: Jun 21 2000
5;; Keywords: libxml documentation
6
7;; This program is free software; you can redistribute it and/or
8;; modify it under the terms of the GNU General Public License
9;; as published by the Free Software Foundation; either version 2
10;; of the License, or (at your option) any later version.
11;;
12;; This program is distributed in the hope that it will be useful,
13;; but WITHOUT ANY WARRANTY; without even the implied warranty of
14;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15;; GNU General Public License for more details.
16;;
17;; You should have received a copy of the GNU General Public License
18;; along with this program; if not, write to the Free Software
19;; Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20
21 ;;; Commentary / README
22
23;; these functions allow you to browse the libxml documentation
Daniel Veillard449d7392001-07-07 19:11:06 +000024;; (using lynx within emacs by default)
25;;
Daniel Veillardc310d562000-06-23 18:32:15 +000026;; ----- Installing
27;; 1. add the following to ~/.emacs (adapt path and remove comments !)
Daniel Veillardca989762001-06-23 17:39:29 +000028;; (autoload 'libxmldoc-lookup-symbol "~/elisp/libxml-doc"
29;; "Look up libxml-symbols and start browser on documentation." t)
30;; or put this file in load-path and use this:
31;; (autoload 'libxmldoc-lookup-symbol "libxml-doc"
32;; "Look up libxml-symbols and start browser on documentation." t)
Daniel Veillard449d7392001-07-07 19:11:06 +000033;;
Daniel Veillardc310d562000-06-23 18:32:15 +000034;; 2. adapt libxmldoc-root:
Daniel Veillard06500c82004-09-07 09:12:44 +000035;; i.e. (setq libxmldoc-root "~/libxml2-2.0.0/doc/html")
Daniel Veillard449d7392001-07-07 19:11:06 +000036;;
Daniel Veillardc310d562000-06-23 18:32:15 +000037;; 3. change the filter-regex: by default, cpp-defines, callbacks and
38;; html-functions are excluded (C-h v libxmldoc-filter-regexp)
Daniel Veillard449d7392001-07-07 19:11:06 +000039;;
Daniel Veillardc310d562000-06-23 18:32:15 +000040;; 4. consider customizing libxmldoc-browse-url (lynx by default);
41;; cannot use Emacs/W3 4.0pre46 because it has problems with the html
Daniel Veillard449d7392001-07-07 19:11:06 +000042;;
Daniel Veillardc310d562000-06-23 18:32:15 +000043;; ----- Using
Daniel Veillardca989762001-06-23 17:39:29 +000044;; call M-x libxmldoc-lookup-symbol: this will prompt with completion and
45;; then open the browser showing the documentation. If the word around the
46;; point matches a symbol, that is used instead. You can also call
47;; libxmldoc-lookup-symbol noninteractively and pass the symbol.
48
49;; Note:
50;; an alternative to libxml-doc is emacs tags:
51;; $ cd libxml2-2.3.8
Daniel Veillard449d7392001-07-07 19:11:06 +000052;; $ make TAGS
Daniel Veillardca989762001-06-23 17:39:29 +000053;; $ emacs
54;; M-. (M-x find-tag) ... or
55;; M-x tags-search ... RET M-, M-, ...
56;; (for more information: info emacs RET m Tags RET)
57
Daniel Veillardc310d562000-06-23 18:32:15 +000058
59 ;;; ChangeLog:
60;; Wed Jun 21 01:07:12 2000: initial release
61;; Wed Jun 21 01:45:29 2000: added libxmldoc-lookup-symbol-at-point
62;; Wed Jun 21 23:37:58 2000: libxmldoc-lookup-symbol now uses
63;; (thing-at-point 'word) if it matches a symbol
64;; Thu Jun 22 02:37:46 2000: filtering is only done for completion
65;; Thu Jun 22 21:03:41 2000: libxmldoc-browse-url can be customized
Daniel Veillard8a367d42001-06-07 14:01:34 +000066;; Thu May 31 2001 (Geert):
67;; - Changed the `gnome-xml-' html file prefix into `libxml-'.
68;; - Changed the 'word match from thing-at-point into 'symbol.
69;; With 'word, identifiers with an underscore (e.g. BAD_CAST)
70;; don't get matched.
Daniel Veillardca989762001-06-23 17:39:29 +000071;; Fri Jun 8 16:29:18 2001, Sat Jun 23 16:19:47 2001:
72;; complete rewrite of libxmldoc-lookup-symbol
73;; by Felix Natter <fnatter@gmx.net>, Geert Kloosterman <geertk@ai.rug.nl>:
Daniel Veillard8a367d42001-06-07 14:01:34 +000074;; - Now keeps the list of symbols between calls to speed things up.
Daniel Veillardca989762001-06-23 17:39:29 +000075;; - filtering is only used when no symbol is passed and
76;; thing-at-point does not match a symbol and "*" + thing-at-point
77;; does not match a symbol (this is used to catch callbacks) and
78;; libxmldoc-filter-regexp is non-nil.
79;; Sat Jun 23 16:20:34 2001: update the docstrings
80;; Sat Jun 23 16:22:54 2001 (Geert Kloosterman <geertk@ai.rug.nl>):
81;; update README: use autoload instead of load+c-mode-hook
Daniel Veillard449d7392001-07-07 19:11:06 +000082;; Sat Jul 7 19:00:31 2001: fixed a problem with XEmacs: the
83;; string-match of XEmacs when used in completing-read used the
84;; minibuffer's value of case-fold-search, and not the one in the
85;; c-mode buffer that we had set => so there's a new *-string-match-cs
86;; (case sensitive) function which binds case-fold-search and runs string-match
Daniel Veillard06500c82004-09-07 09:12:44 +000087;; Wed Sep 1 20:26:29 2004: adapted for libxml2-2.6.9: handle
88;; document-relative (#XXX) links
Daniel Veillard8a367d42001-06-07 14:01:34 +000089
Daniel Veillardc310d562000-06-23 18:32:15 +000090;;; TODO:
Daniel Veillardca989762001-06-23 17:39:29 +000091;; - use command-execute for libxmldoc-browse-url
92;; - keep (match-string 1) in a variable (libxmldoc-get-list-of-symbols)
Daniel Veillard449d7392001-07-07 19:11:06 +000093;; (only if it improves performance)
Daniel Veillardca989762001-06-23 17:39:29 +000094;; - check the (require ..)-statements
Daniel Veillardc310d562000-06-23 18:32:15 +000095
96 ;;; Code:
97
Daniel Veillardca989762001-06-23 17:39:29 +000098(require 'browse-url)
99(require 'term)
100
101(defvar libxmldoc-root "~/src/libxml2-2.3.8/doc/html"
Daniel Veillardc310d562000-06-23 18:32:15 +0000102 "The root-directory of the libxml2-documentation (~ will be expanded).")
Daniel Veillardca989762001-06-23 17:39:29 +0000103(defvar libxmldoc-filter-regexp "^html\\|^\\*\\|^[A-Z_]+"
Daniel Veillardc310d562000-06-23 18:32:15 +0000104 "Symbols that match this regular expression will be excluded when doing
Daniel Veillardca989762001-06-23 17:39:29 +0000105completion and no symbol is specified.
Daniel Veillardc310d562000-06-23 18:32:15 +0000106 For example:
107 callbacks: \"^\\\\*\"
108 cpp-defines: \"[A-Z_]+\"
109 xml-functions \"^xml\"
110 html-functions \"^html\"
111 sax-functions \".*SAX\"
Daniel Veillardca989762001-06-23 17:39:29 +0000112By default, callbacks, cpp-defines and html* are excluded.
113Set this to nil if you don't want filtering.")
Daniel Veillardc310d562000-06-23 18:32:15 +0000114(defvar libxmldoc-browse-url 'browse-url-lynx-emacs
115 "Browser used for browsing documentation. Emacs/W3 4.0pre46 cannot handle
Daniel Veillardca989762001-06-23 17:39:29 +0000116the html (and would be too slow), so lynx-emacs is used by default.")
Daniel Veillardc310d562000-06-23 18:32:15 +0000117(defvar libxmldoc-symbol-history nil
118 "History for looking up libxml-symbols.")
Daniel Veillardca989762001-06-23 17:39:29 +0000119(defvar libxmldoc-symbols nil
120 "The list of libxml-symbols.")
Daniel Veillard8a367d42001-06-07 14:01:34 +0000121
Daniel Veillardc310d562000-06-23 18:32:15 +0000122 ;;;; public functions
123
124(defun libxmldoc-lookup-symbol(&optional symbol)
125 "Look up xml-symbol." (interactive)
Daniel Veillard449d7392001-07-07 19:11:06 +0000126 ;; setting case-fold-search is now done in libxmldoc-string-match-cs
Daniel Veillard8a367d42001-06-07 14:01:34 +0000127
Daniel Veillard784b9352003-02-16 15:50:27 +0000128 ;; Build up a symbol list if necessary
Daniel Veillard449d7392001-07-07 19:11:06 +0000129 (if (null libxmldoc-symbols)
130 (setq libxmldoc-symbols (libxmldoc-get-list-of-symbols)))
Daniel Veillardca989762001-06-23 17:39:29 +0000131
Daniel Veillard449d7392001-07-07 19:11:06 +0000132 (cond
133 (symbol ;; symbol is specified as argument
134 (if (not (assoc symbol libxmldoc-symbols))
135 (setq symbol nil)))
136 ((assoc (thing-at-point 'symbol) libxmldoc-symbols)
137 (setq symbol (thing-at-point 'symbol)))
138 ;; this is needed to catch callbacks
139 ;; note: this could be rewritten to use (thing-at-point 'word)
140 ((assoc (concat "*" (thing-at-point 'symbol)) libxmldoc-symbols)
141 (setq symbol (concat "*" (thing-at-point 'symbol))))
142 )
Daniel Veillard8a367d42001-06-07 14:01:34 +0000143
Daniel Veillard449d7392001-07-07 19:11:06 +0000144 ;; omit "" t) from call to completing-read for the sake of xemacs
145 (setq symbol (completing-read
146 "Libxml: " libxmldoc-symbols
147 (if (or symbol (null libxmldoc-filter-regexp))
148 nil
149 '(lambda(key,value)
150 (not (libxmldoc-string-match-cs libxmldoc-filter-regexp
151 (car key,value)))))
152 t symbol
153 'libxmldoc-symbol-history))
Daniel Veillardca989762001-06-23 17:39:29 +0000154
155
Daniel Veillard449d7392001-07-07 19:11:06 +0000156 ;; start browser
157 (apply libxmldoc-browse-url
158 (list (cdr (assoc symbol libxmldoc-symbols)))))
159
160;; (if (or symbol
161;; (null libxmldoc-filter-regexp))
162;; libxmldoc-symbols
163;; (mapcar
164;; '(lambda(key,value)
165;; (if (null (string-match
166;; libxmldoc-filter-regexp
167;; (car key,value)))
168;; key,value))
169;; libxmldoc-symbols))
170
Daniel Veillardc310d562000-06-23 18:32:15 +0000171
172;;;; internal
173
Daniel Veillard449d7392001-07-07 19:11:06 +0000174(defun libxmldoc-string-match-cs(regexp str)
175 "This is needed because string-match in XEmacs uses the current-
176buffer's value of case-fold-search (different from GNU Emacs)."
177 (let ((case-fold-search nil))
178 (string-match regexp str)))
179
Daniel Veillardca989762001-06-23 17:39:29 +0000180(defun libxmldoc-get-list-of-symbols()
Daniel Veillardc310d562000-06-23 18:32:15 +0000181 "Get the list of html-links in the libxml-documentation."
Daniel Veillardca989762001-06-23 17:39:29 +0000182 (let ((files
183 (directory-files
184 libxmldoc-root t
185 (concat "^" (if (file-exists-p (concat libxmldoc-root
186 "/libxml-parser.html"))
187 "libxml-"
188 "gnome-xml-")
189 ".*\\.html$") t))
Daniel Veillard8a367d42001-06-07 14:01:34 +0000190 (symbols ())
191 (case-fold-search t)
Daniel Veillard8a367d42001-06-07 14:01:34 +0000192 (uri))
Daniel Veillardca989762001-06-23 17:39:29 +0000193 (message "collecting libxml-symbols...")
Daniel Veillard8a367d42001-06-07 14:01:34 +0000194 (while (car files)
Daniel Veillard06500c82004-09-07 09:12:44 +0000195 (message "processing %s" (car files))
Daniel Veillardca989762001-06-23 17:39:29 +0000196 (with-temp-buffer
197 (insert-file-contents (car files))
198 (goto-char (point-min))
199 (while (re-search-forward
200 "<a[^>]*href[ \t\n]*=[ \t\n]*\"\\([^=>]*\\)\"[^>]*>" nil t nil)
Daniel Veillard06500c82004-09-07 09:12:44 +0000201 ;; is it a relative link (#XXX)?
202 (if (char-equal (elt (match-string 1) 0) ?#)
203 (setq uri (concat "file://" (car files) (match-string 1)))
204 (setq uri (concat "file://" (expand-file-name libxmldoc-root)
205 "/" (match-string 1))))
Daniel Veillardca989762001-06-23 17:39:29 +0000206 (if (not (re-search-forward "\\([^<]*\\)<" nil t nil))
207 (error "regexp error while getting libxml-symbols.."))
208 ;; this needs add-to-list because i.e. xmlChar appears often
209 (if (not (string-equal "" (match-string 1)))
210 (add-to-list 'symbols (cons (match-string 1) uri))))
Daniel Veillard449d7392001-07-07 19:11:06 +0000211 ;; (setq symbols (cons (cons (match-string 1) uri) symbols)))
212 )
213 (setq files (cdr files)))
214 symbols))
215
216(provide 'libxmldoc)
Daniel Veillardc310d562000-06-23 18:32:15 +0000217
218;;; libxml-doc.el ends here
Daniel Veillard449d7392001-07-07 19:11:06 +0000219
Daniel Veillard8a367d42001-06-07 14:01:34 +0000220;;; Local Variables:
221;;; indent-tabs-mode: nil
222;;; End: