summaryrefslogtreecommitdiff
path: root/help/tex-macro-catalogue.el
blob: f550ac03b449fafd363d0bb746fd0eb8bd2bc7e6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
;;; ====================================================================
;;;  @Emacs-Lisp-file{
;;;     filename        = "tex-macro-catalogue.el",
;;;     version         = "2.00",
;;;     date            = "15 February 1993",
;;;     time            = "14:43:35 GMT",
;;;     author          = "David Carlisle",
;;;     address         = "Computer Science Department
;;;                        Manchester University
;;;                        Oxford Road
;;;                        Manchester
;;;                        England
;;;                        M13 9PL",
;;;     telephone       = "+44 61 275 6139",
;;;     FAX             = "+44 61 275 6236",
;;;     email           = "carlisle@cs.man.ac.uk (Internet)",
;;;     checksum        = "05502 349 1299 11389",
;;;     codetable       = "ISO/ASCII",
;;;     keywords        = "TeX, macros,styles,index,catalogue",
;;;     supported       = "yes",
;;;     docstring       = "
;;;
;;;     A GNU Emacs interface to David Jones' Catalogue of TeX macros.
;;;
;;;     The most recent version of the catalogue is always available
;;;     from theory.lcs.mit.edu in the directory
;;;     pub/tex/tex-styles-and-macros.txt.
;;;
;;;     Copies can also be obtained from the following locations:
;;;
;;;        ftp.tex.ac.uk:pub/archive/help/tex-styles-and-macros.txt
;;;        ftp.th-darmstadt.de:
;;;                  pub/tex/documentation/tex-styles-and-macros.txt[.Z]
;;;        ftp.uni-stuttgart.de:/soft/tex/documentation/TeX-index
;;;        ftp.SHSU.edu:[fileserv.tex-index]tex.index
;;;        ymir.claremont.edu:[anonymous.tex.documentation]tex-index.txt
;;;
;;;        ftp.cs.ruu.nl:pub/TEX/DOC/TeX-index.Z
;;;        ftp.math.utah.edu:pub/tex/tex-index
;;;        ftp.diku.dk:pub/TeX/misc/TeX-Index.Z
;;;
;;;
;;;     The checksum field above was produced by
;;;     Robert Solovay's checksum utility.",
;;;  }
;;; ====================================================================

;;; tex-macro-catalogue.el
;;; ;;;;;;;;;;;;;;;;;;;;;;

;;; This is an attempt at an emacs interface to the TeX macro catalogue
;;; produced by David Jones <dmjones@theory.lcs.mit.edu>

;;; INSTALLATION
;;;
;;; First obtain the catalogue and install it in a suitable directory.
;;; Then modify the setting of tmc-file below to refer to the path
;;; name of the catalogue file.
;;; This file may then be installed in an emacs-lisp directory, and
;;; byte compiled.


;;; BASIC USE
;;;
;;; Add the following lines (without the `;;;') to your .emacs. The
;;; catalogue may then be searched with M-x tex-macro-catalogue
;;;
;;; (autoload 'tex-macro-catalogue "tex-macro-catalogue"
;;;                                  "TeX macro catalogue browser" t)
;;;
;;; The browser will start by displaying a help screen, this screen
;;; may be recalled later by typing `?'.


;;; CUSTOMISATION & OTHER DETAILS
;;;
;;; The hook tmc-mode-hook may be set in your .emacs file, to
;;; customise the catalogue searching.
;;;
;;; You may wish to change the keybindings, or modify the list
;;; tmc-latex-sections of sections that you consider latex-related.
;;; (eg to add LAMSTeX, or remove FOILTeX.)
;;;
;;; The entries are returned with only the titles displayed.
;;; The bodies are hidden by outline mode. Typing `s' by a title shows
;;; the corresponding body. `S' shows all the returned entries.
;;; Hiding entries is done with `h' (one entry) or `H' all entries.
;;;
;;; Typing `?' displays a help screen, as long as you do not abort
;;; this with ^g, the previous contents of the tmc-entries buffer will
;;; be redisplayed at the next keypress.
;;;
;;; The first time you restrict the search to LaTeX `L', there will be
;;; a slight delay, as the positions of the LaTeX-related sections are
;;; determined. After the first time `L' and `A' should quickly switch
;;; between LaTeX-specific and unrestricted searching.
;;;
;;; If you usually require LaTeX-restricted searching, you could cause
;;; the browser to start off in that mode by placing a hook such as
;;; the following (without the ;;;) in your .emacs file.
;;;
;;; (setq tmc-mode-hook
;;;  (function
;;;   (lambda ()
;;;     (tmc-latex-only))))


;;; David Carlisle <carlisle@cs.man.ac.uk>
;;;
;;; Version 1:    May      1992
;;; Version 2: 15 February 1993

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


(defconst tmc-file
  "/usr/common/lib/tex3/doc/tex-styles-and-macros.txt"
  "The path name for the catalogue file.
   MUST BE SET CORRECTLY FOR YOUR SITE.")

(defvar tmc-latex-sections
  (list "AMS-LATEX" "FOILTEX" "LATEX"  "SLITEX" "GENERIC MACROS")
  "The LaTeX-related sections of the catalogue.")

(defvar tmc-file-buffer nil
  "Buffer to store the catalogue.")

(defvar tmc-ranges nil
  "The current list of ranges to search.")

(defvar tmc-latex-ranges nil
  "The list of ranges corresponding to tmc-latex-sections.")

(defun tmc-all-formats ()
 "Search the whole file, not just LaTeX-related sections."
 (interactive)
 (if (string= (buffer-name) "tmc-entries")
   (progn
     (setq mode-name "Macro Catalogue Entries")
;; Force an update to the modeline.
     (set-buffer-modified-p (buffer-modified-p))))
    (set-buffer tmc-file-buffer)
;; Set the range list to be one range, the whole file.
    (setq tmc-ranges (list (cons (point-min) (point-max)))))

(defun tmc-latex-only ()
 "Search the whole file, not just LaTeX-related sections."
 (interactive)
 (if (string= (buffer-name) "tmc-entries")
   (progn
     (setq mode-name "Macro Catalogue Entries (LaTeX only)")
;; Force an update to the modeline.
     (set-buffer-modified-p (buffer-modified-p))))
    (set-buffer tmc-file-buffer)
;; If we have not already computed the ranges coresponding to the
;; section titles, compute them now.
    (setq tmc-ranges
      (or
        tmc-latex-ranges
       (prog2
         (message "Locating LaTeX sections...")
         (setq tmc-latex-ranges
         (mapcar 'tmc-find-section tmc-latex-sections))
         (message "done")))))


(defun tmc-find-section (secname)
 "Return a cons-pair containing the markers corresponding to the start
 and finish of the requested section"
 (goto-char (point-min))
;; Section titles have a blank line before and after. (To distinguish
;; them from the list of sections at the beginning.)
 (re-search-forward
       (concat "\n\\s-*\n%%Section [0-9]+: " secname " *$\n\\s-*\n"))
 (cons (point)
  (progn (re-search-forward "\n%%Section [0-9]+:" (point-max) 1)
         (point))))

(defun tmc-list-search-section (range)
 "Search for an entry within the specified range."
 (set-buffer (get-buffer-create "tmc-entries"))
 (set-buffer tmc-file-buffer)
 (goto-char (car range))
 (while (re-search-forward
         (concat "^"key-type": .*\\b"key"\\b") (cdr range) t)
    (save-excursion (tmc-get-entry)))
 (switch-to-buffer "tmc-entries")
 (hide-body)
 (goto-char (point-min))
 (forward-line 1))

(defun tmc-list-search (key-type key)
 "Search for the entry in every range in the list tmc-ranges."
 (message "Searching...")
 (mapcar 'tmc-list-search-section tmc-ranges)
 (message "done"))

(defun tmc-list-by-author (auth)
 "Search for entries by author."
 (interactive "sAuthor Name: ")
 (tmc-list-search "Author" auth))

(defun tmc-list-by-keyword (key)
 "Search for entries by keyword."
 (interactive "sKeyword: ")
 (tmc-list-search "Keywords" key))

(defun tmc-list-by-title (name)
 "Search for entries by title (= name)."
 (interactive "sTitle: ")
 (tmc-list-search "Name" name))

(defun tmc-get-entry ()
 "Insert the found entry into the tmc-entries buffer."
 (re-search-backward "^[ ]*$")
   (let ((tmc-entry
         (buffer-substring (point)
            (progn
             (forward-line 1)(re-search-forward "^[ ]*$") (point)))))
     (set-buffer "tmc-entries")
     (goto-char (point-max))
     (insert tmc-entry)))

(defvar tmc-map (make-sparse-keymap)
  "Local keymap used in TeX macro catalogue entries buffer.")


(defun tex-macro-catalogue ()
 "Initialise a buffer to control searching the TeX macro catalogue.
  The available commands are:
\\{tmc-map}"
 (interactive)
;; Load the file if not already loaded,
;; without evaluating any hooks or local variables
 (if tmc-file-buffer
   (set-buffer tmc-file-buffer)
;;else
   (setq tmc-file-buffer (create-file-buffer tmc-file))
   (set-buffer tmc-file-buffer)
   (insert-file-contents tmc-file))
 (setq buffer-read-only t)
 (switch-to-buffer (get-buffer-create "tmc-entries"))
;; Use outline mode to hide the entry bodies.
 (outline-mode)
 (make-local-variable 'outline-regexp)
 (setq outline-regexp "Name")
 (setq major-mode 'tex-macro-catalogue)
 (tmc-all-formats)
 (switch-to-buffer (get-buffer-create "tmc-entries"))
 (use-local-map tmc-map)
;; Individual customisations.
 (run-hooks 'tmc-mode-hook)
;; Start off with the help screen.
 (tmc-help))

(defvar tmc-help nil "The help string")

(defun tmc-help ()
 "Help for TeX macro catalogue searches."
 (interactive)
 (switch-to-buffer (get-buffer-create "tmc-entries"))
;; The help string is displayed until the next key sequence.
;; The previous contents of the buffer are then returned, unless the
;; help is quit with \C-g.
 (let ((p (point))
       (tmc-temp (buffer-string)))
 (erase-buffer)
;; Only initialise the help string now in case the user has changed
;; the key bindings in tmc-mode-hook.
 (insert (or tmc-help
 tmc-help
 (setq tmc-help (substitute-command-keys
"TeX Macro Catalogue

Before Searching, type:

       `\\[tmc-latex-only]' \
Restrict search to LaTeX and related formats.
       `\\[tmc-all-formats]' \
Allow searching over the whole catalogue. (Default.)

To search, type:
       `\\[tmc-list-by-keyword]' \
to search the catalogue by Keyword.
       `\\[tmc-list-by-author]' \
to search the catalogue by Author.
       `\\[tmc-list-by-title]' \
to search the catalogue by Title (name) of package.

After a successful search, type:
       `\\[outline-next-visible-heading]' \
`\\[outline-previous-visible-heading]' \
Move to next (previous) entry.

       `\\[show-subtree]' `\\[show-all]' \
Show current entry (All entries).
       `\\[hide-subtree]' `\\[hide-body]' \
Hide current entry (All entries).

       `\\[tmc-clear]' Clear this buffer.
       `\\[tmc-quit]' Quit.

       `\\[tmc-help]' Get this help
  "))))
 (goto-char (point-min))
 (sit-for 60)
 (erase-buffer)
 (insert tmc-temp)
 (goto-char p)))


(defun tmc-clear ()
  "Clear the tmc-entries buffer."
  (interactive)
  (set-buffer "tmc-entries")
  (erase-buffer))

(defun tmc-quit ()
  "Quit searching the catalogue."
  (interactive)
  (tmc-clear)
  (bury-buffer tmc-file-buffer)
  (let ((obuf (current-buffer)))
    (switch-to-buffer (other-buffer))
    (bury-buffer obuf)))


;; Set up the default key bindings.
(define-key tmc-map "S"    'show-all)
(define-key tmc-map "H"    'hide-body)
(define-key tmc-map "s"    'show-subtree)
(define-key tmc-map "h"    'hide-subtree)
(define-key tmc-map "n"    'outline-next-visible-heading)
(define-key tmc-map "p"    'outline-previous-visible-heading)

(define-key tmc-map "k"    'tmc-list-by-keyword)
(define-key tmc-map "a"    'tmc-list-by-author)
(define-key tmc-map "t"    'tmc-list-by-title)

(define-key tmc-map "c"    'tmc-clear)
(define-key tmc-map "q"    'tmc-quit)

(define-key tmc-map "L"    'tmc-latex-only)
(define-key tmc-map "A"    'tmc-all-formats)

(define-key tmc-map "?"    'tmc-help)


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;