lisp/textmodes/texinfo.el

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