1 ;;; reftex-toc.el - RefTeX's table of contents mode
2 ;; Copyright (c) 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
4 ;; Author: Carsten Dominik <dominik@strw.LeidenUniv.nl>
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
25 (eval-when-compile (require 'cl))
30 (defvar reftex-toc-map (make-sparse-keymap)
31 "Keymap used for *toc* buffer.")
33 (defvar reftex-toc-menu)
35 (defun reftex-toc-mode ()
36 "Major mode for managing Table of Contents for LaTeX files.
37 This buffer was created with RefTeX.
38 Press `?' for a summary of important key bindings.
40 Here are all local bindings.
44 (kill-all-local-variables)
45 (setq major-mode 'reftex-toc-mode
47 (use-local-map reftex-toc-map)
48 (set (make-local-variable 'revert-buffer-function) 'reftex-toc-revert)
49 (set (make-local-variable 'reftex-toc-include-labels-indicator) "")
50 (set (make-local-variable 'reftex-toc-max-level-indicator)
51 (if (= reftex-toc-max-level 100)
53 (int-to-string reftex-toc-max-level)))
54 (setq mode-line-format
55 (list "---- " 'mode-line-buffer-identification
56 " " 'global-mode-string " (" mode-name ")"
57 " L<" 'reftex-toc-include-labels-indicator ">"
58 " I<" 'reftex-toc-include-index-indicator ">"
59 " T<" 'reftex-toc-max-level-indicator ">"
61 (setq truncate-lines t)
62 (make-local-hook 'post-command-hook)
63 (make-local-hook 'pre-command-hook)
64 (make-local-variable 'reftex-last-follow-point)
65 (add-hook 'post-command-hook 'reftex-toc-post-command-hook nil t)
66 (add-hook 'pre-command-hook 'reftex-toc-pre-command-hook nil t)
67 (easy-menu-add reftex-toc-menu reftex-toc-map)
68 (run-hooks 'reftex-toc-mode-hook))
70 (defvar reftex-last-toc-file nil
71 "Stores the file name from which `reftex-toc' was called. For redo command.")
73 (defvar reftex-last-window-height nil)
74 (defvar reftex-toc-include-labels-indicator nil)
75 (defvar reftex-toc-include-index-indicator nil)
76 (defvar reftex-toc-max-level-indicator nil)
78 (defvar reftex-toc-return-marker (make-marker)
79 "Marker which makes it possible to return from toc to old position.")
81 (defconst reftex-toc-help
82 " AVAILABLE KEYS IN TOC BUFFER
83 ============================
84 n / p next-line / previous-line
85 SPC Show the corresponding location of the LaTeX document.
86 TAB Goto the location and keep the *toc* window.
87 RET Goto the location and hide the *toc* window (also on mouse-2).
88 C-c > Display Index. With prefix arg, restrict index to current section.
89 q / k Hide/Kill *toc* buffer, return to position of reftex-toc command.
90 l i c F Toggle display of [l]abels, [i]ndex, [c]ontext, [F]ile borders.
91 t Change maximum toc depth (e.g. `3 t' hides levels greater than 3).
92 f / g Toggle follow mode on and off / Refresh *toc* buffer.
93 r / C-u r Reparse the LaTeX document / Reparse entire LaTeX document.
94 . In other window, show position from where `reftex-toc' was called.
95 x Switch to TOC of external document (with LaTeX package `xr').")
97 (defun reftex-toc (&optional rebuild)
98 "Show the table of contents for the current document.
99 When called with a raw C-u prefix, rescan the document first."
103 (if (or (not (string= reftex-last-toc-master (reftex-TeX-master-file)))
105 (reftex-erase-buffer "*toc*"))
107 (setq reftex-last-toc-file (buffer-file-name))
108 (setq reftex-last-toc-master (reftex-TeX-master-file))
110 (set-marker reftex-toc-return-marker (point))
112 ;; If follow mode is active, arrange to delay it one command
113 (if reftex-toc-follow-mode
114 (setq reftex-toc-follow-mode 1))
116 (and reftex-toc-include-index-entries
117 (reftex-ensure-index-support))
118 (or reftex-support-index
119 (setq reftex-toc-include-index-entries nil))
121 ;; Ensure access to scanning info and rescan buffer if prefix are is '(4)
122 (reftex-access-scan-info current-prefix-arg)
124 (let* ((this-buf (current-buffer))
125 (docstruct-symbol reftex-docstruct-symbol)
126 (xr-data (assq 'xr (symbol-value reftex-docstruct-symbol)))
127 (xr-alist (cons (cons "" (buffer-file-name)) (nth 1 xr-data)))
128 (here-I-am (if rebuild
129 (get 'reftex-toc :reftex-data)
130 (car (reftex-where-am-I))))
133 (if (get-buffer-window "*toc*")
134 (select-window (get-buffer-window "*toc*"))
135 (when (or (not reftex-toc-keep-other-windows)
136 (< (window-height) (* 2 window-min-height)))
137 (delete-other-windows))
138 (setq reftex-last-window-height (window-height)) ; remember
140 (let ((default-major-mode 'reftex-toc-mode))
141 (switch-to-buffer "*toc*")))
143 (or (eq major-mode 'reftex-toc-mode) (reftex-toc-mode))
144 (set (make-local-variable 'reftex-docstruct-symbol) docstruct-symbol)
145 (setq reftex-toc-include-labels-indicator
146 (if (eq reftex-toc-include-labels t)
148 reftex-toc-include-labels))
149 (setq reftex-toc-include-index-indicator
150 (if (eq reftex-toc-include-index-entries t)
152 reftex-toc-include-index-entries))
156 ;; buffer is empty - fill it with the table of contents
157 (message "Building *toc* buffer...")
159 (setq buffer-read-only nil)
161 "TABLE-OF-CONTENTS on %s
162 SPC=view TAB=goto RET=goto+hide [q]uit [r]escan [l]abels [f]ollow [x]r [?]Help
163 ------------------------------------------------------------------------------
164 " (abbreviate-file-name reftex-last-toc-master)))
166 (if (reftex-use-fonts)
167 (put-text-property 1 (point) 'face reftex-toc-header-face))
168 (put-text-property 1 (point) 'intangible t)
169 (put-text-property 1 2 'xr-alist xr-alist)
172 (reftex-insert-docstruct
175 reftex-toc-include-labels
176 reftex-toc-include-index-entries
177 reftex-toc-include-file-boundaries
178 reftex-toc-include-context
186 (run-hooks 'reftex-display-copied-context-hook)
187 (message "Building *toc* buffer...done.")
188 (setq buffer-read-only t))
190 ;; Only compute the offset
192 (or (reftex-get-offset this-buf here-I-am
193 (if reftex-toc-include-labels " " nil)
195 reftex-toc-include-index-entries
196 reftex-toc-include-file-boundaries)
197 (reftex-last-assoc-before-elt
199 (symbol-value reftex-docstruct-symbol))))
200 (put 'reftex-toc :reftex-line 3)
202 (beginning-of-line)))
204 ;; Find the correct starting point
205 (reftex-find-start-point (point) offset (get 'reftex-toc :reftex-line))
206 (setq reftex-last-follow-point (point))))
208 (defun reftex-toc-pre-command-hook ()
209 ;; used as pre command hook in *toc* buffer
210 (reftex-unhighlight 0)
211 (reftex-unhighlight 1))
213 (defun reftex-toc-post-command-hook ()
214 ;; used in the post-command-hook for the *toc* buffer
215 (when (get-text-property (point) :data)
216 (put 'reftex-toc :reftex-data (get-text-property (point) :data))
218 (not (get-text-property (point) 'intangible))
219 (memq reftex-highlight-selection '(cursor both))
221 (or (previous-single-property-change (1+ (point)) :data)
223 (or (next-single-property-change (point) :data)
225 (if (integerp reftex-toc-follow-mode)
226 ;; remove delayed action
227 (setq reftex-toc-follow-mode t)
228 (and reftex-toc-follow-mode
229 (not (equal reftex-last-follow-point (point)))
230 ;; show context in other window
231 (setq reftex-last-follow-point (point))
233 (reftex-toc-visit-location nil (not reftex-revisit-to-follow))
236 (defun reftex-re-enlarge ()
237 ;; Enlarge windiw to a remembered size
239 (max 0 (- (or reftex-last-window-height (window-height))
242 (defun reftex-toc-show-help ()
243 "Show a summary of special key bindings."
245 (with-output-to-temp-buffer "*RefTeX Help*"
246 (princ reftex-toc-help))
247 (reftex-enlarge-to-fit "*RefTeX Help*" t)
248 ;; If follow mode is active, arrange to delay it one command
249 (if reftex-toc-follow-mode
250 (setq reftex-toc-follow-mode 1)))
252 (defun reftex-toc-next (&optional arg)
253 "Move to next selectable item."
255 (setq reftex-callback-fwd t)
256 (or (eobp) (forward-char 1))
257 (goto-char (or (next-single-property-change (point) :data)
259 (defun reftex-toc-previous (&optional arg)
260 "Move to previous selectable item."
262 (setq reftex-callback-fwd nil)
263 (goto-char (or (previous-single-property-change (point) :data)
265 (defun reftex-toc-next-heading (&optional arg)
266 "Move to next table of contentes line."
269 (re-search-forward "^ " nil t arg)
271 (defun reftex-toc-previous-heading (&optional arg)
272 "Move to previous table of contentes line."
274 (re-search-backward "^ " nil t arg))
275 (defun reftex-toc-toggle-follow ()
276 "Toggle follow (other window follows with context)."
278 (setq reftex-last-follow-point -1)
279 (setq reftex-toc-follow-mode (not reftex-toc-follow-mode)))
280 (defun reftex-toc-toggle-file-boundary ()
281 "Toggle inclusion of file boundaries in *toc* buffer."
283 (setq reftex-toc-include-file-boundaries
284 (not reftex-toc-include-file-boundaries))
286 (defun reftex-toc-toggle-labels (arg)
287 "Toggle inclusion of labels in *toc* buffer.
288 With prefix ARG, prompt for a label type and include only labels of
291 (setq reftex-toc-include-labels
292 (if arg (reftex-query-label-type)
293 (not reftex-toc-include-labels)))
295 (defun reftex-toc-toggle-index (arg)
296 "Toggle inclusion of index in *toc* buffer.
297 With prefix arg, prompt for an index tag and include only entries of that
300 (setq reftex-toc-include-index-entries
301 (if arg (reftex-index-select-tag)
302 (not reftex-toc-include-index-entries)))
304 (defun reftex-toc-toggle-context ()
305 "Toggle inclusion of label context in *toc* buffer.
306 Label context is only displayed when the labels are there as well."
308 (setq reftex-toc-include-context (not reftex-toc-include-context))
310 (defun reftex-toc-max-level (arg)
311 "Set the maximum level of toc lines in this buffer to value of prefix ARG.
312 When no prefix is given, set the max level to a large number, so that all
313 levels are shown. For eaxample, to set the level to 3, type `3 m'."
315 (setq reftex-toc-max-level (if arg
316 (prefix-numeric-value arg)
318 (setq reftex-toc-max-level-indicator
319 (if arg (int-to-string reftex-toc-max-level) "ALL"))
321 (defun reftex-toc-view-line ()
322 "View document location in other window."
324 (reftex-toc-visit-location))
325 (defun reftex-toc-goto-line-and-hide ()
326 "Go to document location in other window. Hide the *toc* window."
328 (reftex-toc-visit-location 'hide))
329 (defun reftex-toc-goto-line ()
330 "Go to document location in other window. *toc* window stays."
332 (reftex-toc-visit-location t))
333 (defun reftex-toc-mouse-goto-line-and-hide (ev)
334 "Go to document location in other window. Hide the *toc* window."
337 (reftex-toc-visit-location 'hide))
338 (defun reftex-toc-show-calling-point ()
339 "Show point where reftex-toc was called from."
341 (let ((this-window (selected-window)))
344 (switch-to-buffer-other-window
345 (marker-buffer reftex-toc-return-marker))
346 (goto-char (marker-position reftex-toc-return-marker))
348 (select-window this-window))))
349 (defun reftex-toc-quit ()
350 "Hide the *toc* window and do not move point."
352 (or (one-window-p) (delete-window))
353 (switch-to-buffer (marker-buffer reftex-toc-return-marker))
355 (goto-char (or (marker-position reftex-toc-return-marker) (point))))
356 (defun reftex-toc-quit-and-kill ()
357 "Kill the *toc* buffer."
359 (kill-buffer "*toc*")
360 (or (one-window-p) (delete-window))
361 (switch-to-buffer (marker-buffer reftex-toc-return-marker))
363 (goto-char (marker-position reftex-toc-return-marker)))
364 (defun reftex-toc-display-index (&optional arg)
365 "Display the index buffer for the current document.
366 This works just like `reftex-display-index' from a LaTeX buffer.
367 With prefix arg 1, restrict index to the section at point."
369 (let ((data (get-text-property (point) :data))
370 (docstruct (symbol-value reftex-docstruct-symbol))
373 (setq bor (reftex-last-assoc-before-elt 'toc data docstruct)
374 eor (assoc 'toc (cdr (memq bor docstruct)))
375 restr (list (nth 6 bor) bor eor)))
376 (reftex-toc-goto-line)
377 (reftex-display-index (if restr nil arg) restr)))
378 (defun reftex-toc-rescan (&rest ignore)
379 "Regenerate the *toc* buffer by reparsing file of section at point."
381 (if (and reftex-enable-partial-scans
382 (null current-prefix-arg))
383 (let* ((data (get-text-property (point) :data))
385 (file (cond ((eq what 'toc) (nth 3 data))
386 ((memq what '(eof bof file-error)) (nth 1 data))
387 ((stringp what) (nth 3 data))
388 ((eq what 'index) (nth 3 data))))
389 (line (+ (count-lines (point-min) (point)) (if (bolp) 1 0))))
391 (error "Don't know which file to rescan. Try `C-u r'")
392 (put 'reftex-toc :reftex-line line)
393 (switch-to-buffer-other-window
394 (reftex-get-file-buffer-force file))
395 (setq current-prefix-arg '(4))
398 (reftex-kill-temporary-buffers))
399 (defun reftex-toc-Rescan (&rest ignore)
400 "Regenerate the *toc* buffer by reparsing the entire document."
402 (switch-to-buffer-other-window
403 (reftex-get-file-buffer-force reftex-last-toc-file))
404 (setq current-prefix-arg '(16))
406 (defun reftex-toc-revert (&rest ignore)
407 "Regenerate the *toc* from the internal lists."
409 (switch-to-buffer-other-window
410 (reftex-get-file-buffer-force reftex-last-toc-file))
411 (reftex-erase-buffer "*toc*")
412 (setq current-prefix-arg nil)
414 (defun reftex-toc-external (&rest ignore)
415 "Switch to table of contents of an external document."
417 (let* ((old-buf (current-buffer))
418 (xr-alist (get-text-property 1 'xr-alist))
419 (xr-index (reftex-select-external-document
421 (switch-to-buffer-other-window (or (reftex-get-file-buffer-force
422 (cdr (nth xr-index xr-alist)))
423 (error "Cannot switch document")))
425 (if (equal old-buf (current-buffer))
427 (message "Switched document"))))
429 (defun reftex-toc-visit-location (&optional final no-revisit)
430 ;; Visit the tex file corresponding to the toc entry on the current line.
431 ;; If FINAL is t, stay there
432 ;; If FINAL is 'hide, hide the *toc* window.
433 ;; Otherwise, move cursor back into *toc* window.
434 ;; NO-REVISIT means don't visit files, just use live biffers.
435 ;; This function is pretty clever about finding back a section heading,
436 ;; even if the buffer is not live, or things like outline, x-symbol etc.
439 (let* ((toc (get-text-property (point) :data))
440 (toc-window (selected-window))
441 show-window show-buffer match)
443 (unless toc (error "Don't know which toc line to visit"))
449 (setq match (reftex-toc-find-section toc no-revisit)))
451 ((eq (car toc) 'index)
453 (setq match (reftex-index-show-entry toc no-revisit)))
455 ((memq (car toc) '(bof eof))
458 (let ((where (car toc))
460 (if (or (not no-revisit) (reftex-get-buffer-visiting file))
462 (switch-to-buffer-other-window
463 (reftex-get-file-buffer-force file nil))
464 (goto-char (if (eq where 'bof) (point-min) (point-max))))
465 (message reftex-no-follow-message) nil))))
469 (setq match (reftex-show-label-location toc reftex-callback-fwd
472 (setq show-window (selected-window)
473 show-buffer (current-buffer))
476 (select-window toc-window)
477 (error "Cannot find location"))
479 (select-window toc-window)
481 ;; use the `final' parameter to decide what to do next
484 (reftex-unhighlight 0)
485 (select-window show-window))
487 (reftex-unhighlight 0)
488 (or (one-window-p) (delete-window))
489 (switch-to-buffer show-buffer)
493 (defun reftex-toc-find-section (toc &optional no-revisit)
494 (let* ((file (nth 3 toc))
497 (literal (nth 7 toc))
498 (emergency-point (nth 8 toc))
501 ((and (markerp marker) (marker-buffer marker))
502 ;; Buffer is still live and we have the marker. Should be easy.
503 (switch-to-buffer-other-window (marker-buffer marker))
504 (goto-char (marker-position marker))
505 (or (looking-at (regexp-quote literal))
506 (looking-at (reftex-make-regexp-allow-for-ctrl-m literal))
507 (looking-at (reftex-make-desperate-section-regexp literal))
508 (looking-at (concat "\\\\"
512 reftex-section-levels-all)))
514 ((or (not no-revisit)
515 (reftex-get-buffer-visiting file))
516 ;; Marker is lost. Use the backup method.
517 (switch-to-buffer-other-window
518 (reftex-get-file-buffer-force file nil))
519 (goto-char (or emergency-point (point-min)))
520 (or (looking-at (regexp-quote literal))
521 (let ((len (length literal)))
522 (or (reftex-nearest-match (regexp-quote literal) len)
523 (reftex-nearest-match
524 (reftex-make-regexp-allow-for-ctrl-m literal) len)
525 (reftex-nearest-match
526 (reftex-make-desperate-section-regexp literal) len)))))
527 (t (message reftex-no-follow-message) nil))))
529 (goto-char (match-beginning 0))
530 (if (not (= (point) (point-max))) (recenter 1))
531 (reftex-highlight 0 (match-beginning 0) (match-end 0) (current-buffer)))
534 (defun reftex-make-desperate-section-regexp (old)
535 ;; Return a regexp which will still match a section statement even if
536 ;; x-symbol or isotex or the like have been at work in the mean time.
537 (let* ((n (1+ (string-match "[[{]" old)))
538 (new (regexp-quote (substring old 0 (1+ (string-match "[[{]" old)))))
539 (old (substring old n)))
541 "\\([\r\n]\\)\\|\\(\\`\\|[ \t\n\r]\\)\\([a-zA-Z0-9]+\\)\\([ \t\n\r]\\|}\\'\\)"
543 (if (match-beginning 1)
544 (setq new (concat new "[^\n\r]*[\n\r]"))
545 (setq new (concat new "[^\n\r]*" (match-string 3 old))))
546 (setq old (substring old (match-end 0))))
549 ;; Table of Contents map
550 (define-key reftex-toc-map (if (featurep 'xemacs) [(button2)] [(mouse-2)])
551 'reftex-toc-mouse-goto-line-and-hide)
553 (substitute-key-definition
554 'next-line 'reftex-toc-next reftex-toc-map global-map)
555 (substitute-key-definition
556 'previous-line 'reftex-toc-previous reftex-toc-map global-map)
559 '(("n" . reftex-toc-next)
560 ("p" . reftex-toc-previous)
561 ("?" . reftex-toc-show-help)
562 (" " . reftex-toc-view-line)
563 ("\C-m" . reftex-toc-goto-line-and-hide)
564 ("\C-i" . reftex-toc-goto-line)
565 ("\C-c>". reftex-toc-display-index)
566 ("r" . reftex-toc-rescan)
567 ("R" . reftex-toc-Rescan)
568 ("g" . revert-buffer)
569 ("q" . reftex-toc-quit)
570 ("k" . reftex-toc-quit-and-kill)
571 ("f" . reftex-toc-toggle-follow)
572 ("F" . reftex-toc-toggle-file-boundary)
573 ("i" . reftex-toc-toggle-index)
574 ("l" . reftex-toc-toggle-labels)
575 ("t" . reftex-toc-max-level)
576 ("c" . reftex-toc-toggle-context)
577 ("%" . reftex-toc-toggle-commented)
578 ("x" . reftex-toc-external)
579 ("." . reftex-toc-show-calling-point)
580 ("\C-c\C-n" . reftex-toc-next-heading)
581 ("\C-c\C-p" . reftex-toc-previous-heading))
582 do (define-key reftex-toc-map (car x) (cdr x)))
584 (loop for key across "0123456789" do
585 (define-key reftex-toc-map (vector (list key)) 'digit-argument))
586 (define-key reftex-toc-map "-" 'negative-argument)
589 reftex-toc-menu reftex-toc-map
590 "Menu for Table of Contents buffer"
592 ["Show Location" reftex-toc-view-line t]
593 ["Go To Location" reftex-toc-goto-line t]
594 ["Exit & Go To Location" reftex-toc-goto-line-and-hide t]
595 ["Index" reftex-toc-display-index t]
596 ["Quit" reftex-toc-quit t]
598 ["External Document TOC " reftex-toc-external t]
601 ["Rebuilt *toc* Buffer" revert-buffer t]
602 ["Rescan One File" reftex-toc-rescan reftex-enable-partial-scans]
603 ["Rescan Entire Document" reftex-toc-Rescan t])
606 ["File Boundaries" reftex-toc-toggle-file-boundary :style toggle
607 :selected reftex-toc-include-file-boundaries]
608 ["Labels" reftex-toc-toggle-labels :style toggle
609 :selected reftex-toc-include-labels]
610 ["Index Entries" reftex-toc-toggle-index :style toggle
611 :selected reftex-toc-include-index-entries]
612 ["Context" reftex-toc-toggle-context :style toggle
613 :selected reftex-toc-include-context]
615 ["Follow Mode" reftex-toc-toggle-follow :style toggle
616 :selected reftex-toc-follow-mode])
618 ["Help" reftex-toc-show-help t]))
621 ;;; reftex-toc.el ends here