* net/tramp-sh.el (tramp-histfile-override): Add :version.
[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 (defvar skeleton-end-newline)
48
49 (defgroup texinfo nil
50   "Texinfo Mode."
51   :link '(custom-group-link :tag "Font Lock Faces group" font-lock-faces)
52   :group 'docs)
53
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)
59
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)
65
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)
71
72 \f
73 ;;; Autoloads:
74
75 (autoload 'makeinfo-region
76   "makeinfo"
77   "Make Info file from region of current Texinfo file, and switch to it.
78
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)
83
84 (autoload 'makeinfo-buffer
85   "makeinfo"
86   "Make Info file from current buffer.
87
88 Use the \\[next-error] command to move to the next error
89 \(if there are errors\)."
90   t nil)
91
92 (autoload 'kill-compilation
93   "compile"
94   "Kill the process made by the \\[compile] command."
95   t nil)
96
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)
103
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.
109
110 The functions for creating or updating nodes and menus, and their
111 keybindings, are:
112
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)
116
117     `texinfo-make-menu' (&optional region-p)      \\[texinfo-make-menu]
118     `texinfo-all-menus-update' ()                 \\[texinfo-all-menus-update]
119     `texinfo-master-menu' ()
120
121     `texinfo-indent-menu-description' (column &optional region-p)
122
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)
126
127 (autoload 'texinfo-every-node-update
128   "texnfo-upd"
129   "Update every node in a Texinfo file."
130   t nil)
131
132 (autoload 'texinfo-sequential-node-update
133   "texnfo-upd"
134   "Update one node (or many) in a Texinfo file with sequential pointers.
135
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.
140
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.
144
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)
150
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.
155
156 Non-nil argument (prefix, if interactive) means make or update menus
157 for nodes within or part of the marked region.
158
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)
164
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.
169
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)
173
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.
179
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.
183
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.
187
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'.
191
192 The master menu has the following format, which is adapted from the
193 recommendation in the Texinfo Manual:
194
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.
199
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.
204
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)
208
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)
216
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)
224
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.
230
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)
234
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.
240
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.
244
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.
249
250 The command also updates the `Top' level node pointers of OUTER-FILE.
251
252 Notes:
253
254   * this command does NOT save any files--you must save the
255     outer file and any modified, included files.
256
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.
260
261 Requirements:
262
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.
267
268 Thus, normally, each included file contains one, and only one,
269 chapter."
270   t nil)
271
272 \f
273 ;;; Code:
274
275 ;;; Don't you dare insert any `require' calls at top level in this file--rms.
276
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.")
298
299 ;;; Syntax table
300
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))
314
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'.")
322
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'.")
329
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.")
344
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.")
349
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)
356
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.")
383
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*")))))))
400
401 \f
402 ;;; Keybindings
403
404 ;;; Keys common both to Texinfo mode and to TeX shell.
405
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)
416
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))
419
420 ;; Mode documentation displays commands in reverse order
421 ;; from how they are listed in the texinfo-mode-map.
422
423 (defvar texinfo-mode-map
424   (let ((map (make-sparse-keymap)))
425
426     ;; bindings for `texnfo-tex.el'
427     (texinfo-define-common-keys map)
428
429     (define-key map "\"" 'texinfo-insert-quote)
430
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)
437
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)
441
442     ;; AUCTeX-like bindings
443     (define-key map "\e\r"              'texinfo-insert-@item)
444
445     ;; bindings for updating nodes and menus
446
447     (define-key map "\C-c\C-um"   'texinfo-master-menu)
448
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)
453
454     (define-key map "\C-c\C-s"     'texinfo-show-structure)
455
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)
461
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)
467
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))
484
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]))
505
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))
511
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.")
515
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))))
521
522 ;;; Texinfo mode
523
524 ;;;###autoload
525 (define-derived-mode texinfo-mode text-mode "Texinfo"
526   "Major mode for editing Texinfo files.
527
528   It has these extra commands:
529 \\{texinfo-mode-map}
530
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.
535
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.
540
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.
548
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.
554
555 Also, Texinfo mode provides functions for automatically creating or
556 updating menus and node pointers.  These functions
557
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.
561
562 Here are the functions:
563
564     texinfo-update-node                \\[texinfo-update-node]
565     texinfo-every-node-update          \\[texinfo-every-node-update]
566     texinfo-sequential-node-update
567
568     texinfo-make-menu                  \\[texinfo-make-menu]
569     texinfo-all-menus-update           \\[texinfo-all-menus-update]
570     texinfo-master-menu
571
572     texinfo-indent-menu-description (column &optional region-p)
573
574 The `texinfo-column-for-description' variable specifies the column to
575 which menu descriptions are indented.
576
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.
580
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.
585
586 If the file has a `top' node, it must be called `top' or `Top' and
587 be the first node in the file.
588
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)
614
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                       "\\>"))
625
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")
630
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)
635
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)))))
643
644
645 \f
646 ;;; Insert string commands
647
648 (defvar texinfo-block-default "example")
649
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)
664
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)))
680
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)))))
686
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)))))
718
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.
722
723 (defun texinfo-last-unended-begin ()
724   (while (and (re-search-backward texinfo-environment-regexp)
725               (looking-at "@end"))
726     (texinfo-last-unended-begin)))
727
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)))
734
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)
743
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   "{" _ "}")
749
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{" _ "}")
756
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{" _ "}")
763
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{" _ "}")
770
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{" _ "}")
777
778 (define-skeleton texinfo-insert-@example
779   "Insert the string `@example' in a Texinfo buffer."
780   nil
781   \n "@example" \n \n)
782
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{" _ "}")
789
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)
803
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{" _ "}")
810
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)
818
819 (define-skeleton texinfo-insert-@noindent
820   "Insert the string `@noindent' in a Texinfo buffer."
821   nil
822   \n "@noindent" \n)
823
824 (define-skeleton texinfo-insert-@quotation
825   "Insert the string `@quotation' in a Texinfo buffer."
826   \n "@quotation" \n _ \n)
827
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{" _ "}")
834
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{" _ "}")
841
842 (define-skeleton texinfo-insert-@table
843   "Insert the string `@table' in a Texinfo buffer."
844   nil
845   \n "@table " _ \n)
846
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{" _ "}")
853
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
863
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.
868
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.
872
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."
878
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     ))
919
920 \f
921 ;;; The  tex  and  print  function definitions:
922
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)
927
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)
932
933 (defcustom texinfo-texindex-command "texindex"
934   "Command used by `texinfo-texindex' to sort unsorted index files."
935   :type 'string
936   :group 'texinfo)
937
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)
945
946 (defvar texinfo-tex-trailer "@bye"
947   "String appended after a region sent to TeX by `texinfo-tex-region'.")
948
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.
953
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.
959
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)))
966
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)))
976
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))
989
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))
996
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))
1003
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)
1016
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))
1034
1035 (provide 'texinfo)
1036
1037 ;;; texinfo.el ends here