Merge from emacs-24; up to r116973
[emacs.git] / lisp / textmodes / texinfo.el
1 ;;; texinfo.el --- major mode for editing Texinfo files -*- coding: utf-8 -*-
2
3 ;; Copyright (C) 1985, 1988-1993, 1996-1997, 2000-2014 Free Software
4 ;; Foundation, Inc.
5
6 ;; Author: Robert J. Chassell
7 ;; Date:   [See date below for texinfo-version]
8 ;; Maintainer: emacs-devel@gnu.org
9 ;; Keywords: maint, tex, docs
10
11 ;; This file is part of GNU Emacs.
12
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
17
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 ;; GNU General Public License for more details.
22
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
25
26 ;;; Todo:
27
28 ;; - facemenu support.
29 ;; - command completion.
30
31 ;;; Commentary:
32
33 ;;; Code:
34
35 (eval-when-compile (require 'tex-mode))
36 (declare-function tex-buffer "tex-mode" ())
37 (declare-function tex-region "tex-mode" (beg end))
38 (declare-function tex-send-command "tex-mode")
39 (declare-function tex-recenter-output-buffer "tex-mode" (linenum))
40 (declare-function tex-print "tex-mode" (&optional alt))
41 (declare-function tex-view "tex-mode" ())
42 (declare-function tex-shell-running "tex-mode" ())
43 (declare-function tex-kill-job "tex-mode" ())
44
45 (defvar outline-heading-alist)
46
47 (defgroup texinfo nil
48   "Texinfo Mode."
49   :link '(custom-group-link :tag "Font Lock Faces group" font-lock-faces)
50   :group 'docs)
51
52 ;;;###autoload
53 (defcustom texinfo-open-quote (purecopy "``")
54   "String inserted by typing \\[texinfo-insert-quote] to open a quotation."
55   :type 'string
56   :group 'texinfo)
57
58 ;;;###autoload
59 (defcustom texinfo-close-quote (purecopy "''")
60   "String inserted by typing \\[texinfo-insert-quote] to close a quotation."
61   :type 'string
62   :group 'texinfo)
63
64 (defcustom texinfo-mode-hook nil
65   "Normal hook run when entering Texinfo mode."
66   :type 'hook
67   :options '(turn-on-auto-fill flyspell-mode)
68   :group 'texinfo)
69
70 \f
71 ;;; Autoloads:
72
73 (autoload 'makeinfo-region
74   "makeinfo"
75   "Make Info file from region of current Texinfo file, and switch to it.
76
77 This command does not offer the `next-error' feature since it would
78 apply to a temporary file, not the original; use the `makeinfo-buffer'
79 command to gain use of `next-error'."
80   t nil)
81
82 (autoload 'makeinfo-buffer
83   "makeinfo"
84   "Make Info file from current buffer.
85
86 Use the \\[next-error] command to move to the next error
87 \(if there are errors\)."
88   t nil)
89
90 (autoload 'kill-compilation
91   "compile"
92   "Kill the process made by the \\[compile] command."
93   t nil)
94
95 (autoload 'makeinfo-recenter-compilation-buffer
96   "makeinfo"
97   "Redisplay `*compilation*' buffer so most recent output can be seen.
98 The last line of the buffer is displayed on
99 line LINE of the window, or centered if LINE is nil."
100   t nil)
101
102 (autoload 'texinfo-update-node
103   "texnfo-upd"
104   "Without any prefix argument, update the node in which point is located.
105 Non-nil argument (prefix, if interactive) means update the nodes in the
106 marked region.
107
108 The functions for creating or updating nodes and menus, and their
109 keybindings, are:
110
111     `texinfo-update-node' (&optional region-p)    \\[texinfo-update-node]
112     `texinfo-every-node-update' ()                \\[texinfo-every-node-update]
113     `texinfo-sequential-node-update' (&optional region-p)
114
115     `texinfo-make-menu' (&optional region-p)      \\[texinfo-make-menu]
116     `texinfo-all-menus-update' ()                 \\[texinfo-all-menus-update]
117     `texinfo-master-menu' ()
118
119     `texinfo-indent-menu-description' (column &optional region-p)
120
121 The `texinfo-column-for-description' variable specifies the column to
122 which menu descriptions are indented. Its default value is 32."
123   t nil)
124
125 (autoload 'texinfo-every-node-update
126   "texnfo-upd"
127   "Update every node in a Texinfo file."
128   t nil)
129
130 (autoload 'texinfo-sequential-node-update
131   "texnfo-upd"
132   "Update one node (or many) in a Texinfo file with sequential pointers.
133
134 This function causes the `Next' or `Previous' pointer to point to the
135 immediately preceding or following node, even if it is at a higher or
136 lower hierarchical level in the document.  Continually pressing `n' or
137 `p' takes you straight through the file.
138
139 Without any prefix argument, update the node in which point is located.
140 Non-nil argument (prefix, if interactive) means update the nodes in the
141 marked region.
142
143 This command makes it awkward to navigate among sections and
144 subsections; it should be used only for those documents that are meant
145 to be read like a novel rather than a reference, and for which the
146 Info `g*' command is inadequate."
147   t nil)
148
149 (autoload 'texinfo-make-menu
150   "texnfo-upd"
151   "Without any prefix argument, make or update a menu.
152 Make the menu for the section enclosing the node found following point.
153
154 Non-nil argument (prefix, if interactive) means make or update menus
155 for nodes within or part of the marked region.
156
157 Whenever a menu exists, and is being updated, the descriptions that
158 are associated with node names in the pre-existing menu are
159 incorporated into the new menu.  Otherwise, the nodes' section titles
160 are inserted as descriptions."
161   t nil)
162
163 (autoload 'texinfo-all-menus-update
164   "texnfo-upd"
165   "Update every regular menu in a Texinfo file.
166 Remove pre-existing master menu, if there is one.
167
168 If called with a non-nil argument, this function first updates all the
169 nodes in the buffer before updating the menus."
170   t nil)
171
172 (autoload 'texinfo-master-menu
173   "texnfo-upd"
174   "Make a master menu for a whole Texinfo file.
175 Non-nil argument (prefix, if interactive) means first update all
176 existing nodes and menus.  Remove pre-existing master menu, if there is one.
177
178 This function creates a master menu that follows the top node.  The
179 master menu includes every entry from all the other menus.  It
180 replaces any existing ordinary menu that follows the top node.
181
182 If called with a non-nil argument, this function first updates all the
183 menus in the buffer (incorporating descriptions from pre-existing
184 menus) before it constructs the master menu.
185
186 The function removes the detailed part of an already existing master
187 menu.  This action depends on the pre-existing master menu using the
188 standard `texinfo-master-menu-header'.
189
190 The master menu has the following format, which is adapted from the
191 recommendation in the Texinfo Manual:
192
193    * The first part contains the major nodes in the Texinfo file: the
194      nodes for the chapters, chapter-like sections, and the major
195      appendices.  This includes the indices, so long as they are in
196      chapter-like sections, such as unnumbered sections.
197
198    * The second and subsequent parts contain a listing of the other,
199      lower level menus, in order.  This way, an inquirer can go
200      directly to a particular node if he or she is searching for
201      specific information.
202
203 Each of the menus in the detailed node listing is introduced by the
204 title of the section containing the menu."
205   t nil)
206
207 (autoload 'texinfo-indent-menu-description
208   "texnfo-upd"
209   "Indent every description in menu following point to COLUMN.
210 Non-nil argument (prefix, if interactive) means indent every
211 description in every menu in the region.  Does not indent second and
212 subsequent lines of a multi-line description."
213   t nil)
214
215 (autoload 'texinfo-insert-node-lines
216   "texnfo-upd"
217   "Insert missing `@node' lines in region of Texinfo file.
218 Non-nil argument (prefix, if interactive) means also to insert the
219 section titles as node names; and also to insert the section titles as
220 node names in pre-existing @node lines that lack names."
221   t nil)
222
223 (autoload 'texinfo-start-menu-description
224   "texnfo-upd"
225   "In this menu entry, insert the node's section title as a description.
226 Position point at beginning of description ready for editing.
227 Do not insert a title if the line contains an existing description.
228
229 You will need to edit the inserted text since a useful description
230 complements the node name rather than repeats it as a title does."
231   t nil)
232
233 (autoload 'texinfo-multiple-files-update
234   "texnfo-upd"
235   "Update first node pointers in each file included in OUTER-FILE;
236 create or update main menu in the outer file that refers to such nodes.
237 This does not create or update menus or pointers within the included files.
238
239 With optional MAKE-MASTER-MENU argument (prefix arg, if interactive),
240 insert a master menu in OUTER-FILE.  This does not create or update
241 menus or pointers within the included files.
242
243 With optional UPDATE-EVERYTHING argument (numeric prefix arg, if
244 interactive), update all the menus and all the `Next', `Previous', and
245 `Up' pointers of all the files included in OUTER-FILE before inserting
246 a master menu in OUTER-FILE.
247
248 The command also updates the `Top' level node pointers of OUTER-FILE.
249
250 Notes:
251
252   * this command does NOT save any files--you must save the
253     outer file and any modified, included files.
254
255   * except for the `Top' node, this command does NOT handle any
256     pre-existing nodes in the outer file; hence, indices must be
257     enclosed in an included file.
258
259 Requirements:
260
261   * each of the included files must contain exactly one highest
262     hierarchical level node,
263   * this highest node must be the first node in the included file,
264   * each highest hierarchical level node must be of the same type.
265
266 Thus, normally, each included file contains one, and only one,
267 chapter."
268   t nil)
269
270 \f
271 ;;; Code:
272
273 ;;; Don't you dare insert any `require' calls at top level in this file--rms.
274
275 (defvar texinfo-section-list
276   '(("top" 1)
277     ("chapter" 2)
278     ("section" 3)
279     ("subsection" 4)
280     ("subsubsection" 5)
281     ("unnumbered" 2)
282     ("unnumberedsec" 3)
283     ("unnumberedsubsec" 4)
284     ("unnumberedsubsubsec" 5)
285     ("appendix" 2)
286     ("appendixsec" 3)
287     ("appendixsection" 3)
288     ("appendixsubsec" 4)
289     ("appendixsubsubsec" 5)
290     ("majorheading" 2)
291     ("chapheading" 2)
292     ("heading" 3)
293     ("subheading" 4)
294     ("subsubheading" 5))
295   "Alist of sectioning commands and their relative level.")
296
297 ;;; Syntax table
298
299 (defvar texinfo-mode-syntax-table
300   (let ((st (make-syntax-table)))
301     (modify-syntax-entry ?\" "." st)
302     (modify-syntax-entry ?\\ "." st)
303     (modify-syntax-entry ?@ "\\" st)
304     (modify-syntax-entry ?\^q "\\" st)
305     (modify-syntax-entry ?\[ "(]" st)
306     (modify-syntax-entry ?\] ")[" st)
307     (modify-syntax-entry ?{ "(}" st)
308     (modify-syntax-entry ?} "){" st)
309     (modify-syntax-entry ?\n ">" st)
310     (modify-syntax-entry ?\' "w" st)
311     st))
312
313 ;; Written by Wolfgang Bangerth <zcg51122@rpool1.rus.uni-stuttgart.de>
314 ;; To override this example, set either `imenu-generic-expression'
315 ;; or `imenu-create-index-function'.
316 (defvar texinfo-imenu-generic-expression
317   '((nil "^@\\(node\\|anchor\\)[ \t]+\\([^,\n]*\\)" 2)
318     ("Chapters" "^@chapter[ \t]+\\(.*\\)$" 1))
319   "Imenu generic expression for Texinfo mode.  See `imenu-generic-expression'.")
320
321 (defconst texinfo-syntax-propertize-function
322   (syntax-propertize-rules
323    ("\\(@\\)c\\(omment\\)?\\>" (1 "<"))
324    ("^\\(@\\)ignore\\>" (1 "< b"))
325    ("^@end ignore\\(\n\\)" (1 "> b")))
326   "Syntactic keywords to catch comment delimiters in `texinfo-mode'.")
327
328 (defconst texinfo-environments
329   '("cartouche" "copying" "defcv" "deffn" "defivar" "defmac"
330     "defmethod" "defop" "defopt" "defspec" "deftp" "deftypecv"
331     "deftypefn" "deftypefun" "deftypeivar" "deftypemethod"
332     "deftypeop" "deftypevar" "deftypevr" "defun" "defvar"
333     "defvr" "description" "detailmenu" "direntry" "display"
334     "documentdescription" "enumerate" "example" "flushleft"
335     "flushright" "format" "ftable" "group" "html" "ifclear" "ifset"
336     "ifhtml" "ifinfo" "ifnothtml" "ifnotinfo" "ifnotplaintext"
337     "ifnottex" "ifplaintext" "iftex" "ignore" "itemize" "lisp"
338     "macro" "menu" "multitable" "quotation" "smalldisplay"
339     "smallexample" "smallformat" "smalllisp" "table" "tex"
340     "titlepage" "verbatim" "vtable")
341   "List of Texinfo environments.")
342
343 (defconst texinfo-environment-regexp
344   (concat "^@" (regexp-opt (cons "end" texinfo-environments) t) "\\>")
345   "Regexp for environment-like Texinfo list commands.
346 Subexpression 1 is what goes into the corresponding `@end' statement.")
347
348 (defface texinfo-heading
349   '((t (:inherit font-lock-function-name-face)))
350   "Face used for section headings in `texinfo-mode'."
351   :group 'texinfo)
352 (define-obsolete-face-alias 'texinfo-heading-face 'texinfo-heading "22.1")
353 (defvar texinfo-heading-face 'texinfo-heading)
354
355 (defvar texinfo-font-lock-keywords
356   `(;; All but the first had an OVERRIDE of t.
357     ;; It didn't seem to be any better, and it's slower--simon.
358     ;; Robert J. Chassell <bob@gnu.org> says remove this line.
359     ;;("\\$\\([^$]*\\)\\$" 1 font-lock-string-face t)
360     ("@\\([a-zA-Z]+\\|[^ \t\n]\\)" 1 font-lock-keyword-face) ;commands
361     ("^\\*\\([^\n:]*\\)" 1 font-lock-function-name-face t) ;menu items
362     ("@\\(emph\\|i\\|sc\\){\\([^}]+\\)" 2 'italic)
363     ("@\\(strong\\|b\\){\\([^}]+\\)" 2 'bold)
364     ("@\\(kbd\\|key\\|url\\|uref\\){\\([^}]+\\)" 2 font-lock-string-face)
365     ;; The following two groups have an OVERRIDE of `keep' because
366     ;; their arguments frequently include a @@, and we don't want that
367     ;; to overwrite the normal fontification of the argument.
368     ("@\\(file\\|email\\){\\([^}]+\\)" 2 font-lock-string-face keep)
369     ("@\\(samp\\|code\\|var\\|math\\|env\\|command\\|option\\){\\([^}]+\\)"
370      2 font-lock-variable-name-face keep)
371     ("@\\(cite\\|x?ref\\|pxref\\|dfn\\|inforef\\){\\([^}]+\\)"
372      2 font-lock-constant-face)
373     ("@\\(anchor\\){\\([^}]+\\)" 2 font-lock-type-face)
374     ("@\\(dmn\\|acronym\\|value\\){\\([^}]+\\)" 2 font-lock-builtin-face)
375     ("@\\(end\\|itemx?\\) +\\(.+\\)" 2 font-lock-keyword-face keep)
376     ;; (,texinfo-environment-regexp
377     ;;  1 (texinfo-clone-environment (match-beginning 1) (match-end 1)) keep)
378     (,(concat "^@" (regexp-opt (mapcar 'car texinfo-section-list) t)
379                ".*\n") 0 texinfo-heading-face t))
380   "Additional expressions to highlight in Texinfo mode.")
381
382 (defun texinfo-clone-environment (start end)
383   (let ((endp nil))
384     (save-excursion
385       (ignore-errors
386         (goto-char start)
387         (when (looking-at "end\\Sw+\\(\\sw+\\)")
388           (setq endp t start (match-beginning 1) end (match-end 1)))
389         (unless (get-char-property start 'text-clones)
390           (if endp
391               (texinfo-last-unended-begin)
392             (forward-word 1)
393             (texinfo-next-unmatched-end))
394           (skip-syntax-forward "^w")
395           (when (looking-at
396                  (concat (regexp-quote (buffer-substring start end)) "\\>"))
397             (text-clone-create start end 'spread "\\w*")))))))
398
399 \f
400 ;;; Keybindings
401
402 ;;; Keys common both to Texinfo mode and to TeX shell.
403
404 (defun texinfo-define-common-keys (keymap)
405   "Define the keys both in Texinfo mode and in the texinfo-tex-shell."
406   (define-key keymap "\C-c\C-t\C-k"    'tex-kill-job)
407   (define-key keymap "\C-c\C-t\C-x"    'texinfo-quit-job)
408   (define-key keymap "\C-c\C-t\C-l"    'tex-recenter-output-buffer)
409   (define-key keymap "\C-c\C-t\C-d"    'texinfo-delete-from-print-queue)
410   (define-key keymap "\C-c\C-t\C-q"    'tex-show-print-queue)
411   (define-key keymap "\C-c\C-t\C-p"    'texinfo-tex-print)
412   (define-key keymap "\C-c\C-t\C-v"    'texinfo-tex-view)
413   (define-key keymap "\C-c\C-t\C-i"    'texinfo-texindex)
414
415   (define-key keymap "\C-c\C-t\C-r"    'texinfo-tex-region)
416   (define-key keymap "\C-c\C-t\C-b"    'texinfo-tex-buffer))
417
418 ;; Mode documentation displays commands in reverse order
419 ;; from how they are listed in the texinfo-mode-map.
420
421 (defvar texinfo-mode-map
422   (let ((map (make-sparse-keymap)))
423
424     ;; bindings for `texnfo-tex.el'
425     (texinfo-define-common-keys map)
426
427     (define-key map "\"" 'texinfo-insert-quote)
428
429     ;; bindings for `makeinfo.el'
430     (define-key map "\C-c\C-m\C-k" 'kill-compilation)
431     (define-key map "\C-c\C-m\C-l"
432       'makeinfo-recenter-compilation-buffer)
433     (define-key map "\C-c\C-m\C-r" 'makeinfo-region)
434     (define-key map "\C-c\C-m\C-b" 'makeinfo-buffer)
435
436     ;; bindings for `texinfmt.el'
437     (define-key map "\C-c\C-e\C-r"    'texinfo-format-region)
438     (define-key map "\C-c\C-e\C-b"    'texinfo-format-buffer)
439
440     ;; AUCTeX-like bindings
441     (define-key map "\e\r"              'texinfo-insert-@item)
442
443     ;; bindings for updating nodes and menus
444
445     (define-key map "\C-c\C-um"   'texinfo-master-menu)
446
447     (define-key map "\C-c\C-u\C-m"   'texinfo-make-menu)
448     (define-key map "\C-c\C-u\C-n"   'texinfo-update-node)
449     (define-key map "\C-c\C-u\C-e"   'texinfo-every-node-update)
450     (define-key map "\C-c\C-u\C-a"   'texinfo-all-menus-update)
451
452     (define-key map "\C-c\C-s"     'texinfo-show-structure)
453
454     (define-key map "\C-c}"          'up-list)
455     ;; FIXME: This is often used for "close block" aka texinfo-insert-@end.
456     (define-key map "\C-c]"          'up-list)
457     (define-key map "\C-c/"          'texinfo-insert-@end)
458     (define-key map "\C-c{"             'texinfo-insert-braces)
459
460     ;; bindings for inserting strings
461     (define-key map "\C-c\C-o"     'texinfo-insert-block)
462     (define-key map "\C-c\C-c\C-d" 'texinfo-start-menu-description)
463     (define-key map "\C-c\C-c\C-s" 'texinfo-insert-@strong)
464     (define-key map "\C-c\C-c\C-e" 'texinfo-insert-@emph)
465
466     (define-key map "\C-c\C-cv"    'texinfo-insert-@var)
467     (define-key map "\C-c\C-cu"    'texinfo-insert-@uref)
468     (define-key map "\C-c\C-ct"    'texinfo-insert-@table)
469     (define-key map "\C-c\C-cs"    'texinfo-insert-@samp)
470     (define-key map "\C-c\C-cq"    'texinfo-insert-@quotation)
471     (define-key map "\C-c\C-co"    'texinfo-insert-@noindent)
472     (define-key map "\C-c\C-cn"    'texinfo-insert-@node)
473     (define-key map "\C-c\C-cm"    'texinfo-insert-@email)
474     (define-key map "\C-c\C-ck"    'texinfo-insert-@kbd)
475     (define-key map "\C-c\C-ci"    'texinfo-insert-@item)
476     (define-key map "\C-c\C-cf"    'texinfo-insert-@file)
477     (define-key map "\C-c\C-cx"    'texinfo-insert-@example)
478     (define-key map "\C-c\C-ce"    'texinfo-insert-@end)
479     (define-key map "\C-c\C-cd"    'texinfo-insert-@dfn)
480     (define-key map "\C-c\C-cc"    'texinfo-insert-@code)
481     map))
482
483 (easy-menu-define texinfo-mode-menu
484   texinfo-mode-map
485   "Menu used for `texinfo-mode'."
486   '("Texinfo"
487     ["Insert block"     texinfo-insert-block    t]
488     ;; ["Insert node"   texinfo-insert-@node    t]
489     "----"
490     ["Update All"       (lambda () (interactive) (texinfo-master-menu t))
491      :keys "\\[universal-argument] \\[texinfo-master-menu]"]
492     ["Update every node" texinfo-every-node-update t]
493     ["Update node"      texinfo-update-node     t]
494     ["Make Master menu" texinfo-master-menu     t]
495     ["Make menu"        texinfo-make-menu       t]
496     ["Update all menus" texinfo-all-menus-update t]
497     "----"
498     ["Show structure"   texinfo-show-structure  t]
499     ["Format region"    texinfo-format-region   t]
500     ["Format buffer"    texinfo-format-buffer   t]
501     ["Makeinfo region"  makeinfo-region         t]
502     ["Makeinfo buffer"  makeinfo-buffer         t]))
503
504 \f
505 (defun texinfo-filter (section list)
506   (let (res)
507     (dolist (x list) (if (eq section (cadr x)) (push (car x) res)))
508     res))
509
510 (defvar texinfo-chapter-level-regexp
511   (regexp-opt (texinfo-filter 2 texinfo-section-list))
512   "Regular expression matching just the Texinfo chapter level headings.")
513
514 (defun texinfo-current-defun-name ()
515   "Return the name of the Texinfo node at point, or nil."
516   (save-excursion
517     (if (re-search-backward "^@node[ \t]+\\([^,\n]+\\)" nil t)
518         (match-string-no-properties 1))))
519
520 ;;; Texinfo mode
521
522 ;;;###autoload
523 (define-derived-mode texinfo-mode text-mode "Texinfo"
524   "Major mode for editing Texinfo files.
525
526   It has these extra commands:
527 \\{texinfo-mode-map}
528
529   These are files that are used as input for TeX to make printed manuals
530 and also to be turned into Info files with \\[makeinfo-buffer] or
531 the `makeinfo' program.  These files must be written in a very restricted and
532 modified version of TeX input format.
533
534   Editing commands are like text-mode except that the syntax table is
535 set up so expression commands skip Texinfo bracket groups.  To see
536 what the Info version of a region of the Texinfo file will look like,
537 use \\[makeinfo-region], which runs `makeinfo' on the current region.
538
539   You can show the structure of a Texinfo file with \\[texinfo-show-structure].
540 This command shows the structure of a Texinfo file by listing the
541 lines with the @-sign commands for @chapter, @section, and the like.
542 These lines are displayed in another window called the *Occur* window.
543 In that window, you can position the cursor over one of the lines and
544 use \\[occur-mode-goto-occurrence], to jump to the corresponding spot
545 in the Texinfo file.
546
547   In addition, Texinfo mode provides commands that insert various
548 frequently used @-sign commands into the buffer.  You can use these
549 commands to save keystrokes.  And you can insert balanced braces with
550 \\[texinfo-insert-braces] and later use the command \\[up-list] to
551 move forward past the closing brace.
552
553 Also, Texinfo mode provides functions for automatically creating or
554 updating menus and node pointers.  These functions
555
556   * insert the `Next', `Previous' and `Up' pointers of a node,
557   * insert or update the menu for a section, and
558   * create a master menu for a Texinfo source file.
559
560 Here are the functions:
561
562     texinfo-update-node                \\[texinfo-update-node]
563     texinfo-every-node-update          \\[texinfo-every-node-update]
564     texinfo-sequential-node-update
565
566     texinfo-make-menu                  \\[texinfo-make-menu]
567     texinfo-all-menus-update           \\[texinfo-all-menus-update]
568     texinfo-master-menu
569
570     texinfo-indent-menu-description (column &optional region-p)
571
572 The `texinfo-column-for-description' variable specifies the column to
573 which menu descriptions are indented.
574
575 Passed an argument (a prefix argument, if interactive), the
576 `texinfo-update-node' and `texinfo-make-menu' functions do their jobs
577 in the region.
578
579 To use the updating commands, you must structure your Texinfo file
580 hierarchically, such that each `@node' line, with the exception of the
581 Top node, is accompanied by some kind of section line, such as an
582 `@chapter' or `@section' line.
583
584 If the file has a `top' node, it must be called `top' or `Top' and
585 be the first node in the file.
586
587 Entering Texinfo mode calls the value of `text-mode-hook', and then the
588 value of `texinfo-mode-hook'."
589   (setq-local page-delimiter
590               (concat "^@node [ \t]*[Tt]op\\|^@\\("
591                       texinfo-chapter-level-regexp
592                       "\\)\\>"))
593   (setq-local require-final-newline mode-require-final-newline)
594   (setq-local indent-tabs-mode nil)
595   (setq-local paragraph-separate
596               (concat "\b\\|@[a-zA-Z]*[ \n]\\|"
597                       paragraph-separate))
598   (setq-local paragraph-start (concat "\b\\|@[a-zA-Z]*[ \n]\\|"
599                                       paragraph-start))
600   (setq-local sentence-end-base "\\(@\\(end\\)?dots{}\\|[.?!]\\)[]\"'”)}]*")
601   (setq-local fill-column 70)
602   (setq-local comment-start "@c ")
603   (setq-local comment-start-skip "@c +\\|@comment +")
604   (setq-local words-include-escapes t)
605   (setq-local imenu-generic-expression texinfo-imenu-generic-expression)
606   (setq imenu-case-fold-search nil)
607   (setq font-lock-defaults
608         '(texinfo-font-lock-keywords nil nil nil backward-paragraph))
609   (setq-local syntax-propertize-function texinfo-syntax-propertize-function)
610   (setq-local parse-sexp-lookup-properties t)
611   (setq-local add-log-current-defun-function #'texinfo-current-defun-name)
612
613   ;; Outline settings.
614   (setq-local outline-heading-alist
615               ;; We should merge `outline-heading-alist' and
616               ;; `texinfo-section-list'.  But in the mean time, let's
617               ;; just generate one from the other.
618               (mapcar (lambda (x) (cons (concat "@" (car x)) (cadr x)))
619                       texinfo-section-list))
620   (setq-local outline-regexp
621               (concat (regexp-opt (mapcar 'car outline-heading-alist) t)
622                       "\\>"))
623
624   (setq-local tex-start-of-header "%\\*\\*start")
625   (setq-local tex-end-of-header "%\\*\\*end")
626   (setq-local tex-first-line-header-regexp "^\\\\input")
627   (setq-local tex-trailer "@bye\n")
628
629   ;; Prevent filling certain lines, in addition to ones specified by
630   ;; the user.
631   (setq-local auto-fill-inhibit-regexp
632               (let ((prevent-filling "^@\\(def\\|multitable\\)"))
633                 (if (null auto-fill-inhibit-regexp)
634                     prevent-filling
635                   (concat auto-fill-inhibit-regexp "\\|" prevent-filling)))))
636
637
638 \f
639 ;;; Insert string commands
640
641 (defvar texinfo-block-default "example")
642
643 (define-skeleton texinfo-insert-block
644   "Create a matching pair @<cmd> .. @end <cmd> at point.
645 Puts point on a blank line between them."
646   (setq texinfo-block-default
647         (completing-read (format "Block name [%s]: " texinfo-block-default)
648                          texinfo-environments
649                          nil nil nil nil texinfo-block-default))
650   \n "@" str
651   ;; Blocks that take parameters: all the def* blocks take parameters,
652   ;;  plus a few others.
653   (if (or (string-match "\\`def" str)
654           (member str '("table" "ftable" "vtable")))
655       '(nil " " -))
656   \n _ \n "@end " str \n)
657
658 (defun texinfo-inside-macro-p (macro &optional bound)
659   "Non-nil if inside a macro matching the regexp MACRO."
660   (condition-case nil
661       (save-excursion
662         (save-restriction
663           (narrow-to-region bound (point))
664           (while (progn
665                    (up-list -1)
666                    (not (condition-case nil
667                             (save-excursion
668                               (backward-sexp 1)
669                               (looking-at macro))
670                           (scan-error nil)))))
671           t))
672     (scan-error nil)))
673
674 (defun texinfo-inside-env-p (env &optional bound)
675   "Non-nil if inside an environment matching the regexp @ENV."
676   (save-excursion
677     (and (re-search-backward (concat "@\\(end\\s +\\)?" env) bound t)
678          (not (match-end 1)))))
679
680 (defvar texinfo-enable-quote-macros "@\\(code\\|samp\\|kbd\\)\\>")
681 (defvar texinfo-enable-quote-envs
682   '("example\\>" "smallexample\\>" "lisp\\>"))
683 (defun texinfo-insert-quote (&optional arg)
684   "Insert the appropriate quote mark for Texinfo.
685 Usually inserts the value of `texinfo-open-quote' (normally ``) or
686 `texinfo-close-quote' (normally ''), depending on the context.
687 With prefix argument or inside @code or @example, inserts a plain \"."
688   (interactive "*P")
689   (let ((top (or (save-excursion (re-search-backward "@node\\>" nil t))
690                  (point-min))))
691     (if (or arg
692             (= (preceding-char) ?\\)
693             (save-excursion
694               ;; Might be near the start of a (narrowed) buffer.
695               (ignore-errors (backward-char (length texinfo-open-quote)))
696               (when (or (looking-at texinfo-open-quote)
697                         (looking-at texinfo-close-quote))
698                 (delete-char (length texinfo-open-quote))
699                 t))
700             (texinfo-inside-macro-p texinfo-enable-quote-macros top)
701             (let ((in-env nil))
702               (dolist (env texinfo-enable-quote-envs in-env)
703                 (if (texinfo-inside-env-p env top)
704                     (setq in-env t)))))
705         (self-insert-command (prefix-numeric-value arg))
706       (insert
707        (if (or (bobp)
708                (memq (char-syntax (preceding-char)) '(?\( ?> ?\s)))
709            texinfo-open-quote
710          texinfo-close-quote)))))
711
712 ;; The following texinfo-insert-@end command not only inserts a SPC
713 ;; after the @end, but tries to find out what belongs there.  It is
714 ;; not very smart: it does not understand nested lists.
715
716 (defun texinfo-last-unended-begin ()
717   (while (and (re-search-backward texinfo-environment-regexp)
718               (looking-at "@end"))
719     (texinfo-last-unended-begin)))
720
721 (defun texinfo-next-unmatched-end ()
722   (while (and (re-search-forward texinfo-environment-regexp)
723               (save-excursion
724                 (goto-char (match-beginning 0))
725                 (not (looking-at "@end"))))
726     (texinfo-next-unmatched-end)))
727
728 (define-skeleton texinfo-insert-@end
729   "Insert the matching `@end' for the last Texinfo command that needs one."
730          (ignore-errors
731            (save-excursion
732       (backward-word 1)
733              (texinfo-last-unended-begin)
734       (or (match-string 1) '-)))
735   \n "@end " str \n)
736
737 (define-skeleton texinfo-insert-braces
738   "Make a pair of braces and be poised to type inside of them.
739 Use \\[up-list] to move forward out of the braces."
740   nil
741   "{" _ "}")
742
743 (define-skeleton texinfo-insert-@code
744   "Insert a `@code{...}' command in a Texinfo buffer.
745 A numeric argument says how many words the braces should surround.
746 The default is not to surround any existing words with the braces."
747   nil
748   "@code{" _ "}")
749
750 (define-skeleton texinfo-insert-@dfn
751   "Insert a `@dfn{...}' command in a Texinfo buffer.
752 A numeric argument says how many words the braces should surround.
753 The default is not to surround any existing words with the braces."
754   nil
755   "@dfn{" _ "}")
756
757 (define-skeleton texinfo-insert-@email
758   "Insert a `@email{...}' command in a Texinfo buffer.
759 A numeric argument says how many words the braces should surround.
760 The default is not to surround any existing words with the braces."
761   nil
762   "@email{" _ "}")
763
764 (define-skeleton texinfo-insert-@emph
765   "Insert a `@emph{...}' command in a Texinfo buffer.
766 A numeric argument says how many words the braces should surround.
767 The default is not to surround any existing words with the braces."
768   nil
769   "@emph{" _ "}")
770
771 (define-skeleton texinfo-insert-@example
772   "Insert the string `@example' in a Texinfo buffer."
773   nil
774   \n "@example" \n)
775
776 (define-skeleton texinfo-insert-@file
777   "Insert a `@file{...}' command in a Texinfo buffer.
778 A numeric argument says how many words the braces should surround.
779 The default is not to surround any existing words with the braces."
780   nil
781   "@file{" _ "}")
782
783 (define-skeleton texinfo-insert-@item
784   "Insert the string `@item' in a Texinfo buffer.
785 If in a table defined by @table, follow said string with a space.
786 Otherwise, follow with a newline."
787   nil
788   \n "@item"
789           (if (equal (ignore-errors
790                       (save-excursion
791                         (texinfo-last-unended-begin)
792                         (match-string 1)))
793                      "table")
794       " " '\n)
795   _ \n)
796
797 (define-skeleton texinfo-insert-@kbd
798   "Insert a `@kbd{...}' command in a Texinfo buffer.
799 A numeric argument says how many words the braces should surround.
800 The default is not to surround any existing words with the braces."
801   nil
802   "@kbd{" _ "}")
803
804 (define-skeleton texinfo-insert-@node
805   "Insert the string `@node' in a Texinfo buffer.
806 Insert a comment on the following line indicating the order of
807 arguments to @node.  Insert a carriage return after the comment line.
808 Leave point after `@node'."
809   nil
810   \n "@node " _ \n)
811
812 (define-skeleton texinfo-insert-@noindent
813   "Insert the string `@noindent' in a Texinfo buffer."
814   nil
815   \n "@noindent" \n)
816
817 (define-skeleton texinfo-insert-@quotation
818   "Insert the string `@quotation' in a Texinfo buffer."
819   \n "@quotation" \n)
820
821 (define-skeleton texinfo-insert-@samp
822   "Insert a `@samp{...}' command in a Texinfo buffer.
823 A numeric argument says how many words the braces should surround.
824 The default is not to surround any existing words with the braces."
825   nil
826   "@samp{" _ "}")
827
828 (define-skeleton texinfo-insert-@strong
829   "Insert a `@strong{...}' command in a Texinfo buffer.
830 A numeric argument says how many words the braces should surround.
831 The default is not to surround any existing words with the braces."
832   nil
833   "@strong{" _ "}")
834
835 (define-skeleton texinfo-insert-@table
836   "Insert the string `@table' in a Texinfo buffer."
837   nil
838   \n "@table " _ \n)
839
840 (define-skeleton texinfo-insert-@var
841   "Insert a `@var{}' command in a Texinfo buffer.
842 A numeric argument says how many words the braces should surround.
843 The default is not to surround any existing words with the braces."
844   nil
845   "@var{" _ "}")
846
847 (define-skeleton texinfo-insert-@uref
848   "Insert a `@uref{}' command in a Texinfo buffer.
849 A numeric argument says how many words the braces should surround.
850 The default is not to surround any existing words with the braces."
851   nil
852   "@uref{" _ "}")
853 (defalias 'texinfo-insert-@url 'texinfo-insert-@uref)
854 \f
855 ;;; Texinfo file structure
856
857 (defun texinfo-show-structure (&optional nodes-too)
858   "Show the structure of a Texinfo file.
859 List the lines in the file that begin with the @-sign commands for
860 @chapter, @section, and the like.
861
862 With optional argument (prefix if interactive), list both the lines
863 with @-sign commands for @chapter, @section, and the like, and list
864 @node lines.
865
866 Lines with structuring commands beginning in them are displayed in
867 another buffer named `*Occur*'.  In that buffer, you can move point to
868 one of those lines and then use
869 \\<occur-mode-map>\\[occur-mode-goto-occurrence],
870 to jump to the corresponding spot in the Texinfo source file."
871
872   (interactive "P")
873   ;; First, remember current location
874   (let (current-location)
875     (save-excursion
876       (end-of-line)            ; so as to find section on current line
877       (if (re-search-backward
878            ;; do not require `texinfo-section-types-regexp' in texnfo-upd.el
879            "^@\\(chapter \\|sect\\|subs\\|subh\\|unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
880            nil t)
881           (setq current-location
882                 (progn
883                   (beginning-of-line)
884                   (buffer-substring (point) (progn (end-of-line) (point)))))
885         ;; else point is located before any section command.
886         (setq current-location "tex")))
887     ;; Second, create and format an *Occur* buffer
888     (save-excursion
889       (goto-char (point-min))
890       (occur (concat "^\\(?:" (if nodes-too "@node\\>\\|")
891                      outline-regexp "\\)")))
892     (pop-to-buffer "*Occur*")
893     (goto-char (point-min))
894     (let ((inhibit-read-only t))
895       (flush-lines "-----")
896       ;; Now format the "*Occur*" buffer to show the structure.
897       ;; Thanks to ceder@signum.se (Per Cederqvist)
898       (goto-char (point-max))
899       (let (level)
900         (while (re-search-backward "^ *[0-9]*:@\\(\\sw+\\)" nil 0)
901           (goto-char (1- (match-beginning 1)))
902           (setq level
903                 (or (cadr (assoc (match-string 1) texinfo-section-list)) 2))
904           (indent-to-column (+ (current-column) (* 4 (- level 2))))
905           (beginning-of-line))))
906     ;; Third, go to line corresponding to location in source file
907     ;; potential bug: two exactly similar `current-location' lines ...
908     (goto-char (point-min))
909     (re-search-forward current-location nil t)
910     (beginning-of-line)
911     ))
912
913 \f
914 ;;; The  tex  and  print  function definitions:
915
916 (defcustom texinfo-texi2dvi-command "texi2dvi"
917   "Command used by `texinfo-tex-buffer' to run TeX and texindex on a buffer."
918   :type 'string
919   :group 'texinfo)
920
921 (defcustom texinfo-tex-command "tex"
922   "Command used by `texinfo-tex-region' to run TeX on a region."
923   :type 'string
924   :group 'texinfo)
925
926 (defcustom texinfo-texindex-command "texindex"
927   "Command used by `texinfo-texindex' to sort unsorted index files."
928   :type 'string
929   :group 'texinfo)
930
931 (defcustom texinfo-delete-from-print-queue-command "lprm"
932   "Command string used to delete a job from the line printer queue.
933 Command is used by \\[texinfo-delete-from-print-queue] based on
934 number provided by a previous \\[tex-show-print-queue]
935 command."
936   :type 'string
937   :group 'texinfo)
938
939 (defvar texinfo-tex-trailer "@bye"
940   "String appended after a region sent to TeX by `texinfo-tex-region'.")
941
942 (defun texinfo-tex-region (beg end)
943   "Run TeX on the current region.
944 This works by writing a temporary file (`tex-zap-file') in the directory
945 that is the value of `tex-directory', then running TeX on that file.
946
947 The first line of the buffer is copied to the
948 temporary file; and if the buffer has a header, it is written to the
949 temporary file before the region itself.  The buffer's header is all lines
950 between the strings defined by `tex-start-of-header' and `tex-end-of-header'
951 inclusive.  The header must start in the first 100 lines.
952
953 The value of `texinfo-tex-trailer' is appended to the temporary file after the region."
954   (interactive "r")
955   (require 'tex-mode)
956   (let ((tex-command texinfo-tex-command)
957         (tex-trailer texinfo-tex-trailer))
958     (tex-region beg end)))
959
960 (defun texinfo-tex-buffer ()
961   "Run TeX on visited file, once or twice, to make a correct `.dvi' file."
962   (interactive)
963   (require 'tex-mode)
964   (let ((tex-command texinfo-texi2dvi-command)
965         ;; Disable tex-start-options-string.  texi2dvi would not
966         ;; understand anything specified here.
967         (tex-start-options-string ""))
968     (tex-buffer)))
969
970 (defun texinfo-texindex ()
971   "Run `texindex' on unsorted index files.
972 The index files are made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
973 This runs the shell command defined by `texinfo-texindex-command'."
974   (interactive)
975   (require 'tex-mode)
976   (tex-send-command texinfo-texindex-command (concat tex-zap-file ".??"))
977   ;; alternatively
978   ;; (send-string "tex-shell"
979   ;;              (concat texinfo-texindex-command
980   ;;                      " " tex-zap-file ".??" "\n"))
981   (tex-recenter-output-buffer nil))
982
983 (defun texinfo-tex-print ()
984   "Print `.dvi' file made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
985 This runs the shell command defined by `tex-dvi-print-command'."
986   (interactive)
987   (require 'tex-mode)
988   (tex-print))
989
990 (defun texinfo-tex-view ()
991   "View `.dvi' file made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
992 This runs the shell command defined by `tex-dvi-view-command'."
993   (interactive)
994   (require 'tex-mode)
995   (tex-view))
996
997 (defun texinfo-quit-job ()
998   "Quit currently running TeX job, by sending an `x' to it."
999   (interactive)
1000   (if (not (get-process "tex-shell"))
1001       (error "No TeX shell running"))
1002   (tex-send-command "x"))
1003 ;; alternatively:
1004 ;; save-excursion
1005 ;;   (set-buffer (get-buffer "*tex-shell*"))
1006 ;;   (goto-char (point-max))
1007 ;;   (insert "x")
1008 ;;   (comint-send-input)
1009
1010 (defun texinfo-delete-from-print-queue (job-number)
1011   "Delete job from the line printer spooling queue.
1012 You are prompted for the job number (use a number shown by a previous
1013 \\[tex-show-print-queue] command)."
1014   (interactive "nPrinter job number for deletion: ")
1015   (require 'tex-mode)
1016   (if (tex-shell-running)
1017       (tex-kill-job)
1018     (tex-start-shell))
1019   (tex-send-command texinfo-delete-from-print-queue-command job-number)
1020   ;; alternatively
1021   ;; (send-string "tex-shell"
1022   ;;              (concat
1023   ;;               texinfo-delete-from-print-queue-command
1024   ;;               " "
1025   ;;               job-number"\n"))
1026   (tex-recenter-output-buffer nil))
1027
1028 (provide 'texinfo)
1029
1030 ;;; texinfo.el ends here