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