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