libxml-doc.el
1 ;;; libxml-doc.el - look up libxml-symbols and start browser on documentation 2 3 ;; Author: Felix Natter <fnatter@gmx.net>, Geert Kloosterman <geertk@ai.rug.nl> 4 ;; 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 24 ;; (using lynx within emacs by default) 25 ;; 26 ;; ----- Installing 27 ;; 1. add the following to ~/.emacs (adapt path and remove comments !) 28 ;; (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) 33 ;; 34 ;; 2. adapt libxmldoc-root: 35 ;; i.e. (setq libxmldoc-root "~/libxml2-2.0.0/doc/html") 36 ;; 37 ;; 3. change the filter-regex: by default, cpp-defines, callbacks and 38 ;; html-functions are excluded (C-h v libxmldoc-filter-regexp) 39 ;; 40 ;; 4. consider customizing libxmldoc-browse-url (lynx by default); 41 ;; cannot use Emacs/W3 4.0pre46 because it has problems with the html 42 ;; 43 ;; ----- Using 44 ;; 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 52 ;; $ make TAGS 53 ;; $ 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 58 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 66 ;; 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. 71 ;; 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>: 74 ;; - Now keeps the list of symbols between calls to speed things up. 75 ;; - 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 82 ;; 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 87 ;; Wed Sep 1 20:26:29 2004: adapted for libxml2-2.6.9: handle 88 ;; document-relative (#XXX) links 89 90 ;;; TODO: 91 ;; - use command-execute for libxmldoc-browse-url 92 ;; - keep (match-string 1) in a variable (libxmldoc-get-list-of-symbols) 93 ;; (only if it improves performance) 94 ;; - check the (require ..)-statements 95 96 ;;; Code: 97 98 (require 'browse-url) 99 (require 'term) 100 101 (defvar libxmldoc-root "~/src/libxml2-2.3.8/doc/html" 102 "The root-directory of the libxml2-documentation (~ will be expanded).") 103 (defvar libxmldoc-filter-regexp "^html\\|^\\*\\|^[A-Z_]+" 104 "Symbols that match this regular expression will be excluded when doing 105 completion and no symbol is specified. 106 For example: 107 callbacks: \"^\\\\*\" 108 cpp-defines: \"[A-Z_]+\" 109 xml-functions \"^xml\" 110 html-functions \"^html\" 111 sax-functions \".*SAX\" 112 By default, callbacks, cpp-defines and html* are excluded. 113 Set this to nil if you don't want filtering.") 114 (defvar libxmldoc-browse-url 'browse-url-lynx-emacs 115 "Browser used for browsing documentation. Emacs/W3 4.0pre46 cannot handle 116 the html (and would be too slow), so lynx-emacs is used by default.") 117 (defvar libxmldoc-symbol-history nil 118 "History for looking up libxml-symbols.") 119 (defvar libxmldoc-symbols nil 120 "The list of libxml-symbols.") 121 122 ;;;; public functions 123 124 (defun libxmldoc-lookup-symbol(&optional symbol) 125 "Look up xml-symbol." (interactive) 126 ;; setting case-fold-search is now done in libxmldoc-string-match-cs 127 128 ;; Build up a symbol list if necessary 129 (if (null libxmldoc-symbols) 130 (setq libxmldoc-symbols (libxmldoc-get-list-of-symbols))) 131 132 (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 ) 143 144 ;; 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)) 154 155 156 ;; 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 171 172 ;;;; internal 173 174 (defun libxmldoc-string-match-cs(regexp str) 175 "This is needed because string-match in XEmacs uses the current- 176 buffer's value of case-fold-search (different from GNU Emacs)." 177 (let ((case-fold-search nil)) 178 (string-match regexp str))) 179 180 (defun libxmldoc-get-list-of-symbols() 181 "Get the list of html-links in the libxml-documentation." 182 (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)) 190 (symbols ()) 191 (case-fold-search t) 192 (uri)) 193 (message "collecting libxml-symbols...") 194 (while (car files) 195 (message "processing %s" (car files)) 196 (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) 201 ;; 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)))) 206 (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)))) 211 ;; (setq symbols (cons (cons (match-string 1) uri) symbols))) 212 ) 213 (setq files (cdr files))) 214 symbols)) 215 216 (provide 'libxmldoc) 217 218 ;;; libxml-doc.el ends here 219 220 ;;; Local Variables: 221 ;;; indent-tabs-mode: nil 222 ;;; End: