summaryrefslogtreecommitdiff
path: root/info/latex2e-help-texinfo/ltx-help.el
blob: 0b48d680e1b6cdf699bc001c8403ef1e5324433f (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
;;; ltx-help.el --- Lookup latex commands in info pages.

;; Authors: Peter Galbraith <rhogee@bathybius.meteo.mcgill.ca> or <galbrth@ac.dal.ca>
;;      Christian Lynbech <lynbech@daimi.aau.dk>
;;      Martin Sjolin <marsj@ida.liu.se>
;;      Boris Goldowsky <boris@cs.rochester.edu> 
;; Maintainer: as part of latexrefman, http://home.gna.org/latexrefman/
;; Updated: 25 April 2013
;; Keywords: help, latex, info


;;; Commentary:

;; Use the function latex-help to look up a latex command or
;; environment in the latex online manual.  If point is at such a
;; command, this will be the default.

;; The Texinfo document that this code works with is at
;; http://ctan.org/pkg/latex2e-help-texinfo.

;; Installation:
;;
;; Add the following piece of code to your .emacs
;;  (define-key help-map "\C-l" 'latex-help)
;;
;; to bind latex-help to C-h C-l. To load latex-help when loading AUC-TeX or
;; some other LaTeX/TeX mode and bind the it to C-C i key, add the the following
;; to you .emacs:
;;
;; (add-hook 'Latex-mode-hook 
;;           (function (lambda ()
;;                        (define-key LaTeX-mode-map "\C-ci" 'latex-help))))
;;
;; or if you do not have add-hook (a very nice package):
;;
;; (setq Latex-mode-hook 
;;      (function (lambda ()
;;                  (define-key LaTeX-mode-map "\C-ci" 'latex-help))))
;;
;;

;;; Change Log:

;;Mar  4, 1994 <lynbech@daimi.aau.dk>:
;;    Changed to my personal preferences.  I have changed the function
;;    names.  I have changed it to take a parameter, rather than just
;;    taking the current word. I am also basing it on the index rather
;;    than the node names.
;;
;;Mar 10, 1994 <marsj@ida.liu.se>:
;;    Added definition of current-word if not present.
;;    Made default value pick up a leading \ if apropriate
;;
;;Mar 11, 1994 <lynbech@daimi.aau.dk>:
;;    Changed the name of current-word into latex-help-guess. This
;;    eliminates the need for the embedded defun.
;;    Also made describe-latex work more like describe-function in its
;;    way of using default values. Now you must press return at an
;;    empty prompt to get the listed default (if any).
;;
;;Mar 10, 1994 <marsj@ida.liu.se>:
;;    Rewrote part of the describe-latex command to use the prefix
;;    argument, changed latex-help-get-cmd-obarray to return the
;;    the new array and test if it is empty or not. Add information
;;    concerning where to find the latex.texi file and emacs 18 info.el
;;  
;;Mar 28, 1994 <boris@cs.rochester.edu>:
;;    * rewrote describe-latex's command-reading code; it did not
;;      default correctly on my system.
;;    * Added latex-help-hist, for completion history.
;;    * Modified it to use show-temp-buffer, if defined, so that it will
;;      display the help buffer in accord with user preferences.
;;    * Renamed describe-latex to latex-help, for consistency with other names.
;;    * Removed unneeded (interactive) specs for latex-help-guess and
;;      latex-help-get-cmd-obarray. 
;;    * Added autoload cookies.
;;    * Doc fix.
;;
;;Mar 29, 1994 <marsj@ida.liu.se>:
;;    * made it working under epoch/emacs-18 by calling
;;      completion-read without the last argument.
;;    * made prompting similar to emacs help
;;    * moved add-hook and define keys to installation section, since
;;      the settings conflict with my own keybindings. Also, the key
;;      binding should be chosen by the end user.
;;
;; Wed Mar 30 08:45:50 1994     LYNBECH
;;      * Changed file layout to conform to FSF's standards
;;      * Tweaked latex-help-guess to include any leading backslashes
;;      * Inversed the meaning of the prefix argument. Now default is
;;        to switch buffers. Also added new variable `latex-help-split-window'
;;        to allow window splitting always.
;;      * Minor doc fixes
;;
;; Wed Apr  6 08:34:08 1994     LYNBECH
;;      * fixed latex-help-guess to be more faithful to the lexical rules
;;        of  TeX. The result is not especially elegant.
;;
;;Apr 16, 1994 <abraham@iesd.auc.dk>:
;;    Changed the name to `ltx-help.el'.
;;
;; Sat Apr  1 1995  Torsten Martinsen  (torsten@kom.auc.dk)
;;    Changed obarray to an alist where the car of each cons cell is the
;;    command name, and the cdr is the Info node describing that
;;    command. This implementation has the following advantages:
;;     - we don't need to have a lot of small redundant Info nodes; instead,
;;       we can use the Texinfo function index mechanism.
;;     - the alist is dynamically sized, so this version will work regardless
;;       of how many LaTeX commands the Info file contains.
;;    Added info on LaTeX2e Info file.
;;
;; Mon Apr 15 1996  Torsten Martinsen (bullestock@dk-online.dk)
;;    Changed node 'List of Commands' to 'Command Index' as suggested by 
;;    Ralf Fassel <ralf@natlab.research.philips.com>.
;;
;; Mon Apr 22 1996  Torsten Martinsen (bullestock@dk-online.dk)
;;    When running under FSF Emacs, use (buffer-substring-no-properties)
;;    instead of (buffer-substring) as suggested by Kurt Hornik
;;    <hornik@ci.tuwien.ac.at>. Also removed Emacs 18 support.
;;
;; Thu Jun 12 2008  Karl Berry (karl@freefriends.org)
;;    Change latex-help-file to "(latex2e)", so our names are consistent.
;;    Doc updates.
;;
;; Thu Apr 25 2013  Karl Berry (karl@freefriends.org)
;;    Doc updates, and install these changes:
;;
;; Thu Apr 25 2013  Mandar Mitra (mandar.mitra@gmail.com)
;;    Using with (for example) "array" goes to the top node
;;    of latex2e.info instead of the intended node.
;;
;; Thu Dec 3 2015  Kevin Ryde (user42_kevin@yahoo.com.au)
;;    * latex-help-get-cmd-alist don't take \:: as double-colon style index,
;;      and allow "(line 123)" at the end of recent makeinfo output.
;;    * Use buffer-substring-no-properties when exists (does in XEmacs 21.4).

;;; Code:

(require 'info)

(defalias 'ltxh-buffer-substring
  (if (fboundp 'buffer-substring-no-properties)  ;; when available
      'buffer-substring-no-properties
    'buffer-substring))

(defcustom latex-help-file "(latex2e)"
  "Select the LaTeX2e non official reference manual translation."
  :type '(choice
	  (string :tag "English" "(latex2e)")
	  (string :tag "French" "(latex2e-fr)")
	  (string :tag "Spanish" "(latex2e-es)") ))

(defvar latex-help-split-window nil
  "*When this is non-nil, `latex-help' will always pop up the info
buffer, rather than just switch to it.")

(defvar latex-help-hist nil
  "History for latex command help")

(defconst latex-help-cmd-alist nil
  "Alist of the commands in the index of the latex info manual,
used for validation and completion.")

;;;###autoload
(defun latex-help (cmd split)
  "Try to find info entry about LaTeX entity CMD.
CMD may be either a command or an environment.
If CMD is not a string, this function will prompt for it, eventually
with completion. If SPLIT (prefix arg.) is non-nil, latex-help will
pop up the Info buffer, rather than just switch to it. See also
variable `latex-help-split-window'."
  (interactive 
   (list
    (let* ((cw (latex-help-guess))
           (cww (concat "\\" cw))
           (cmd-alist (latex-help-get-cmd-alist))
           (node (try-completion cw cmd-alist))
           ; try-completion returns actual string in case of partial match
           ; but returns t in case of exact match
           (nodename1 (if (equal node t) cw node))
           (nodename2 (if (equal nodename1 nil)
                          (try-completion cww cmd-alist) nodename1))
          (guess (cond ((equal nodename2 t) cww)
                        ((equal nodename2 nil) nil)
                        (t nodename2)))
           (val (completing-read (if guess 
                                     (format "Describe LaTeX command (default %s): " guess)
                                   "Describe LaTeX command: ")
                                 cmd-alist nil t nil
                                 'latex-help-hist)))
      (cdr (assoc (if (equal val "")
                      guess
                    val) cmd-alist)))
    current-prefix-arg))
  (if (not (or split latex-help-split-window))
      (Info-goto-node (concat latex-help-file cmd))
    (save-excursion
      (let ((pop-up-windows t)
            (buffer (current-buffer)))
        (pop-to-buffer nil)
        (Info-goto-node (concat latex-help-file cmd))
        (if (fboundp 'show-temp-buffer)
            (show-temp-buffer (current-buffer) t)
          (pop-to-buffer buffer))))))
    
(defun latex-help-guess ()
  "Return the word point is on as a string, if it's between two
word-constituent characters. If not, but it immediately follows one,
move back first.  Otherwise, if point precedes a word constituent,
move forward first.  Otherwise, move backwards until a word constituent
is found and get that word; if you reach a newline first, move forward
instead.

This function has been tweaked to deal better with latex commands.

Return the LaTeX command point is on as a string.
"
  ;; cl: I am not claiming this to be neither elegant nor fast.
  (save-excursion
    (let ((oldpoint (point)) (start (point)) (end (point))
          (wc "A-Za-z") (nwc "^A-Za-z"))

      (cond
       ((looking-at "\\\\[^A-Za-z]")
        (setq start (point)
              end (+ 2 (point))))
       
       ((looking-at "\\\\[A-Za-z]+")
        (setq start (match-beginning 0)
              end (match-end 0)))

       (t
        (skip-chars-backward wc)
        (skip-chars-backward "\\\\" (1- (point)))
        (setq start (point))

        (goto-char oldpoint)

        (skip-chars-forward "\\\\" (1+ (point)))
        (skip-chars-forward wc)
        (setq end (point))

        (if (and (eq start oldpoint) (eq end oldpoint))
            (progn
              (skip-chars-backward nwc
                                   (save-excursion (beginning-of-line) (point)))
              (if (eq (preceding-char) ?\n)
                  (progn
                    (skip-chars-forward nwc)
                    (setq start (point))
                    (skip-chars-forward "\\\\" (1+ (point)))
                    (skip-chars-forward wc)
                    (setq end (point)))
                (setq end (point))
                (skip-chars-backward wc)
                (skip-chars-backward "\\\\" (1- (point)))
                (setq start (point)))))
        )
       )
      (ltxh-buffer-substring start end)))
  )

(defun latex-help-get-cmd-alist ()
  "Scoop up the commands in the index of the latex info manual.
The values are saved in `latex-help-cmd-alist' for speed."
  ;; mm, does it contain any cached entries
  (if (not (assoc "\\begin" latex-help-cmd-alist))
      (save-window-excursion
        (setq latex-help-cmd-alist nil)
        (Info-goto-node (concat latex-help-file "Command Index"))
        (if (re-search-forward "::$" nil t)
            (progn
              (end-of-buffer)
              (while (re-search-backward "^\\* \\(.+\\)::$" nil t)
                (setq key (ltxh-buffer-substring (match-beginning 1) (match-end 1)))
                (setq latex-help-cmd-alist 
                      (cons (cons key key) latex-help-cmd-alist))))
          (end-of-buffer)
          (while (re-search-backward "^\\* \\(.+\\): *\\(.+\\)\\." nil t)
            (setq key (ltxh-buffer-substring (match-beginning 1) (match-end 1)))
            (setq value (ltxh-buffer-substring (match-beginning 2) (match-end 2)))
            (setq latex-help-cmd-alist 
                  (cons (cons key value) latex-help-cmd-alist))))
        ))
  ;; and return the alist.
  latex-help-cmd-alist
  )

(provide 'ltx-help)

;;; ltx-help.el ends here