; Fix wrong/duplicate ChangeLog entries
[emacs.git] / lisp / textmodes / texinfo.el
blob6b28249c427ebf90f9b5d8a223459c4339eb9a0b
1 ;;; texinfo.el --- major mode for editing Texinfo files -*- coding: utf-8 -*-
3 ;; Copyright (C) 1985, 1988-1993, 1996-1997, 2000-2015 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)
72 \f
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)
272 \f
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)
354 (define-obsolete-face-alias 'texinfo-heading-face 'texinfo-heading "22.1")
355 (defvar texinfo-heading-face 'texinfo-heading)
357 (defvar texinfo-font-lock-keywords
358 `(;; All but the first had an OVERRIDE of t.
359 ;; It didn't seem to be any better, and it's slower--simon.
360 ;; Robert J. Chassell <bob@gnu.org> says remove this line.
361 ;;("\\$\\([^$]*\\)\\$" 1 font-lock-string-face t)
362 ("@\\([a-zA-Z]+\\|[^ \t\n]\\)" 1 font-lock-keyword-face) ;commands
363 ("^\\*\\([^\n:]*\\)" 1 font-lock-function-name-face t) ;menu items
364 ("@\\(emph\\|i\\|sc\\){\\([^}]+\\)" 2 'italic)
365 ("@\\(strong\\|b\\){\\([^}]+\\)" 2 'bold)
366 ("@\\(kbd\\|key\\|url\\|uref\\){\\([^}]+\\)" 2 font-lock-string-face)
367 ;; The following two groups have an OVERRIDE of `keep' because
368 ;; their arguments frequently include a @@, and we don't want that
369 ;; to overwrite the normal fontification of the argument.
370 ("@\\(file\\|email\\){\\([^}]+\\)" 2 font-lock-string-face keep)
371 ("@\\(samp\\|code\\|var\\|math\\|env\\|command\\|option\\){\\([^}]+\\)"
372 2 font-lock-variable-name-face keep)
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") 0 texinfo-heading-face t))
382 "Additional expressions to highlight in Texinfo mode.")
384 (defun texinfo-clone-environment (start end)
385 (let ((endp nil))
386 (save-excursion
387 (ignore-errors
388 (goto-char start)
389 (when (looking-at "end\\Sw+\\(\\sw+\\)")
390 (setq endp t start (match-beginning 1) end (match-end 1)))
391 (unless (get-char-property start 'text-clones)
392 (if endp
393 (texinfo-last-unended-begin)
394 (forward-word 1)
395 (texinfo-next-unmatched-end))
396 (skip-syntax-forward "^w")
397 (when (looking-at
398 (concat (regexp-quote (buffer-substring start end)) "\\>"))
399 (text-clone-create start end 'spread "\\w*")))))))
401 \f
402 ;;; Keybindings
404 ;;; Keys common both to Texinfo mode and to TeX shell.
406 (defun texinfo-define-common-keys (keymap)
407 "Define the keys both in Texinfo mode and in the texinfo-tex-shell."
408 (define-key keymap "\C-c\C-t\C-k" 'tex-kill-job)
409 (define-key keymap "\C-c\C-t\C-x" 'texinfo-quit-job)
410 (define-key keymap "\C-c\C-t\C-l" 'tex-recenter-output-buffer)
411 (define-key keymap "\C-c\C-t\C-d" 'texinfo-delete-from-print-queue)
412 (define-key keymap "\C-c\C-t\C-q" 'tex-show-print-queue)
413 (define-key keymap "\C-c\C-t\C-p" 'texinfo-tex-print)
414 (define-key keymap "\C-c\C-t\C-v" 'texinfo-tex-view)
415 (define-key keymap "\C-c\C-t\C-i" 'texinfo-texindex)
417 (define-key keymap "\C-c\C-t\C-r" 'texinfo-tex-region)
418 (define-key keymap "\C-c\C-t\C-b" 'texinfo-tex-buffer))
420 ;; Mode documentation displays commands in reverse order
421 ;; from how they are listed in the texinfo-mode-map.
423 (defvar texinfo-mode-map
424 (let ((map (make-sparse-keymap)))
426 ;; bindings for `texnfo-tex.el'
427 (texinfo-define-common-keys map)
429 (define-key map "\"" 'texinfo-insert-quote)
431 ;; bindings for `makeinfo.el'
432 (define-key map "\C-c\C-m\C-k" 'kill-compilation)
433 (define-key map "\C-c\C-m\C-l"
434 'makeinfo-recenter-compilation-buffer)
435 (define-key map "\C-c\C-m\C-r" 'makeinfo-region)
436 (define-key map "\C-c\C-m\C-b" 'makeinfo-buffer)
438 ;; bindings for `texinfmt.el'
439 (define-key map "\C-c\C-e\C-r" 'texinfo-format-region)
440 (define-key map "\C-c\C-e\C-b" 'texinfo-format-buffer)
442 ;; AUCTeX-like bindings
443 (define-key map "\e\r" 'texinfo-insert-@item)
445 ;; bindings for updating nodes and menus
447 (define-key map "\C-c\C-um" 'texinfo-master-menu)
449 (define-key map "\C-c\C-u\C-m" 'texinfo-make-menu)
450 (define-key map "\C-c\C-u\C-n" 'texinfo-update-node)
451 (define-key map "\C-c\C-u\C-e" 'texinfo-every-node-update)
452 (define-key map "\C-c\C-u\C-a" 'texinfo-all-menus-update)
454 (define-key map "\C-c\C-s" 'texinfo-show-structure)
456 (define-key map "\C-c}" 'up-list)
457 ;; FIXME: This is often used for "close block" aka texinfo-insert-@end.
458 (define-key map "\C-c]" 'up-list)
459 (define-key map "\C-c/" 'texinfo-insert-@end)
460 (define-key map "\C-c{" 'texinfo-insert-braces)
462 ;; bindings for inserting strings
463 (define-key map "\C-c\C-o" 'texinfo-insert-block)
464 (define-key map "\C-c\C-c\C-d" 'texinfo-start-menu-description)
465 (define-key map "\C-c\C-c\C-s" 'texinfo-insert-@strong)
466 (define-key map "\C-c\C-c\C-e" 'texinfo-insert-@emph)
468 (define-key map "\C-c\C-cv" 'texinfo-insert-@var)
469 (define-key map "\C-c\C-cu" 'texinfo-insert-@uref)
470 (define-key map "\C-c\C-ct" 'texinfo-insert-@table)
471 (define-key map "\C-c\C-cs" 'texinfo-insert-@samp)
472 (define-key map "\C-c\C-cq" 'texinfo-insert-@quotation)
473 (define-key map "\C-c\C-co" 'texinfo-insert-@noindent)
474 (define-key map "\C-c\C-cn" 'texinfo-insert-@node)
475 (define-key map "\C-c\C-cm" 'texinfo-insert-@email)
476 (define-key map "\C-c\C-ck" 'texinfo-insert-@kbd)
477 (define-key map "\C-c\C-ci" 'texinfo-insert-@item)
478 (define-key map "\C-c\C-cf" 'texinfo-insert-@file)
479 (define-key map "\C-c\C-cx" 'texinfo-insert-@example)
480 (define-key map "\C-c\C-ce" 'texinfo-insert-@end)
481 (define-key map "\C-c\C-cd" 'texinfo-insert-@dfn)
482 (define-key map "\C-c\C-cc" 'texinfo-insert-@code)
483 map))
485 (easy-menu-define texinfo-mode-menu
486 texinfo-mode-map
487 "Menu used for `texinfo-mode'."
488 '("Texinfo"
489 ["Insert block" texinfo-insert-block t]
490 ;; ["Insert node" texinfo-insert-@node t]
491 "----"
492 ["Update All" (lambda () (interactive) (texinfo-master-menu t))
493 :keys "\\[universal-argument] \\[texinfo-master-menu]"]
494 ["Update every node" texinfo-every-node-update t]
495 ["Update node" texinfo-update-node t]
496 ["Make Master menu" texinfo-master-menu t]
497 ["Make menu" texinfo-make-menu t]
498 ["Update all menus" texinfo-all-menus-update t]
499 "----"
500 ["Show structure" texinfo-show-structure t]
501 ["Format region" texinfo-format-region t]
502 ["Format buffer" texinfo-format-buffer t]
503 ["Makeinfo region" makeinfo-region t]
504 ["Makeinfo buffer" makeinfo-buffer t]))
506 \f
507 (defun texinfo-filter (section list)
508 (let (res)
509 (dolist (x list) (if (eq section (cadr x)) (push (car x) res)))
510 res))
512 (defvar texinfo-chapter-level-regexp
513 (regexp-opt (texinfo-filter 2 texinfo-section-list))
514 "Regular expression matching just the Texinfo chapter level headings.")
516 (defun texinfo-current-defun-name ()
517 "Return the name of the Texinfo node at point, or nil."
518 (save-excursion
519 (if (re-search-backward "^@node[ \t]+\\([^,\n]+\\)" nil t)
520 (match-string-no-properties 1))))
522 ;;; Texinfo mode
524 ;;;###autoload
525 (define-derived-mode texinfo-mode text-mode "Texinfo"
526 "Major mode for editing Texinfo files.
528 It has these extra commands:
529 \\{texinfo-mode-map}
531 These are files that are used as input for TeX to make printed manuals
532 and also to be turned into Info files with \\[makeinfo-buffer] or
533 the `makeinfo' program. These files must be written in a very restricted and
534 modified version of TeX input format.
536 Editing commands are like text-mode except that the syntax table is
537 set up so expression commands skip Texinfo bracket groups. To see
538 what the Info version of a region of the Texinfo file will look like,
539 use \\[makeinfo-region], which runs `makeinfo' on the current region.
541 You can show the structure of a Texinfo file with \\[texinfo-show-structure].
542 This command shows the structure of a Texinfo file by listing the
543 lines with the @-sign commands for @chapter, @section, and the like.
544 These lines are displayed in another window called the *Occur* window.
545 In that window, you can position the cursor over one of the lines and
546 use \\[occur-mode-goto-occurrence], to jump to the corresponding spot
547 in the Texinfo file.
549 In addition, Texinfo mode provides commands that insert various
550 frequently used @-sign commands into the buffer. You can use these
551 commands to save keystrokes. And you can insert balanced braces with
552 \\[texinfo-insert-braces] and later use the command \\[up-list] to
553 move forward past the closing brace.
555 Also, Texinfo mode provides functions for automatically creating or
556 updating menus and node pointers. These functions
558 * insert the `Next', `Previous' and `Up' pointers of a node,
559 * insert or update the menu for a section, and
560 * create a master menu for a Texinfo source file.
562 Here are the functions:
564 texinfo-update-node \\[texinfo-update-node]
565 texinfo-every-node-update \\[texinfo-every-node-update]
566 texinfo-sequential-node-update
568 texinfo-make-menu \\[texinfo-make-menu]
569 texinfo-all-menus-update \\[texinfo-all-menus-update]
570 texinfo-master-menu
572 texinfo-indent-menu-description (column &optional region-p)
574 The `texinfo-column-for-description' variable specifies the column to
575 which menu descriptions are indented.
577 Passed an argument (a prefix argument, if interactive), the
578 `texinfo-update-node' and `texinfo-make-menu' functions do their jobs
579 in the region.
581 To use the updating commands, you must structure your Texinfo file
582 hierarchically, such that each `@node' line, with the exception of the
583 Top node, is accompanied by some kind of section line, such as an
584 `@chapter' or `@section' line.
586 If the file has a `top' node, it must be called `top' or `Top' and
587 be the first node in the file.
589 Entering Texinfo mode calls the value of `text-mode-hook', and then the
590 value of `texinfo-mode-hook'."
591 (setq-local page-delimiter
592 (concat "^@node [ \t]*[Tt]op\\|^@\\("
593 texinfo-chapter-level-regexp
594 "\\)\\>"))
595 (setq-local require-final-newline mode-require-final-newline)
596 (setq-local indent-tabs-mode nil)
597 (setq-local paragraph-separate
598 (concat "\b\\|@[a-zA-Z]*[ \n]\\|"
599 paragraph-separate))
600 (setq-local paragraph-start (concat "\b\\|@[a-zA-Z]*[ \n]\\|"
601 paragraph-start))
602 (setq-local sentence-end-base "\\(@\\(end\\)?dots{}\\|[.?!]\\)[]\"'”)}]*")
603 (setq-local fill-column 70)
604 (setq-local comment-start "@c ")
605 (setq-local comment-start-skip "@c +\\|@comment +")
606 (setq-local words-include-escapes t)
607 (setq-local imenu-generic-expression texinfo-imenu-generic-expression)
608 (setq imenu-case-fold-search nil)
609 (setq font-lock-defaults
610 '(texinfo-font-lock-keywords nil nil nil backward-paragraph))
611 (setq-local syntax-propertize-function texinfo-syntax-propertize-function)
612 (setq-local parse-sexp-lookup-properties t)
613 (setq-local add-log-current-defun-function #'texinfo-current-defun-name)
615 ;; Outline settings.
616 (setq-local outline-heading-alist
617 ;; We should merge `outline-heading-alist' and
618 ;; `texinfo-section-list'. But in the mean time, let's
619 ;; just generate one from the other.
620 (mapcar (lambda (x) (cons (concat "@" (car x)) (cadr x)))
621 texinfo-section-list))
622 (setq-local outline-regexp
623 (concat (regexp-opt (mapcar 'car outline-heading-alist) t)
624 "\\>"))
626 (setq-local tex-start-of-header "%\\*\\*start")
627 (setq-local tex-end-of-header "%\\*\\*end")
628 (setq-local tex-first-line-header-regexp "^\\\\input")
629 (setq-local tex-trailer "@bye\n")
631 ;; Prevent skeleton.el from adding a newline to each inserted
632 ;; skeleton. Those which do want a newline do that explicitly in
633 ;; their define-skeleton form.
634 (setq-local skeleton-end-newline nil)
636 ;; Prevent filling certain lines, in addition to ones specified by
637 ;; the user.
638 (setq-local auto-fill-inhibit-regexp
639 (let ((prevent-filling "^@\\(def\\|multitable\\)"))
640 (if (null auto-fill-inhibit-regexp)
641 prevent-filling
642 (concat auto-fill-inhibit-regexp "\\|" prevent-filling)))))
645 \f
646 ;;; Insert string commands
648 (defvar texinfo-block-default "example")
650 (define-skeleton texinfo-insert-block
651 "Create a matching pair @<cmd> .. @end <cmd> at point.
652 Puts point on a blank line between them."
653 (setq texinfo-block-default
654 (completing-read (format "Block name [%s]: " texinfo-block-default)
655 texinfo-environments
656 nil nil nil nil texinfo-block-default))
657 \n "@" str
658 ;; Blocks that take parameters: all the def* blocks take parameters,
659 ;; plus a few others.
660 (if (or (string-match "\\`def" str)
661 (member str '("table" "ftable" "vtable")))
662 '(nil " " -))
663 \n _ \n "@end " str \n \n)
665 (defun texinfo-inside-macro-p (macro &optional bound)
666 "Non-nil if inside a macro matching the regexp MACRO."
667 (condition-case nil
668 (save-excursion
669 (save-restriction
670 (narrow-to-region bound (point))
671 (while (progn
672 (up-list -1)
673 (not (condition-case nil
674 (save-excursion
675 (backward-sexp 1)
676 (looking-at macro))
677 (scan-error nil)))))
678 t))
679 (scan-error nil)))
681 (defun texinfo-inside-env-p (env &optional bound)
682 "Non-nil if inside an environment matching the regexp @ENV."
683 (save-excursion
684 (and (re-search-backward (concat "@\\(end\\s +\\)?" env) bound t)
685 (not (match-end 1)))))
687 (defvar texinfo-enable-quote-macros "@\\(code\\|samp\\|kbd\\)\\>")
688 (defvar texinfo-enable-quote-envs
689 '("example\\>" "smallexample\\>" "lisp\\>"))
690 (defun texinfo-insert-quote (&optional arg)
691 "Insert the appropriate quote mark for Texinfo.
692 Usually inserts the value of `texinfo-open-quote' (normally \\=`\\=`) or
693 `texinfo-close-quote' (normally ''), depending on the context.
694 With prefix argument or inside @code or @example, inserts a plain \"."
695 (interactive "*P")
696 (let ((top (or (save-excursion (re-search-backward "@node\\>" nil t))
697 (point-min))))
698 (if (or arg
699 (= (preceding-char) ?\\)
700 (save-excursion
701 ;; Might be near the start of a (narrowed) buffer.
702 (ignore-errors (backward-char (length texinfo-open-quote)))
703 (when (or (looking-at texinfo-open-quote)
704 (looking-at texinfo-close-quote))
705 (delete-char (length texinfo-open-quote))
706 t))
707 (texinfo-inside-macro-p texinfo-enable-quote-macros top)
708 (let ((in-env nil))
709 (dolist (env texinfo-enable-quote-envs in-env)
710 (if (texinfo-inside-env-p env top)
711 (setq in-env t)))))
712 (self-insert-command (prefix-numeric-value arg))
713 (insert
714 (if (or (bobp)
715 (memq (char-syntax (preceding-char)) '(?\( ?> ?\s)))
716 texinfo-open-quote
717 texinfo-close-quote)))))
719 ;; The following texinfo-insert-@end command not only inserts a SPC
720 ;; after the @end, but tries to find out what belongs there. It is
721 ;; not very smart: it does not understand nested lists.
723 (defun texinfo-last-unended-begin ()
724 (while (and (re-search-backward texinfo-environment-regexp)
725 (looking-at "@end"))
726 (texinfo-last-unended-begin)))
728 (defun texinfo-next-unmatched-end ()
729 (while (and (re-search-forward texinfo-environment-regexp)
730 (save-excursion
731 (goto-char (match-beginning 0))
732 (not (looking-at "@end"))))
733 (texinfo-next-unmatched-end)))
735 (define-skeleton texinfo-insert-@end
736 "Insert the matching `@end' for the last Texinfo command that needs one."
737 (ignore-errors
738 (save-excursion
739 (backward-word 1)
740 (texinfo-last-unended-begin)
741 (or (match-string 1) '-)))
742 \n "@end " str \n \n)
744 (define-skeleton texinfo-insert-braces
745 "Make a pair of braces and be poised to type inside of them.
746 Use \\[up-list] to move forward out of the braces."
747 nil
748 "{" _ "}")
750 (define-skeleton texinfo-insert-@code
751 "Insert a `@code{...}' 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 "@code{" _ "}")
757 (define-skeleton texinfo-insert-@dfn
758 "Insert a `@dfn{...}' 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 "@dfn{" _ "}")
764 (define-skeleton texinfo-insert-@email
765 "Insert a `@email{...}' 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 "@email{" _ "}")
771 (define-skeleton texinfo-insert-@emph
772 "Insert a `@emph{...}' command in a Texinfo buffer.
773 A numeric argument says how many words the braces should surround.
774 The default is not to surround any existing words with the braces."
775 nil
776 "@emph{" _ "}")
778 (define-skeleton texinfo-insert-@example
779 "Insert the string `@example' in a Texinfo buffer."
780 nil
781 \n "@example" \n \n)
783 (define-skeleton texinfo-insert-@file
784 "Insert a `@file{...}' command in a Texinfo buffer.
785 A numeric argument says how many words the braces should surround.
786 The default is not to surround any existing words with the braces."
787 nil
788 "@file{" _ "}")
790 (define-skeleton texinfo-insert-@item
791 "Insert the string `@item' in a Texinfo buffer.
792 If in a table defined by @table, follow said string with a space.
793 Otherwise, follow with a newline."
794 nil
795 \n "@item"
796 (if (equal (ignore-errors
797 (save-excursion
798 (texinfo-last-unended-begin)
799 (match-string 1)))
800 "table")
801 " " '\n)
802 _ \n)
804 (define-skeleton texinfo-insert-@kbd
805 "Insert a `@kbd{...}' command in a Texinfo buffer.
806 A numeric argument says how many words the braces should surround.
807 The default is not to surround any existing words with the braces."
808 nil
809 "@kbd{" _ "}")
811 (define-skeleton texinfo-insert-@node
812 "Insert the string `@node' in a Texinfo buffer.
813 Insert a comment on the following line indicating the order of
814 arguments to @node. Insert a carriage return after the comment line.
815 Leave point after `@node'."
816 nil
817 \n "@node " _ \n)
819 (define-skeleton texinfo-insert-@noindent
820 "Insert the string `@noindent' in a Texinfo buffer."
821 nil
822 \n "@noindent" \n)
824 (define-skeleton texinfo-insert-@quotation
825 "Insert the string `@quotation' in a Texinfo buffer."
826 \n "@quotation" \n _ \n)
828 (define-skeleton texinfo-insert-@samp
829 "Insert a `@samp{...}' 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 "@samp{" _ "}")
835 (define-skeleton texinfo-insert-@strong
836 "Insert a `@strong{...}' command in a Texinfo buffer.
837 A numeric argument says how many words the braces should surround.
838 The default is not to surround any existing words with the braces."
839 nil
840 "@strong{" _ "}")
842 (define-skeleton texinfo-insert-@table
843 "Insert the string `@table' in a Texinfo buffer."
844 nil
845 \n "@table " _ \n)
847 (define-skeleton texinfo-insert-@var
848 "Insert a `@var{}' 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 "@var{" _ "}")
854 (define-skeleton texinfo-insert-@uref
855 "Insert a `@uref{}' command in a Texinfo buffer.
856 A numeric argument says how many words the braces should surround.
857 The default is not to surround any existing words with the braces."
858 nil
859 "@uref{" _ "}")
860 (defalias 'texinfo-insert-@url 'texinfo-insert-@uref)
861 \f
862 ;;; Texinfo file structure
864 (defun texinfo-show-structure (&optional nodes-too)
865 "Show the structure of a Texinfo file.
866 List the lines in the file that begin with the @-sign commands for
867 @chapter, @section, and the like.
869 With optional argument (prefix if interactive), list both the lines
870 with @-sign commands for @chapter, @section, and the like, and list
871 @node lines.
873 Lines with structuring commands beginning in them are displayed in
874 another buffer named `*Occur*'. In that buffer, you can move point to
875 one of those lines and then use
876 \\<occur-mode-map>\\[occur-mode-goto-occurrence],
877 to jump to the corresponding spot in the Texinfo source file."
879 (interactive "P")
880 ;; First, remember current location
881 (let (current-location)
882 (save-excursion
883 (end-of-line) ; so as to find section on current line
884 (if (re-search-backward
885 ;; do not require `texinfo-section-types-regexp' in texnfo-upd.el
886 "^@\\(chapter \\|sect\\|subs\\|subh\\|unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
887 nil t)
888 (setq current-location
889 (progn
890 (beginning-of-line)
891 (buffer-substring (point) (progn (end-of-line) (point)))))
892 ;; else point is located before any section command.
893 (setq current-location "tex")))
894 ;; Second, create and format an *Occur* buffer
895 (save-excursion
896 (goto-char (point-min))
897 (occur (concat "^\\(?:" (if nodes-too "@node\\>\\|")
898 outline-regexp "\\)")))
899 (pop-to-buffer "*Occur*")
900 (goto-char (point-min))
901 (let ((inhibit-read-only t))
902 (flush-lines "-----")
903 ;; Now format the "*Occur*" buffer to show the structure.
904 ;; Thanks to ceder@signum.se (Per Cederqvist)
905 (goto-char (point-max))
906 (let (level)
907 (while (re-search-backward "^ *[0-9]*:@\\(\\sw+\\)" nil 0)
908 (goto-char (1- (match-beginning 1)))
909 (setq level
910 (or (cadr (assoc (match-string 1) texinfo-section-list)) 2))
911 (indent-to-column (+ (current-column) (* 4 (- level 2))))
912 (beginning-of-line))))
913 ;; Third, go to line corresponding to location in source file
914 ;; potential bug: two exactly similar `current-location' lines ...
915 (goto-char (point-min))
916 (re-search-forward current-location nil t)
917 (beginning-of-line)
918 ))
920 \f
921 ;;; The tex and print function definitions:
923 (defcustom texinfo-texi2dvi-command "texi2dvi"
924 "Command used by `texinfo-tex-buffer' to run TeX and texindex on a buffer."
925 :type 'string
926 :group 'texinfo)
928 (defcustom texinfo-tex-command "tex"
929 "Command used by `texinfo-tex-region' to run TeX on a region."
930 :type 'string
931 :group 'texinfo)
933 (defcustom texinfo-texindex-command "texindex"
934 "Command used by `texinfo-texindex' to sort unsorted index files."
935 :type 'string
936 :group 'texinfo)
938 (defcustom texinfo-delete-from-print-queue-command "lprm"
939 "Command string used to delete a job from the line printer queue.
940 Command is used by \\[texinfo-delete-from-print-queue] based on
941 number provided by a previous \\[tex-show-print-queue]
942 command."
943 :type 'string
944 :group 'texinfo)
946 (defvar texinfo-tex-trailer "@bye"
947 "String appended after a region sent to TeX by `texinfo-tex-region'.")
949 (defun texinfo-tex-region (beg end)
950 "Run TeX on the current region.
951 This works by writing a temporary file (`tex-zap-file') in the directory
952 that is the value of `tex-directory', then running TeX on that file.
954 The first line of the buffer is copied to the
955 temporary file; and if the buffer has a header, it is written to the
956 temporary file before the region itself. The buffer's header is all lines
957 between the strings defined by `tex-start-of-header' and `tex-end-of-header'
958 inclusive. The header must start in the first 100 lines.
960 The value of `texinfo-tex-trailer' is appended to the temporary file after the region."
961 (interactive "r")
962 (require 'tex-mode)
963 (let ((tex-command texinfo-tex-command)
964 (tex-trailer texinfo-tex-trailer))
965 (tex-region beg end)))
967 (defun texinfo-tex-buffer ()
968 "Run TeX on visited file, once or twice, to make a correct `.dvi' file."
969 (interactive)
970 (require 'tex-mode)
971 (let ((tex-command texinfo-texi2dvi-command)
972 ;; Disable tex-start-options-string. texi2dvi would not
973 ;; understand anything specified here.
974 (tex-start-options-string ""))
975 (tex-buffer)))
977 (defun texinfo-texindex ()
978 "Run `texindex' on unsorted index files.
979 The index files are made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
980 This runs the shell command defined by `texinfo-texindex-command'."
981 (interactive)
982 (require 'tex-mode)
983 (tex-send-command texinfo-texindex-command (concat tex-zap-file ".??"))
984 ;; alternatively
985 ;; (send-string "tex-shell"
986 ;; (concat texinfo-texindex-command
987 ;; " " tex-zap-file ".??" "\n"))
988 (tex-recenter-output-buffer nil))
990 (defun texinfo-tex-print ()
991 "Print `.dvi' file made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
992 This runs the shell command defined by `tex-dvi-print-command'."
993 (interactive)
994 (require 'tex-mode)
995 (tex-print))
997 (defun texinfo-tex-view ()
998 "View `.dvi' file made by \\[texinfo-tex-region] or \\[texinfo-tex-buffer].
999 This runs the shell command defined by `tex-dvi-view-command'."
1000 (interactive)
1001 (require 'tex-mode)
1002 (tex-view))
1004 (defun texinfo-quit-job ()
1005 "Quit currently running TeX job, by sending an `x' to it."
1006 (interactive)
1007 (if (not (get-process "tex-shell"))
1008 (error "No TeX shell running"))
1009 (tex-send-command "x"))
1010 ;; alternatively:
1011 ;; save-excursion
1012 ;; (set-buffer (get-buffer "*tex-shell*"))
1013 ;; (goto-char (point-max))
1014 ;; (insert "x")
1015 ;; (comint-send-input)
1017 (defun texinfo-delete-from-print-queue (job-number)
1018 "Delete job from the line printer spooling queue.
1019 You are prompted for the job number (use a number shown by a previous
1020 \\[tex-show-print-queue] command)."
1021 (interactive "nPrinter job number for deletion: ")
1022 (require 'tex-mode)
1023 (if (tex-shell-running)
1024 (tex-kill-job)
1025 (tex-start-shell))
1026 (tex-send-command texinfo-delete-from-print-queue-command job-number)
1027 ;; alternatively
1028 ;; (send-string "tex-shell"
1029 ;; (concat
1030 ;; texinfo-delete-from-print-queue-command
1031 ;; " "
1032 ;; job-number"\n"))
1033 (tex-recenter-output-buffer nil))
1035 (provide 'texinfo)
1037 ;;; texinfo.el ends here