* admin/charsets/Makefile.in (TRANS_TABLE): Add short aliases.
[emacs.git] / lisp / textmodes / texnfo-upd.el
blobdf05b670095c887aa5324775d0e827b91240802d
1 ;;; texnfo-upd.el --- utilities for updating nodes and menus in Texinfo files
3 ;; Copyright (C) 1989-1992, 2001-2015 Free Software Foundation, Inc.
5 ;; Author: Robert J. Chassell
6 ;; Maintainer: bug-texinfo@gnu.org
7 ;; Keywords: maint, tex, docs
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; Known bug: update commands fail to ignore @ignore, and fail to DTRT
27 ;; with the @if... directives (so expect trouble when the manual uses
28 ;; different @node lines or @menu items in @iftex and in @ifnottex).
30 ;; Summary: how to use the updating commands
32 ;; The node and menu updating functions automatically
34 ;; * insert missing `@node' lines,
35 ;; * insert the `Next', `Previous' and `Up' pointers of a node,
36 ;; * insert or update the menu for a section,
37 ;; * create a master menu for a Texinfo source file.
38 ;;
39 ;; With a prefix argument, the `texinfo-update-node' and
40 ;; `texinfo-make-menu' functions do their jobs in the region.
41 ;;
42 ;; Important note: We do NOT recommend use of these commands to update
43 ;; the `Next', `Previous' and `Up' pointers on @node lines. Most
44 ;; manuals, including those whose Texinfo files adhere to the structure
45 ;; described below, don't need these pointers, because makeinfo will
46 ;; generate them automatically (see the node "makeinfo Pointer
47 ;; Creation" in the Texinfo manual). By contrast, due to known bugs
48 ;; described above, texinfo-update-node etc. could produce incorrect
49 ;; pointers, and thus make a perfectly valid Texinfo file into an
50 ;; invalid one. You _have_ been warned!
51 ;;
52 ;; In brief, the functions for creating or updating nodes and menus, are:
53 ;;
54 ;; texinfo-update-node (&optional beginning end)
55 ;; texinfo-every-node-update ()
56 ;; texinfo-sequential-node-update (&optional region-p)
57 ;;
58 ;; texinfo-make-menu (&optional beginning end)
59 ;; texinfo-all-menus-update ()
60 ;; texinfo-master-menu ()
61 ;;
62 ;; texinfo-insert-node-lines (&optional title-p)
63 ;;
64 ;; texinfo-indent-menu-description (column &optional region-p)
66 ;; The `texinfo-column-for-description' variable specifies the column to
67 ;; which menu descriptions are indented.
69 ;; Texinfo file structure
70 ;; ----------------------
72 ;; To use the updating commands, you must structure your Texinfo file
73 ;; hierarchically. Each `@node' line, with the exception of the top
74 ;; node, must be accompanied by some kind of section line, such as an
75 ;; `@chapter' or `@section' line. Each node-line/section-line
76 ;; combination must look like this:
78 ;; @node Lists and Tables, Cross References, Structuring, Top
79 ;; @comment node-name, next, previous, up
80 ;; @chapter Making Lists and Tables
82 ;; or like this (without the `@comment' line):
84 ;; @node Lists and Tables, Cross References, Structuring, Top
85 ;; @chapter Making Lists and Tables
87 ;; If the file has a `top' node, it must be called `top' or `Top' and
88 ;; be the first node in the file.
90 \f
91 ;;; The update node functions described in detail
93 ;; The `texinfo-update-node' command with no prefix argument inserts
94 ;; the correct next, previous and up pointers for the node in which
95 ;; point is located (i.e., for the node preceding point).
97 ;; With prefix argument, the `texinfo-update-node' function inserts the
98 ;; correct next, previous and up pointers for the nodes inside the
99 ;; region.
101 ;; It does not matter whether the `@node' line has pre-existing
102 ;; `Next', `Previous', or `Up' pointers in it. They are removed.
104 ;; Warning: Since the pre-existing pointers are replaced with the ones
105 ;; computed by `texinfo-update-node', and since this function has
106 ;; known bugs with the more advanced Texinfo features (see above), it
107 ;; could produce an invalid Texinfo file. You are well advised not to
108 ;; use this function, except if you know what you are doing and
109 ;; exercise extreme caution. Keep in mind that most manuals do not
110 ;; need the `Next', `Previous', and `Up' pointers to be present on the
111 ;; @node lines; makeinfo will automatically generate them when it
112 ;; produces the Info or HTML versions of the manual.
114 ;; The `texinfo-every-node-update' function runs `texinfo-update-node'
115 ;; on the whole buffer.
117 ;; The `texinfo-sequential-node-update' function inserts the
118 ;; immediately following and preceding node into the `Next' or
119 ;; `Previous' pointers regardless of their hierarchical level. This is
120 ;; only useful for certain kinds of text, like a novel, which you go
121 ;; through sequentially.
123 \f
124 ;;; The menu making functions described in detail
126 ;; The `texinfo-make-menu' function without an argument creates or
127 ;; updates a menu for the section encompassing the node that follows
128 ;; point. With an argument, it makes or updates menus for the nodes
129 ;; within or part of the marked region.
131 ;; Whenever an existing menu is updated, the descriptions from
132 ;; that menu are incorporated into the new menu. This is done by copying
133 ;; descriptions from the existing menu to the entries in the new menu
134 ;; that have the same node names. If the node names are different, the
135 ;; descriptions are not copied to the new menu.
137 ;; Menu entries that refer to other Info files are removed since they
138 ;; are not a node within current buffer. This is a deficiency.
140 ;; The `texinfo-all-menus-update' function runs `texinfo-make-menu'
141 ;; on the whole buffer.
143 ;; The `texinfo-master-menu' function creates an extended menu located
144 ;; after the top node. (The file must have a top node.) This
145 ;; function works only on Texinfo files all of whose menus are
146 ;; present in a single file; use `texinfo-multiple-files-update' for
147 ;; multi-file manuals. The function constructs a master menu that
148 ;; includes every entry from every other menu. Use this command to
149 ;; create or update the @detailmenu menu after you've created or
150 ;; updated all the menus in the file, including the menu in the Top
151 ;; node, using the `texinfo-make-menu' or the `texinfo-all-menus-update'
152 ;; command.
154 ;; The `texinfo-indent-menu-description' function indents every
155 ;; description in the menu following point, to the specified column.
156 ;; Non-nil argument (prefix, if interactive) means indent every
157 ;; description in every menu in the region. This function does not
158 ;; indent second and subsequent lines of a multi-line description.
160 ;; The `texinfo-insert-node-lines' function inserts `@node' before the
161 ;; `@chapter', `@section', and such like lines of a region in a Texinfo
162 ;; file where the `@node' lines are missing.
163 ;;
164 ;; With a non-nil argument (prefix, if interactive), the function not
165 ;; only inserts `@node' lines but also inserts the chapter or section
166 ;; titles as the names of the corresponding nodes; and inserts titles
167 ;; as node names in pre-existing `@node' lines that lack names.
168 ;;
169 ;; Since node names should be more concise than section or chapter
170 ;; titles, you will usually want to manually edit node names so inserted.
172 \f
173 ;;; Code:
175 (require 'texinfo)
178 (defvar texinfo-master-menu-header
179 " --- The Detailed Node Listing ---\n"
180 "String inserted before lower level entries in Texinfo master menu.
181 It comes after the chapter-level menu entries.")
183 ;; We used to look for just sub, but that found @subtitle.
184 (defvar texinfo-section-types-regexp
185 "^@\\(chapter \\|sect\\|subs\\|subh\\|unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
186 "Regexp matching chapter, section, other headings (but not the top node).")
188 (defvar texinfo-section-level-regexp
189 (regexp-opt (texinfo-filter 3 texinfo-section-list))
190 "Regular expression matching just the Texinfo section level headings.")
192 (defvar texinfo-subsection-level-regexp
193 (regexp-opt (texinfo-filter 4 texinfo-section-list))
194 "Regular expression matching just the Texinfo subsection level headings.")
196 (defvar texinfo-subsubsection-level-regexp
197 (regexp-opt (texinfo-filter 5 texinfo-section-list))
198 "Regular expression matching just the Texinfo subsubsection level headings.")
200 (defvar texinfo-update-menu-same-level-regexps
201 '((1 . "top[ \t]+")
202 (2 . (concat "\\(^@\\)\\(" texinfo-chapter-level-regexp "\\)\\>[ \t]*"))
203 (3 . (concat "\\(^@\\)\\(" texinfo-section-level-regexp "\\)\\>[ \t]*"))
204 (4 . (concat "\\(^@\\)\\(" texinfo-subsection-level-regexp "\\)\\>[ \t]+"))
205 (5 . (concat "\\(^@\\)\\(" texinfo-subsubsection-level-regexp "\\)\\>[ \t]+")))
206 "Regexps for searching for same level sections in a Texinfo file.
207 The keys are strings specifying the general hierarchical level in the
208 document; the values are regular expressions.")
210 (defvar texinfo-update-menu-higher-regexps
211 '((1 . "^@node [ \t]*DIR")
212 (2 . "^@node [ \t]*top[ \t]*\\(,\\|$\\)")
213 (3 .
214 (concat
215 "\\(^@\\("
216 texinfo-chapter-level-regexp
217 "\\)\\>[ \t]*\\)"))
218 (4 .
219 (concat
220 "\\(^@\\("
221 texinfo-section-level-regexp
222 "\\|"
223 texinfo-chapter-level-regexp
224 "\\)\\>[ \t]*\\)"))
225 (5 .
226 (concat
227 "\\(^@\\("
228 texinfo-subsection-level-regexp
229 "\\|"
230 texinfo-section-level-regexp
231 "\\|"
232 texinfo-chapter-level-regexp
233 "\\)\\>[ \t]*\\)")))
234 "Regexps for searching for higher level sections in a Texinfo file.
235 The keys are strings specifying the general hierarchical level in the
236 document; the values are regular expressions.")
238 (defvar texinfo-update-menu-lower-regexps
239 '((1 .
240 (concat
241 "\\(^@\\("
242 texinfo-chapter-level-regexp
243 "\\|"
244 texinfo-section-level-regexp
245 "\\|"
246 texinfo-subsection-level-regexp
247 "\\|"
248 texinfo-subsubsection-level-regexp
249 "\\)\\>[ \t]*\\)"))
250 (2 .
251 (concat
252 "\\(^@\\("
253 texinfo-section-level-regexp
254 "\\|"
255 texinfo-subsection-level-regexp
256 "\\|"
257 texinfo-subsubsection-level-regexp
258 "\\)\\>[ \t]*\\)"))
259 (3 .
260 (concat
261 "\\(^@\\("
262 texinfo-subsection-level-regexp
263 "\\|"
264 texinfo-subsubsection-level-regexp
265 "\\)\\>[ \t]+\\)"))
266 (4 .
267 (concat
268 "\\(^@\\("
269 texinfo-subsubsection-level-regexp
270 "\\)\\>[ \t]+\\)"))
271 ;; There's nothing below 5, use a bogus regexp that can't match.
272 (5 . "a\\(^\\)"))
273 "Regexps for searching for lower level sections in a Texinfo file.
274 The keys are strings specifying the general hierarchical level in the
275 document; the values are regular expressions.")
277 \f
278 (defun texinfo-make-menu (&optional beginning end)
279 "Without any prefix argument, make or update a menu.
280 Make the menu for the section enclosing the node found following point.
282 A prefix argument means make or update menus
283 for nodes within or part of the marked region.
285 Whenever a menu exists, and is being updated, the descriptions that
286 are associated with node names in the pre-existing menu are
287 incorporated into the new menu.
289 Leaves trailing whitespace in a menu that lacks descriptions, so
290 descriptions will format well. In general, a menu should contain
291 descriptions, because node names and section titles are often too
292 short to explain a node well."
294 (interactive
295 (if prefix-arg
296 (list (point) (mark))))
297 (if (null beginning)
298 (let ((level (texinfo-hierarchic-level)))
299 (texinfo-make-one-menu level)
300 (message "Menu updated"))
301 ;; else
302 (message "Making or updating menus in %s... " (buffer-name))
303 (save-excursion
304 (goto-char (min beginning end))
305 ;; find section type following point
306 (let ((level (texinfo-hierarchic-level))
307 (region-end-marker (make-marker)))
308 (set-marker region-end-marker (max beginning end))
309 (save-restriction
310 (widen)
312 (while (texinfo-find-lower-level-node
313 level (marker-position region-end-marker))
314 (setq level (texinfo-hierarchic-level)) ; new, lower level
315 (texinfo-make-one-menu level))
317 (while (and (< (point) (marker-position region-end-marker))
318 (texinfo-find-higher-level-node
319 level (marker-position region-end-marker)))
320 (setq level (texinfo-hierarchic-level))
321 ;; Don't allow texinfo-find-higher-level-node
322 ;; to find the same node again.
323 (forward-line 1)
324 (while (texinfo-find-lower-level-node
325 level (marker-position region-end-marker))
326 (setq level (texinfo-hierarchic-level)) ; new, lower level
327 (texinfo-make-one-menu level))))))
328 (message "Making or updating menus in %s...done" (buffer-name))))
330 (defun texinfo-make-one-menu (level)
331 "Make a menu of all the appropriate nodes in this section.
332 `Appropriate nodes' are those associated with sections that are
333 at the level specified by LEVEL. Point is left at the end of menu."
334 (let*
335 ((case-fold-search t)
336 (beginning
337 (save-excursion
338 (goto-char (texinfo-update-menu-region-beginning level))
339 (end-of-line)
340 (point)))
341 (end (texinfo-update-menu-region-end level))
342 (first (texinfo-menu-first-node beginning end))
343 (node-name (progn
344 (goto-char beginning)
345 (beginning-of-line)
346 (texinfo-copy-node-name)))
347 (new-menu-list (texinfo-make-menu-list beginning end level)))
348 (when (texinfo-old-menu-p beginning first)
349 (texinfo-incorporate-descriptions new-menu-list)
350 (texinfo-incorporate-menu-entry-names new-menu-list)
351 (texinfo-delete-old-menu beginning first))
352 (texinfo-insert-menu new-menu-list node-name)))
354 (defun texinfo-all-menus-update (&optional update-all-nodes-p)
355 "Update every regular menu in a Texinfo file.
356 Update pre-existing master menu, if there is one.
358 Only single-file manuals are supported by this function. For
359 multi-file manuals, use `texinfo-multiple-files-update'.
361 If called with a non-nil argument, this function first updates all the
362 nodes in the buffer before updating the menus. Do NOT invoke this
363 command with an argument if your Texinfo file uses @node lines without
364 the `Next', `Previous', and `Up' pointers!
366 Indents the first line of descriptions, and leaves trailing whitespace
367 in a menu that lacks descriptions, so descriptions will format well.
368 In general, a menu should contain descriptions, because node names and
369 section titles are often too short to explain a node well."
370 (interactive "P")
371 (let ((case-fold-search t)
372 master-menu-p)
373 (save-excursion
374 (push-mark (point-max) t)
375 (goto-char (point-min))
376 (message "Checking for a master menu in %s ... "(buffer-name))
377 (save-excursion
378 (when (search-forward texinfo-master-menu-header nil t)
379 ;; Check if @detailmenu kludge is used;
380 ;; if so, leave point before @detailmenu.
381 (search-backward "\n@detailmenu" (line-beginning-position -2) t)
382 ;; Remove detailed master menu listing
383 (setq master-menu-p t)
384 (goto-char (match-beginning 0))
385 (let ((end-of-detailed-menu-descriptions
386 (save-excursion ; beginning of end menu line
387 (goto-char (texinfo-menu-end))
388 (beginning-of-line) (forward-char -1)
389 (point))))
390 (delete-region (point) end-of-detailed-menu-descriptions))))
392 (when update-all-nodes-p
393 (message "Updating all nodes in %s ... " (buffer-name))
394 (texinfo-update-node (point-min) (point-max)))
396 (message "Updating all menus in %s ... " (buffer-name))
397 (texinfo-make-menu (point-max) (point-min))
399 (when master-menu-p
400 (message "Updating the master menu in %s... " (buffer-name))
401 (texinfo-master-menu nil)))
403 (message "Done...updated all the menus. You may save the buffer.")))
405 (defun texinfo-find-lower-level-node (level region-end)
406 "Search forward from point for node at any level lower than LEVEL.
407 Search is limited to the end of the marked region, REGION-END,
408 and to the end of the menu region for the level.
410 Return t if the node is found, else nil. Leave point at the beginning
411 of the node if one is found; else do not move point."
412 (let ((case-fold-search t))
413 (if (and (< (point) region-end)
414 (re-search-forward
415 (concat
416 "\\(^@node\\).*\n" ; match node line
417 "\\(\\(\\(^@c\\).*\n\\)" ; match comment line, if any
418 "\\|" ; or
419 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
420 "\\|" ; or
421 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
422 "\\)?" ; end of expression
423 (eval (cdr (assoc level texinfo-update-menu-lower-regexps))))
424 ;; the next higher level node marks the end of this
425 ;; section, and no lower level node will be found beyond
426 ;; this position even if region-end is farther off
427 (texinfo-update-menu-region-end level)
428 t))
429 (goto-char (match-beginning 1)))))
431 (defun texinfo-find-higher-level-node (level region-end)
432 "Search forward from point for node at any higher level than argument LEVEL.
433 Search is limited to the end of the marked region, REGION-END.
435 Return t if the node is found, else nil. Leave point at the beginning
436 of the node if one is found; else do not move point.
438 A `@node' line starting at point does count as a match;
439 if the match is found there, the value is t and point does not move."
441 (let ((case-fold-search t))
442 (cond
443 ((< level 3)
444 (if (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" region-end t)
445 (progn (beginning-of-line) t)))
446 (t
447 (when (re-search-forward
448 (concat
449 "\\(^@node\\).*\n" ; match node line
450 "\\(\\(\\(^@c\\).*\n\\)" ; match comment line, if any
451 "\\|" ; or
452 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
453 "\\|" ; or
454 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
455 "\\)?" ; end of expression
456 (eval (cdr (assoc level texinfo-update-menu-higher-regexps))))
457 region-end t)
458 (beginning-of-line) t)))))
460 \f
461 ;;; Making the list of new menu entries
463 (defun texinfo-make-menu-list (beginning end level)
464 "Make a list of node names and their descriptions.
465 Point is left at the end of the menu region, but the menu is not inserted.
467 First argument is position from which to start making menu list;
468 second argument is end of region in which to try to locate entries;
469 third argument is the level of the nodes that are the entries.
471 Node names and descriptions are dotted pairs of strings. Each pair is
472 an element of the list. If the description does not exist, the
473 element consists only of the node name."
474 (goto-char beginning)
475 (let (new-menu-list)
476 (while (texinfo-menu-locate-entry-p level end)
477 (push (cons
478 (texinfo-copy-node-name)
479 (prog1 "" (forward-line 1)))
480 ;; Use following to insert section titles automatically.
481 ;; (texinfo-copy-section-title))
482 new-menu-list))
483 (nreverse new-menu-list)))
485 (defun texinfo-menu-locate-entry-p (level search-end)
486 "Find a node that will be part of menu for this section.
487 First argument is a string such as \"section\" specifying the general
488 hierarchical level of the menu; second argument is a position
489 specifying the end of the search.
491 The function returns t if the node is found, else nil. It searches
492 forward from point, and leaves point at the beginning of the node.
494 The function finds entries of the same type. Thus `subsections' and
495 `unnumberedsubsecs' will appear in the same menu."
496 (let ((case-fold-search t))
497 (if (re-search-forward
498 (concat
499 "\\(^@node\\).*\n" ; match node line
500 "\\(\\(\\(^@c\\).*\n\\)" ; match comment line, if any
501 "\\|" ; or
502 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
503 "\\|" ; or
504 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
505 "\\)?" ; end of expression
506 (eval
507 (cdr (assoc level texinfo-update-menu-same-level-regexps))))
508 search-end
509 t)
510 (goto-char (match-beginning 1)))))
512 (defun texinfo-copy-node-name ()
513 "Return the node name as a string.
515 Start with point at the beginning of the node line; copy the text
516 after the node command up to the first comma on the line, if any, and
517 return the text as a string. Leaves point at the beginning of the
518 line. If there is no node name, returns an empty string."
520 (save-excursion
521 (buffer-substring
522 (progn (forward-word 1) ; skip over node command
523 (skip-chars-forward " \t") ; and over spaces
524 (point))
525 (if (search-forward "," (line-end-position) t) ; bound search
526 (1- (point))
527 (end-of-line) (point)))))
529 (defun texinfo-copy-section-title ()
530 "Return the title of the section as a string.
531 The title is used as a description line in the menu when one does not
532 already exist.
534 Move point to the beginning of the appropriate section line by going
535 to the start of the text matched by last regexp searched for, which
536 must have been done by `texinfo-menu-locate-entry-p'."
538 ;; could use the same re-search as in `texinfo-menu-locate-entry-p'
539 ;; instead of using `match-beginning'; such a variation would be
540 ;; more general, but would waste information already collected
542 (goto-char (match-beginning 7)) ; match section name
544 (buffer-substring
545 (progn (forward-word 1) ; skip over section type
546 (skip-chars-forward " \t") ; and over spaces
547 (point))
548 (progn (end-of-line) (point))))
550 \f
551 ;;; Handling the old menu
553 (defun texinfo-old-menu-p (beginning first)
554 "Move point to the beginning of the menu for this section, if any.
555 Otherwise move point to the end of the first node of this section.
556 Return t if a menu is found, nil otherwise.
558 First argument is the position of the beginning of the section in which
559 the menu will be located; second argument is the position of the first
560 node within the section.
562 If no menu is found, the function inserts two newlines just before the
563 end of the section, and leaves point there where a menu ought to be."
564 (goto-char beginning)
565 (if (re-search-forward "^@menu" first 'goto-end)
567 (insert "\n\n") (forward-line -2) nil))
569 (defun texinfo-incorporate-descriptions (new-menu-list)
570 "Copy the old menu line descriptions that exist to the new menu.
572 Point must be at beginning of old menu.
574 If the node-name of the new menu is found in the old menu, insert the
575 old description into the new entry.
577 For this function, the new menu is a list made up of lists of dotted
578 pairs in which the first element of the pair is the node name and the
579 second element the description. The new menu is changed destructively.
580 The old menu is the menu as it appears in the Texinfo file."
582 (let ((end-of-menu (texinfo-menu-end)))
583 (dolist (new-menu new-menu-list new-menu-list)
584 (save-excursion ; keep point at beginning of menu
585 (when (re-search-forward
586 ;; Existing nodes can have the form
587 ;; * NODE NAME:: DESCRIPTION
588 ;; or
589 ;; * MENU ITEM: NODE NAME. DESCRIPTION.
590 ;;
591 ;; Recognize both when looking for the description.
592 (concat "\\* \\(" ; so only menu entries are found
593 (regexp-quote (car new-menu)) "::"
594 "\\|"
595 ".*: " (regexp-quote (car new-menu)) "[.,\t\n]"
596 "\\)"
597 ) ; so only complete entries are found
598 end-of-menu
599 t)
600 (setcdr new-menu (texinfo-menu-copy-old-description end-of-menu)))))))
602 (defun texinfo-incorporate-menu-entry-names (new-menu-list)
603 "Copy any old menu entry names to the new menu.
605 Point must be at beginning of old menu.
607 If the node-name of the new menu entry cannot be found in the old
608 menu, do nothing.
610 For this function, the new menu is a list made up of lists of dotted
611 pairs in which the first element of the pair is the node name and the
612 second element is the description (or nil).
614 If we find an existing menu entry name, we change the first element of
615 the pair to be another dotted pair in which the car is the menu entry
616 name and the cdr is the node name.
618 NEW-MENU-LIST is changed destructively. The old menu is the menu as it
619 appears in the texinfo file."
621 (let ((end-of-menu (texinfo-menu-end)))
622 (dolist (new-menu new-menu-list new-menu-list)
623 (save-excursion ; keep point at beginning of menu
624 (if (re-search-forward
625 ;; Existing nodes can have the form
626 ;; * NODE NAME:: DESCRIPTION
627 ;; or
628 ;; * MENU ITEM: NODE NAME. DESCRIPTION.
629 ;;
630 ;; We're interested in the second case.
631 (concat "\\* " ; so only menu entries are found
632 "\\(.*\\): " (regexp-quote (car new-menu))
633 "[.,\t\n]")
634 end-of-menu
635 t)
636 (setcar
637 new-menu ; replace the node name
638 (cons (buffer-substring (match-beginning 1) (match-end 1))
639 (car new-menu))))))))
641 (defun texinfo-menu-copy-old-description (end-of-menu)
642 "Return description field of old menu line as string.
643 Point must be located just after the node name. Point left before description.
644 Single argument, END-OF-MENU, is position limiting search."
645 (skip-chars-forward "[:.,\t\n ]+")
646 ;; don't copy a carriage return at line beginning with asterisk!
647 ;; don't copy @detailmenu or @end menu or @ignore as descriptions!
648 ;; do copy a description that begins with an `@'!
649 ;; !! Known bug: does not copy descriptions starting with ^|\{?* etc.
650 (if (and (looking-at "\\(\\w+\\|@\\)")
651 (not (looking-at
652 "\\(^\\* \\|^@detailmenu\\|^@end menu\\|^@ignore\\)")))
653 (buffer-substring
654 (point)
655 (save-excursion
656 (re-search-forward "\\(^\\* \\|^@ignore\\|^@end menu\\)" end-of-menu t)
657 (line-end-position 0))) ; end of last description line
658 ""))
660 (defun texinfo-menu-end ()
661 "Return position of end of menu, but don't move point.
662 Signal an error if not end of menu."
663 (save-excursion
664 (if (re-search-forward "^@end menu" nil t)
665 (point)
666 (error "Menu does not have an end"))))
668 (defun texinfo-delete-old-menu (beginning first)
669 "Delete the old menu. Point must be in or after menu.
670 First argument is position of the beginning of the section in which
671 the menu will be located; second argument is the position of the first
672 node within the section."
673 ;; No third arg to search, so error if search fails.
674 (re-search-backward "^@menu" beginning)
675 (delete-region (point)
676 (save-excursion
677 (re-search-forward "^@end menu" first)
678 (point))))
680 \f
681 ;;; Inserting new menu
683 ;; try 32, but perhaps 24 is better
684 (defvar texinfo-column-for-description 32
685 "Column at which descriptions start in a Texinfo menu.")
687 (defun texinfo-insert-menu (menu-list node-name)
688 "Insert formatted menu at point.
689 Indents the first line of descriptions, if any, to the value of
690 texinfo-column-for-description. Indenting leaves trailing whitespace
691 in a menu that lacks descriptions, so descriptions will format well.
692 In general, a menu should contain descriptions, because node names and
693 section titles are often too short to explain a node well.
695 MENU-LIST has form:
697 \(\(\"node-name1\" . \"description\"\)
698 \(\"node-name2\" . \"description\"\) ... \)
700 However, the description field might be nil.
702 Also, the node-name field might itself be a dotted pair (call it P) of
703 strings instead of just a string. In that case, the car of P
704 is the menu entry name, and the cdr of P is the node name."
706 (insert "@menu\n")
707 (dolist (menu menu-list)
708 ;; Every menu entry starts with a star and a space.
709 (insert "* ")
711 ;; Insert the node name (and menu entry name, if present).
712 (let ((node-part (car menu)))
713 (if (stringp node-part)
714 ;; "Double colon" entry line; menu entry and node name are the same,
715 (insert (format "%s::" node-part))
716 ;; "Single colon" entry line; menu entry and node name are different.
717 (insert (format "%s: %s." (car node-part) (cdr node-part)))))
719 ;; Insert the description, if present.
720 (when (> (length (cdr menu)) 0)
721 ;; Move to right place.
722 (indent-to texinfo-column-for-description 2)
723 ;; Insert description.
724 (insert (format "%s" (cdr menu))))
726 (insert "\n")) ; end this menu entry
727 (insert "@end menu")
728 (let ((level (texinfo-hierarchic-level)))
729 (message
730 "Updated level \"%s\" menu following node: %s ... " level node-name)))
732 \f
733 ;;; Starting menu descriptions by inserting titles
735 (defun texinfo-start-menu-description ()
736 "In this menu entry, insert the node's section title as a description.
737 Position point at beginning of description ready for editing.
738 Do not insert a title if the line contains an existing description.
740 You will need to edit the inserted text since a useful description
741 complements the node name rather than repeats it as a title does."
743 (interactive)
744 (let (beginning end node-name title)
745 (save-excursion
746 (beginning-of-line)
747 (if (search-forward "* " (line-end-position) t)
748 (progn (skip-chars-forward " \t")
749 (setq beginning (point)))
750 (error "This is not a line in a menu"))
752 (cond
753 ;; "Double colon" entry line; menu entry and node name are the same,
754 ((search-forward "::" (line-end-position) t)
755 (if (looking-at "[ \t]*[^ \t\n]+")
756 (error "Descriptive text already exists"))
757 (skip-chars-backward ": \t")
758 (setq node-name (buffer-substring beginning (point))))
760 ;; "Single colon" entry line; menu entry and node name are different.
761 ((search-forward ":" (line-end-position) t)
762 (skip-chars-forward " \t")
763 (setq beginning (point))
764 ;; Menu entry line ends in a period, comma, or tab.
765 (if (re-search-forward "[.,\t]" (line-beginning-position 2) t)
766 (progn
767 (if (looking-at "[ \t]*[^ \t\n]+")
768 (error "Descriptive text already exists"))
769 (skip-chars-backward "., \t")
770 (setq node-name (buffer-substring beginning (point))))
771 ;; Menu entry line ends in a return.
772 (re-search-forward ".*\n" (line-beginning-position 2) t)
773 (skip-chars-backward " \t\n")
774 (setq node-name (buffer-substring beginning (point)))
775 (if (= 0 (length node-name))
776 (error "No node name on this line")
777 (insert "."))))
778 (t (error "No node name on this line")))
779 ;; Search for node that matches node name, and copy the section title.
780 (if (re-search-forward
781 (concat
782 "^@node[ \t]+"
783 (regexp-quote node-name)
784 ".*\n" ; match node line
785 "\\("
786 "\\(\\(^@c \\|^@comment\\).*\n\\)" ; match comment line, if any
787 "\\|" ; or
788 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
789 "\\|" ; or
790 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
791 "\\)?" ; end of expression
793 nil t)
794 (setq title
795 (buffer-substring
796 ;; skip over section type
797 (progn (forward-word 1)
798 ;; and over spaces
799 (skip-chars-forward " \t")
800 (point))
801 (progn (end-of-line)
802 (skip-chars-backward " \t")
803 (point))))
804 (error "Cannot find node to match node name in menu entry")))
805 ;; Return point to the menu and insert the title.
806 (end-of-line)
807 (delete-region
808 (point)
809 (save-excursion (skip-chars-backward " \t") (point)))
810 (indent-to texinfo-column-for-description 2)
811 (save-excursion (insert title))))
813 \f
814 ;;; Handling description indentation
816 ;; Since the make-menu functions indent descriptions, these functions
817 ;; are useful primarily for indenting a single menu specially.
819 (defun texinfo-indent-menu-description (column &optional region-p)
820 "Indent every description in menu following point to COLUMN.
821 Non-nil argument (prefix, if interactive) means indent every
822 description in every menu in the region. Does not indent second and
823 subsequent lines of a multi-line description."
825 (interactive
826 "nIndent menu descriptions to (column number): \nP")
827 (save-excursion
828 (save-restriction
829 (widen)
830 (if (not region-p)
831 (progn
832 (re-search-forward "^@menu")
833 (texinfo-menu-indent-description column)
834 (message
835 "Indented descriptions in menu. You may save the buffer."))
836 ;;else
837 (message "Indenting every menu description in region... ")
838 (goto-char (region-beginning))
839 (while (and (< (point) (region-end))
840 (texinfo-locate-menu-p))
841 (forward-line 1)
842 (texinfo-menu-indent-description column))
843 (message "Indenting done. You may save the buffer.")))))
845 (defun texinfo-menu-indent-description (to-column-number)
846 "Indent the Texinfo file menu description to TO-COLUMN-NUMBER.
847 Start with point just after the word `menu' in the `@menu' line and
848 leave point on the line before the `@end menu' line. Does not indent
849 second and subsequent lines of a multi-line description."
850 (let* ((beginning-of-next-line (point)))
851 (while (< beginning-of-next-line
852 (save-excursion ; beginning of end menu line
853 (goto-char (texinfo-menu-end))
854 (beginning-of-line)
855 (point)))
857 (when (re-search-forward "\\* \\(.*::\\|.*: [^.,\t\n]+[.,\t]\\)"
858 (texinfo-menu-end)
859 t)
860 (let ((beginning-white-space (point)))
861 (skip-chars-forward " \t") ; skip over spaces
862 (if (looking-at "\\(@\\|\\w\\)+") ; if there is text
863 (progn
864 ;; remove pre-existing indentation
865 (delete-region beginning-white-space (point))
866 (indent-to-column to-column-number)))))
867 ;; position point at beginning of next line
868 (forward-line 1)
869 (setq beginning-of-next-line (point)))))
871 \f
872 ;;; Making the master menu
874 (defun texinfo-master-menu (update-all-nodes-menus-p)
875 "Make a master menu for a whole Texinfo file.
876 Remove pre-existing master menu, if there is one.
878 This function supports only single-file manuals. For multi-file
879 manuals, use `texinfo-multiple-files-update'.
881 This function creates or updates the @detailmenu section of a
882 master menu that follows the Top node. It replaces any existing
883 detailed menu that follows the top node. The detailed menu
884 includes every entry from all the other menus. By default, the
885 existing menus, including the menu in the Top node, are not
886 updated according to the buffer contents, so all the menus should
887 be updated first using `texinfo-make-menu' or
888 `texinfo-all-menus-update', which see. Alternatively, invoke
889 this function with a prefix argument, see below.
891 Non-nil, non-numeric argument (C-u prefix, if interactive) means
892 first update all existing menus in the buffer (incorporating
893 descriptions from pre-existing menus) before it constructs the
894 master menu. If the argument is numeric (e.g., \"C-u 2\"),
895 update all existing nodes as well, by calling
896 \`texinfo-update-node' on the entire file. Warning: do NOT
897 invoke with a numeric argument if your Texinfo file uses @node
898 lines without the `Next', `Previous', `Up' pointers, as the
899 result could be an invalid Texinfo file!
901 The function removes and recreates the detailed part of an already
902 existing master menu. This action assumes that the pre-existing
903 master menu uses the standard `texinfo-master-menu-header' for the
904 detailed menu.
906 The master menu has the following format, which is adapted from the
907 recommendation in the Texinfo Manual:
909 * The first part contains the major nodes in the Texinfo file: the
910 nodes for the chapters, chapter-like sections, and the major
911 appendices. This includes the indices, so long as they are in
912 chapter-like sections, such as unnumbered sections.
914 * The second and subsequent parts contain a listing of the other,
915 lower level menus, in order. This way, an inquirer can go
916 directly to a particular node if he or she is searching for
917 specific information.
919 Each of the menus in the detailed node listing is introduced by the
920 title of the section containing the menu.
922 Indents the first line of descriptions, and leaves trailing whitespace
923 in a menu that lacks descriptions, so descriptions will format well.
924 In general, a menu should contain descriptions, because node names and
925 section titles are often too short to explain a node well."
927 (interactive "P")
928 (let ((case-fold-search t))
929 (widen)
930 (goto-char (point-min))
932 ;; Move point to location after `top'.
933 (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
934 (error "This buffer needs a Top node"))
936 (let ((first-chapter
937 (save-excursion
938 (or (re-search-forward "^@node" nil t)
939 (error "Too few nodes for a master menu"))
940 (point))))
941 (if (search-forward texinfo-master-menu-header first-chapter t)
942 (progn
943 ;; Check if @detailmenu kludge is used;
944 ;; if so, leave point before @detailmenu.
945 (search-backward "\n@detailmenu" (line-beginning-position -2) t)
946 ;; Remove detailed master menu listing
947 (goto-char (match-beginning 0))
948 (let ((end-of-detailed-menu-descriptions
949 (save-excursion ; beginning of end menu line
950 (goto-char (texinfo-menu-end))
951 (beginning-of-line) (forward-char -1)
952 (point))))
953 (delete-region (point) end-of-detailed-menu-descriptions)))))
955 (if update-all-nodes-menus-p
956 (progn
957 (when (numberp update-all-nodes-menus-p)
958 (message
959 "Making a master menu in %s ...first updating all nodes... "
960 (buffer-name))
961 (texinfo-update-node (point-min) (point-max)))
962 (message "Updating all menus in %s ... " (buffer-name))
963 (texinfo-make-menu (point-min) (point-max))))
965 (message "Now making the master menu in %s... " (buffer-name))
966 (goto-char (point-min))
967 (texinfo-insert-master-menu-list
968 (texinfo-master-menu-list))
970 ;; Remove extra newlines that texinfo-insert-master-menu-list
971 ;; may have inserted.
973 (save-excursion
974 (goto-char (point-min))
976 (if (search-forward texinfo-master-menu-header nil t)
977 (progn
978 (goto-char (match-beginning 0))
979 ;; Check if @detailmenu kludge is used;
980 ;; if so, leave point before @detailmenu.
981 (search-backward "\n@detailmenu" (line-beginning-position -2) t)
982 (insert "\n")
983 (delete-blank-lines)
984 (goto-char (point-min))))
986 (re-search-forward "^@menu")
987 (forward-line -1)
988 (delete-blank-lines)
990 (re-search-forward "^@end menu")
991 (forward-line 1)
992 (delete-blank-lines))
994 (message
995 "Done...completed making master menu. You may save the buffer.")))
997 (defun texinfo-master-menu-list ()
998 "Return a list of menu entries and header lines for the master menu.
1000 Start with the menu for chapters and indices and then find each
1001 following menu and the title of the node preceding that menu.
1003 The master menu list has this form:
1005 \(\(\(... \"entry-1-2\" \"entry-1\"\) \"title-1\"\)
1006 \(\(... \"entry-2-2\" \"entry-2-1\"\) \"title-2\"\)
1007 ...\)
1009 However, there does not need to be a title field."
1011 (let (master-menu-list)
1012 (while (texinfo-locate-menu-p)
1013 (push (list (texinfo-copy-menu) (texinfo-copy-menu-title))
1014 master-menu-list))
1015 (nreverse master-menu-list)))
1017 (defun texinfo-insert-master-menu-list (master-menu-list)
1018 "Format and insert the master menu in the current buffer."
1019 (goto-char (point-min))
1020 ;; Insert a master menu only after `Top' node and before next node
1021 ;; \(or include file if there is no next node\).
1022 (unless (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t)
1023 (error "This buffer needs a Top node"))
1024 (let ((first-chapter
1025 (save-excursion (re-search-forward "^@node\\|^@include") (point))))
1026 (unless (re-search-forward "^@menu" first-chapter t)
1027 (error "Buffer lacks a menu in its first node; create it, then run me again")))
1028 (beginning-of-line)
1029 (delete-region ; buffer must have ordinary top menu
1030 (point)
1031 (save-excursion (re-search-forward "^@end menu") (point)))
1033 (save-excursion
1034 ;; `master-menu-inserted-p' is a kludge to tell
1035 ;; whether to insert @end detailmenu (see bleow)
1036 (let (master-menu-inserted-p)
1037 ;; Handle top of menu
1038 (insert "\n@menu\n")
1039 ;; Insert chapter menu entries. Tell user what is going on.
1040 (message "Inserting chapter menu entry: %s ... "
1041 (car (car master-menu-list)))
1042 (dolist (entry (reverse (car (car master-menu-list))))
1043 (insert "* " entry "\n"))
1045 (setq master-menu-list (cdr master-menu-list))
1047 ;; Only insert detailed master menu if there is one....
1048 (if (car (car master-menu-list))
1049 (progn (setq master-menu-inserted-p t)
1050 (insert (concat "\n@detailmenu\n"
1051 texinfo-master-menu-header))))
1053 ;; @detailmenu added 5 Sept 1996 to `texinfo-master-menu-header'
1054 ;; at Karl Berry's request to avert a bug in `makeinfo';
1055 ;; all agree this is a bad kludge and should eventually be removed.
1056 ;; @detailmenu ... @end detailmenu is a noop in `texinfmt.el'.
1057 ;; See @end detailmenu below;
1058 ;; also see `texinfo-all-menus-update' above, `texinfo-master-menu',
1059 ;; `texinfo-multiple-files-update'.
1061 ;; Now, insert all the other menus
1063 ;; The menu master-menu-list has a form like this:
1064 ;; ((("beta" "alpha") "title-A")
1065 ;; (("delta" "gamma") "title-B"))
1067 (dolist (menu master-menu-list)
1069 (message "Inserting menu for %s .... " (cadr menu))
1070 ;; insert title of menu section
1071 (insert "\n" (cadr menu) "\n\n")
1073 ;; insert each menu entry
1074 (dolist (entry (reverse (car menu)))
1075 (insert "* " entry "\n")))
1077 ;; Finish menu
1079 ;; @detailmenu (see note above)
1080 ;; Only insert @end detailmenu if a master menu was inserted.
1081 (if master-menu-inserted-p
1082 (insert "\n@end detailmenu"))
1083 (insert "\n@end menu\n\n"))))
1085 (defun texinfo-locate-menu-p ()
1086 "Find the next menu in the texinfo file.
1087 If found, leave point after word `menu' on the `@menu' line, and return t.
1088 If a menu is not found, do not move point and return nil."
1089 (re-search-forward "\\(^@menu\\)" nil t))
1091 (defun texinfo-copy-menu-title ()
1092 "Return the title of the section preceding the menu as a string.
1093 If such a title cannot be found, return an empty string. Do not move
1094 point."
1095 (let ((case-fold-search t))
1096 (save-excursion
1097 (if (re-search-backward
1098 (concat
1099 "\\(^@top"
1100 "\\|" ; or
1101 texinfo-section-types-regexp ; all other section types
1102 "\\)")
1103 nil
1104 t)
1105 (progn
1106 (beginning-of-line)
1107 (forward-word 1) ; skip over section type
1108 (skip-chars-forward " \t") ; and over spaces
1109 (buffer-substring
1110 (point)
1111 (progn (end-of-line) (point))))
1112 ""))))
1114 (defun texinfo-copy-menu ()
1115 "Return the entries of an existing menu as a list.
1116 Start with point just after the word `menu' in the `@menu' line
1117 and leave point on the line before the `@end menu' line."
1118 (let* (this-menu-list
1119 (end-of-menu (texinfo-menu-end)) ; position of end of `@end menu'
1120 (last-entry (save-excursion ; position of beginning of
1121 ; last `* ' entry
1122 (goto-char end-of-menu)
1123 ;; handle multi-line description
1124 (if (not (re-search-backward "^\\* " nil t))
1125 (error "No entries in menu"))
1126 (point))))
1127 (while (< (point) last-entry)
1128 (if (re-search-forward "^\\* " end-of-menu t)
1129 (push (buffer-substring
1130 (point)
1131 ;; copy multi-line descriptions
1132 (save-excursion
1133 (re-search-forward "\\(^\\* \\|^@e\\)" nil t)
1134 (- (point) 3)))
1135 this-menu-list)))
1136 this-menu-list))
1138 \f
1139 ;;; Determining the hierarchical level in the texinfo file
1141 (defun texinfo-specific-section-type ()
1142 "Return the specific type of next section, as a string.
1143 For example, \"unnumberedsubsec\". Return \"top\" for top node.
1145 Searches forward for a section. Hence, point must be before the
1146 section whose type will be found. Does not move point. Signal an
1147 error if the node is not the top node and a section is not found."
1148 (let* ((case-fold-search t)
1149 ;; The Texinfo manual has a second Top node inside @verbatim
1150 ;; near the end, which dupes us into thinking we are at top
1151 ;; level, no matter where we are when invoked. We don't
1152 ;; really grok @verbatim, so we cheat: only consider us to be
1153 ;; at top level if the position of the Top node we found is
1154 ;; before any other sectioning command.
1155 (top-pos (save-excursion
1156 (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)"
1157 ;; Following search limit causes a bug
1158 ;;(line-end-position)
1159 nil
1160 t)))
1161 (sec-pos (save-excursion
1162 (re-search-forward texinfo-section-types-regexp nil t)))
1163 sec-name)
1164 (if sec-pos
1165 (save-excursion
1166 (goto-char sec-pos)
1167 (setq sec-name (buffer-substring-no-properties
1168 (progn (beginning-of-line) ; copy its name
1169 (1+ (point)))
1170 (progn (forward-word 1)
1171 (point))))))
1172 (cond
1173 ((or sec-pos top-pos)
1174 (if (and top-pos sec-pos)
1175 (if (< top-pos sec-pos)
1176 "top"
1177 sec-name)
1178 (or sec-name "top")))
1179 (t
1180 (error
1181 "texinfo-specific-section-type: Chapter or section not found")))))
1183 (defun texinfo-hierarchic-level ()
1184 "Return the general hierarchical level of the next node in a texinfo file.
1185 Thus, a subheading or appendixsubsec is of type subsection."
1186 (let ((case-fold-search t))
1187 (cadr (assoc
1188 (texinfo-specific-section-type)
1189 texinfo-section-list))))
1191 \f
1192 ;;; Locating the major positions
1194 (defun texinfo-update-menu-region-beginning (level)
1195 "Locate beginning of higher level section this section is within.
1196 Return position of the beginning of the node line; do not move point.
1197 Thus, if this level is subsection, searches backwards for section node.
1198 Only argument is a string of the general type of section."
1199 (let ((case-fold-search t))
1200 ;; !! Known bug: if section immediately follows top node, this
1201 ;; returns the beginning of the buffer as the beginning of the
1202 ;; higher level section.
1203 (cond
1204 ((< level 3)
1205 (save-excursion
1206 (goto-char (point-min))
1207 (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t)
1208 (line-beginning-position)))
1209 (t
1210 (save-excursion
1211 (re-search-backward
1212 (concat
1213 "\\(^@node\\).*\n" ; match node line
1214 "\\(\\(\\(^@c\\).*\n\\)" ; match comment line, if any
1215 "\\|" ; or
1216 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
1217 "\\|" ; or
1218 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
1219 "\\)?" ; end of expression
1220 (eval
1221 (cdr (assoc level texinfo-update-menu-higher-regexps))))
1222 nil
1223 'goto-beginning)
1224 (point))))))
1226 (defun texinfo-update-menu-region-end (level)
1227 "Locate end of higher level section this section is within.
1228 Return position; do not move point. Thus, if this level is a
1229 subsection, find the node for the section this subsection is within.
1230 If level is top or chapter, returns end of file. Only argument is a
1231 string of the general type of section."
1232 (let ((case-fold-search t))
1233 (save-excursion
1234 (if (re-search-forward
1235 (concat
1236 "\\(^@node\\).*\n" ; match node line
1237 "\\(\\(\\(^@c\\).*\n\\)" ; match comment line, if any
1238 "\\|" ; or
1239 "\\(^@ifinfo[ ]*\n\\)" ; ifinfo line, if any
1240 "\\|" ; or
1241 "\\(^@ifnottex[ ]*\n\\)" ; ifnottex line, if any
1242 "\\)?" ; end of expression
1243 (eval
1244 ;; Never finds end of level above chapter so goes to end.
1245 (cdr (assoc level texinfo-update-menu-higher-regexps))))
1246 nil
1247 'goto-end)
1248 (match-beginning 1)
1249 (point-max)))))
1251 (defun texinfo-menu-first-node (beginning end)
1252 "Locate first node of the section the menu will be placed in.
1253 Return position; do not move point.
1254 The menu will be located just before this position.
1256 First argument is the position of the beginning of the section in
1257 which the menu will be located; second argument is the position of the
1258 end of that region; it limits the search."
1259 (save-excursion
1260 (goto-char beginning)
1261 (forward-line 1)
1262 (re-search-forward "^@node" end t)
1263 (line-beginning-position)))
1265 \f
1266 ;;; Updating a node
1268 (defun texinfo-update-node (&optional beginning end)
1269 "Without any prefix argument, update the node in which point is located.
1270 Interactively, a prefix argument means to operate on the region.
1272 Warning: do NOT use this function if your Texinfo file uses @node
1273 lines without the `Next', `Previous', `Up' pointers, because the
1274 result could be an invalid Texinfo file due to known deficiencies
1275 in this command: it does not support @ignore and @if* directives.
1277 The functions for creating or updating nodes and menus, and their
1278 keybindings, are:
1280 texinfo-update-node (&optional beginning end) \\[texinfo-update-node]
1281 texinfo-every-node-update () \\[texinfo-every-node-update]
1282 texinfo-sequential-node-update (&optional region-p)
1284 texinfo-make-menu (&optional region-p) \\[texinfo-make-menu]
1285 texinfo-all-menus-update () \\[texinfo-all-menus-update]
1286 texinfo-master-menu ()
1288 texinfo-indent-menu-description (column &optional region-p)
1290 The `texinfo-column-for-description' variable specifies the column to
1291 which menu descriptions are indented. Its default value is 32."
1293 (interactive
1294 (if prefix-arg
1295 (list (point) (mark))))
1296 (if (null beginning)
1297 ;; Update a single node.
1298 (let ((auto-fill-function nil))
1299 (if (not (re-search-backward "^@node" (point-min) t))
1300 (error "Node line not found before this position"))
1301 (texinfo-update-the-node)
1302 (message "Done...updated the node. You may save the buffer."))
1303 ;; else
1304 (let ((auto-fill-function nil))
1305 (save-excursion
1306 (save-restriction
1307 (narrow-to-region beginning end)
1308 (goto-char (point-min))
1309 (while (re-search-forward "^@node" (point-max) t)
1310 (beginning-of-line)
1311 (texinfo-update-the-node))
1312 (goto-char (point-max))
1313 (message "Done...nodes updated in region. You may save the buffer."))))))
1315 (defun texinfo-every-node-update ()
1316 "Update every node in a Texinfo file.
1318 Warning: do NOT use this function if your Texinfo file uses @node
1319 lines without the `Next', `Previous', `Up' pointers, because the
1320 result could be an invalid Texinfo file due to known deficiencies
1321 in this command: it does not support @ignore and @if* directives."
1322 (interactive)
1323 (save-excursion
1324 (texinfo-update-node (point-min) (point-max))
1325 (message "Done...updated every node. You may save the buffer.")))
1327 (defun texinfo-update-the-node ()
1328 "Update one node. Point must be at the beginning of node line.
1329 Leave point at the end of the node line."
1330 (texinfo-check-for-node-name)
1331 (texinfo-delete-existing-pointers)
1332 (message "Updating node: %s ... " (texinfo-copy-node-name))
1333 (save-restriction
1334 (widen)
1335 (let*
1336 ((case-fold-search t)
1337 (level (texinfo-hierarchic-level))
1338 (beginning (texinfo-update-menu-region-beginning level))
1339 (end (texinfo-update-menu-region-end level)))
1340 (if (eq level 1)
1341 (texinfo-top-pointer-case)
1342 ;; else
1343 (texinfo-insert-pointer beginning end level 'next)
1344 (texinfo-insert-pointer beginning end level 'previous)
1345 (texinfo-insert-pointer beginning end level 'up)
1346 (texinfo-clean-up-node-line)))))
1348 (defun texinfo-top-pointer-case ()
1349 "Insert pointers in the Top node. This is a special case.
1351 The `Next' pointer is a pointer to a chapter or section at a lower
1352 hierarchical level in the file. The `Previous' and `Up' pointers are
1353 to `(dir)'. Point must be at the beginning of the node line, and is
1354 left at the end of the node line."
1356 (texinfo-clean-up-node-line)
1357 (insert ", "
1358 (save-excursion
1359 ;; There may be an @chapter or other such command between
1360 ;; the top node line and the next node line, as a title
1361 ;; for an `ifinfo' section. This @chapter command must
1362 ;; must be skipped. So the procedure is to search for
1363 ;; the next `@node' line, and then copy its name.
1364 (if (re-search-forward "^@node" nil t)
1365 (progn
1366 (beginning-of-line)
1367 (texinfo-copy-node-name))
1368 " "))
1369 ", (dir), (dir)"))
1371 (defun texinfo-check-for-node-name ()
1372 "Determine whether the node has a node name. Prompt for one if not.
1373 Point must be at beginning of node line. Does not move point."
1374 (save-excursion
1375 (let ((initial (texinfo-copy-next-section-title)))
1376 ;; This is not clean. Use `interactive' to read the arg.
1377 (forward-word 1) ; skip over node command
1378 (skip-chars-forward " \t") ; and over spaces
1379 (if (not (looking-at "[^,\t\n ]+")) ; regexp based on what Info looks for
1380 ; alternatively, use "[a-zA-Z]+"
1381 (let ((node-name
1382 (read-from-minibuffer
1383 "Node name (use no @, commas, colons, or apostrophes): "
1384 initial)))
1385 (insert " " node-name))))))
1387 (defun texinfo-delete-existing-pointers ()
1388 "Delete `Next', `Previous', and `Up' pointers.
1389 Starts from the current position of the cursor, and searches forward
1390 on the line for a comma and if one is found, deletes the rest of the
1391 line, including the comma. Leaves point at beginning of line."
1392 (let ((eol-point (line-end-position)))
1393 (if (search-forward "," eol-point t)
1394 (delete-region (1- (point)) eol-point)))
1395 (beginning-of-line))
1397 (defun texinfo-find-pointer (beginning end level direction)
1398 "Move point to section associated with next, previous, or up pointer.
1399 Return type of pointer (either `normal' or `no-pointer').
1401 The first and second arguments bound the search for a pointer to the
1402 beginning and end, respectively, of the enclosing higher level
1403 section. The third argument is a string specifying the general kind
1404 of section such as \"chapter\" or \"section\". When looking for the
1405 `Next' pointer, the section found will be at the same hierarchical
1406 level in the Texinfo file; when looking for the `Previous' pointer,
1407 the section found will be at the same or higher hierarchical level in
1408 the Texinfo file; when looking for the `Up' pointer, the section found
1409 will be at some level higher in the Texinfo file. The fourth argument
1410 \(one of 'next, 'previous, or 'up\) specifies whether to find the
1411 `Next', `Previous', or `Up' pointer."
1412 (let ((case-fold-search t))
1413 (cond ((eq direction 'next)
1414 (forward-line 3) ; skip over current node
1415 ;; Search for section commands accompanied by node lines;
1416 ;; ignore section commands in the middle of nodes.
1417 (if (re-search-forward
1418 ;; A `Top' node is never a next pointer, so won't find it.
1419 (concat
1420 ;; Match node line.
1421 "\\(^@node\\).*\n"
1422 ;; Match comment, ifinfo, ifnottex line, if any
1423 (concat
1424 "\\(\\("
1425 "\\(^@c\\).*\n\\)"
1426 "\\|"
1427 "\\(^@ifinfo[ ]*\n\\)"
1428 "\\|"
1429 "\\(^@ifnottex[ ]*\n\\)"
1430 "\\)?")
1431 (eval
1432 (cdr (assoc level texinfo-update-menu-same-level-regexps))))
1433 end
1434 t)
1435 'normal
1436 'no-pointer))
1437 ((eq direction 'previous)
1438 (if (re-search-backward
1439 (concat
1440 "\\("
1441 ;; Match node line.
1442 "\\(^@node\\).*\n"
1443 ;; Match comment, ifinfo, ifnottex line, if any
1444 (concat
1445 "\\(\\("
1446 "\\(^@c\\).*\n\\)"
1447 "\\|"
1448 "\\(^@ifinfo[ ]*\n\\)"
1449 "\\|"
1450 "\\(^@ifnottex[ ]*\n\\)"
1451 "\\)?")
1452 (eval
1453 (cdr (assoc level texinfo-update-menu-same-level-regexps)))
1454 "\\|"
1455 ;; Match node line.
1456 "\\(^@node\\).*\n"
1457 ;; Match comment, ifinfo, ifnottex line, if any
1458 (concat
1459 "\\(\\("
1460 "\\(^@c\\).*\n\\)"
1461 "\\|"
1462 "\\(^@ifinfo[ ]*\n\\)"
1463 "\\|"
1464 "\\(^@ifnottex[ ]*\n\\)"
1465 "\\)?")
1466 (eval
1467 (cdr (assoc level texinfo-update-menu-higher-regexps)))
1468 "\\|"
1469 ;; Handle `Top' node specially.
1470 "^@node [ \t]*top[ \t]*\\(,\\|$\\)"
1471 "\\)")
1472 beginning
1473 t)
1474 'normal
1475 'no-pointer))
1476 ((eq direction 'up)
1477 (if (re-search-backward
1478 (concat
1479 "\\("
1480 ;; Match node line.
1481 "\\(^@node\\).*\n"
1482 ;; Match comment, ifinfo, ifnottex line, if any
1483 (concat
1484 "\\(\\("
1485 "\\(^@c\\).*\n\\)"
1486 "\\|"
1487 "\\(^@ifinfo[ ]*\n\\)"
1488 "\\|"
1489 "\\(^@ifnottex[ ]*\n\\)"
1490 "\\)?")
1491 (eval (cdr (assoc level texinfo-update-menu-higher-regexps)))
1492 "\\|"
1493 ;; Handle `Top' node specially.
1494 "^@node [ \t]*top[ \t]*\\(,\\|$\\)"
1495 "\\)")
1496 (save-excursion
1497 (goto-char beginning)
1498 (line-beginning-position))
1499 t)
1500 'normal
1501 'no-pointer))
1502 (t
1503 (error "texinfo-find-pointer: lack proper arguments")))))
1505 (defun texinfo-pointer-name (kind)
1506 "Return the node name preceding the section command.
1507 The argument is the kind of section, either `normal' or `no-pointer'."
1508 (let (name)
1509 (cond ((eq kind 'normal)
1510 (end-of-line) ; this handles prev node top case
1511 (re-search-backward ; when point is already
1512 "^@node" ; at the beginning of @node line
1513 (line-beginning-position -2)
1514 t)
1515 (setq name (texinfo-copy-node-name)))
1516 ((eq kind 'no-pointer)
1517 ;; Don't need to put a blank in the pointer slot,
1518 ;; since insert "' " always has a space
1519 (setq name " "))) ; put a blank in the pointer slot
1520 name))
1522 (defun texinfo-insert-pointer (beginning end level direction)
1523 "Insert the `Next', `Previous' or `Up' node name at point.
1524 Move point forward.
1526 The first and second arguments bound the search for a pointer to the
1527 beginning and end, respectively, of the enclosing higher level
1528 section. The third argument is the hierarchical level of the Texinfo
1529 file, a string such as \"section\". The fourth argument is direction
1530 towards which the pointer is directed, one of `next', `previous', or `up'."
1532 (end-of-line)
1533 (insert
1534 ", "
1535 (save-excursion
1536 (texinfo-pointer-name
1537 (texinfo-find-pointer beginning end level direction)))))
1539 (defun texinfo-clean-up-node-line ()
1540 "Remove extra commas, if any, at end of node line."
1541 (end-of-line)
1542 (skip-chars-backward ", ")
1543 (delete-region (point) (line-end-position)))
1545 \f
1546 ;;; Updating nodes sequentially
1547 ;; These sequential update functions insert `Next' or `Previous'
1548 ;; pointers that point to the following or preceding nodes even if they
1549 ;; are at higher or lower hierarchical levels. This means that if a
1550 ;; section contains one or more subsections, the section's `Next'
1551 ;; pointer will point to the subsection and not the following section.
1552 ;; (The subsection to which `Next' points will most likely be the first
1553 ;; item on the section's menu.)
1555 (defun texinfo-sequential-node-update (&optional region-p)
1556 "Update one node (or many) in a Texinfo file with sequential pointers.
1558 This function causes the `Next' or `Previous' pointer to point to the
1559 immediately preceding or following node, even if it is at a higher or
1560 lower hierarchical level in the document. Continually pressing `n' or
1561 `p' takes you straight through the file.
1563 Without any prefix argument, update the node in which point is located.
1564 Non-nil argument (prefix, if interactive) means update the nodes in the
1565 marked region.
1567 This command makes it awkward to navigate among sections and
1568 subsections; it should be used only for those documents that are meant
1569 to be read like a novel rather than a reference, and for which the
1570 Info `g*' command is inadequate."
1572 (interactive "P")
1573 (if (not region-p)
1574 ;; update a single node
1575 (let ((auto-fill-function nil))
1576 (if (not (re-search-backward "^@node" (point-min) t))
1577 (error "Node line not found before this position"))
1578 (texinfo-sequentially-update-the-node)
1579 (message
1580 "Done...sequentially updated the node . You may save the buffer."))
1581 ;; else
1582 (let ((auto-fill-function nil)
1583 (beginning (region-beginning))
1584 (end (region-end)))
1585 (if (= end beginning)
1586 (error "Please mark a region"))
1587 (save-restriction
1588 (narrow-to-region beginning end)
1589 (goto-char beginning)
1590 (push-mark (point) t)
1591 (while (re-search-forward "^@node" (point-max) t)
1592 (beginning-of-line)
1593 (texinfo-sequentially-update-the-node))
1594 (message
1595 "Done...updated the nodes in sequence. You may save the buffer.")))))
1597 (defun texinfo-sequentially-update-the-node ()
1598 "Update one node such that the pointers are sequential.
1599 A `Next' or `Previous' pointer points to any preceding or following node,
1600 regardless of its hierarchical level."
1602 (texinfo-check-for-node-name)
1603 (texinfo-delete-existing-pointers)
1604 (message
1605 "Sequentially updating node: %s ... " (texinfo-copy-node-name))
1606 (save-restriction
1607 (widen)
1608 (let* ((case-fold-search t)
1609 (level (texinfo-hierarchic-level)))
1610 (if (eq level 1)
1611 (texinfo-top-pointer-case)
1612 ;; else
1613 (texinfo-sequentially-insert-pointer level 'next)
1614 (texinfo-sequentially-insert-pointer level 'previous)
1615 (texinfo-sequentially-insert-pointer level 'up)
1616 (texinfo-clean-up-node-line)))))
1618 (defun texinfo-sequentially-insert-pointer (level direction)
1619 "Insert the `Next', `Previous' or `Up' node name at point.
1620 Move point forward.
1622 The first argument is the hierarchical level of the Texinfo file, a
1623 string such as \"section\". The second argument is direction, one of
1624 `next', `previous', or `up'."
1626 (end-of-line)
1627 (insert
1628 ", "
1629 (save-excursion
1630 (texinfo-pointer-name
1631 (texinfo-sequentially-find-pointer level direction)))))
1633 (defun texinfo-sequentially-find-pointer (level direction)
1634 "Find next or previous pointer sequentially in Texinfo file, or up pointer.
1635 Move point to section associated with the pointer. Find point even if
1636 it is in a different section.
1638 Return type of pointer (either `normal' or `no-pointer').
1640 The first argument is a string specifying the general kind of section
1641 such as \"chapter\" or \"section\". The section found will be at the
1642 same hierarchical level in the Texinfo file, or, in the case of the up
1643 pointer, some level higher. The second argument (one of `next',
1644 `previous', or `up') specifies whether to find the `Next', `Previous',
1645 or `Up' pointer."
1646 (let ((case-fold-search t))
1647 (cond ((eq direction 'next)
1648 (forward-line 3) ; skip over current node
1649 (if (re-search-forward
1650 texinfo-section-types-regexp
1651 (point-max)
1652 t)
1653 'normal
1654 'no-pointer))
1655 ((eq direction 'previous)
1656 (if (re-search-backward
1657 texinfo-section-types-regexp
1658 (point-min)
1659 t)
1660 'normal
1661 'no-pointer))
1662 ((eq direction 'up)
1663 (if (re-search-backward
1664 (eval (cdr (assoc level texinfo-update-menu-higher-regexps)))
1665 (point-min)
1666 t)
1667 'normal
1668 'no-pointer))
1669 (t
1670 (error "texinfo-sequential-find-pointer: lack proper arguments")))))
1672 \f
1673 ;;; Inserting `@node' lines
1674 ;; The `texinfo-insert-node-lines' function inserts `@node' lines as needed
1675 ;; before the `@chapter', `@section', and such like lines of a region
1676 ;; in a Texinfo file.
1678 (defun texinfo-insert-node-lines (beginning end &optional title-p)
1679 "Insert missing `@node' lines in region of Texinfo file.
1680 Non-nil argument (prefix, if interactive) means also to insert the
1681 section titles as node names; and also to insert the section titles as
1682 node names in pre-existing `@node' lines that lack names."
1683 (interactive "r\nP")
1685 ;; Use marker; after inserting node lines, leave point at end of
1686 ;; region and mark at beginning.
1688 (let (beginning-marker end-marker title last-section-position)
1690 ;; Save current position on mark ring and set mark to end.
1691 (push-mark end t)
1692 (setq end-marker (mark-marker))
1694 (goto-char beginning)
1695 (while (re-search-forward
1696 texinfo-section-types-regexp
1697 end-marker
1698 'end)
1699 ;; Copy title if desired.
1700 (if title-p
1701 (progn
1702 (beginning-of-line)
1703 (forward-word 1)
1704 (skip-chars-forward " \t")
1705 (setq title (buffer-substring
1706 (point)
1707 (line-end-position)))))
1708 ;; Insert node line if necessary.
1709 (if (re-search-backward
1710 "^@node"
1711 ;; Avoid finding previous node line if node lines are close.
1712 (or last-section-position
1713 (line-beginning-position -1))
1714 t)
1715 ;; @node is present, and point at beginning of that line
1716 (forward-word 1) ; Leave point just after @node.
1717 ;; Else @node missing; insert one.
1718 (beginning-of-line) ; Beginning of `@section' line.
1719 (insert "@node\n")
1720 (backward-char 1)) ; Leave point just after `@node'.
1721 ;; Insert title if desired.
1722 (if title-p
1723 (progn
1724 (skip-chars-forward " \t")
1725 ;; Use regexp based on what info looks for
1726 ;; (alternatively, use "[a-zA-Z]+");
1727 ;; this means we only insert a title if none exists.
1728 (if (not (looking-at "[^,\t\n ]+"))
1729 (progn
1730 (beginning-of-line)
1731 (forward-word 1)
1732 (insert " " title)
1733 (message "Inserted title %s ... " title)))))
1734 ;; Go forward beyond current section title.
1735 (re-search-forward texinfo-section-types-regexp
1736 (line-beginning-position 4) t)
1737 (setq last-section-position (point))
1738 (forward-line 1))
1740 ;; Leave point at end of region, mark at beginning.
1741 (set-mark beginning)
1743 (if title-p
1744 (message
1745 "Done inserting node lines and titles. You may save the buffer.")
1746 (message "Done inserting node lines. You may save the buffer."))))
1748 \f
1749 ;;; Update and create menus for multi-file Texinfo sources
1751 ;; 1. M-x texinfo-multiple-files-update
1752 ;;
1753 ;; Read the include file list of an outer Texinfo file and
1754 ;; update all highest level nodes in the files listed and insert a
1755 ;; main menu in the outer file after its top node.
1757 ;; 2. C-u M-x texinfo-multiple-files-update
1758 ;;
1759 ;; Same as 1, but insert a master menu. (Saves reupdating lower
1760 ;; level menus and nodes.) This command simply reads every menu,
1761 ;; so if the menus are wrong, the master menu will be wrong.
1762 ;; Similarly, if the lower level node pointers are wrong, they
1763 ;; will stay wrong.
1765 ;; 3. C-u 2 M-x texinfo-multiple-files-update
1766 ;;
1767 ;; Read the include file list of an outer Texinfo file and
1768 ;; update all nodes and menus in the files listed and insert a
1769 ;; master menu in the outer file after its top node.
1771 ;;; Note: these functions:
1772 ;;;
1773 ;;; * Do not save or delete any buffers. You may fill up your memory.
1774 ;;; * Do not handle any pre-existing nodes in outer file.
1775 ;;; Hence, you may need a file for indices.
1777 \f
1778 ;;; Auxiliary functions for multiple file updating
1780 (defun texinfo-multi-file-included-list (outer-file)
1781 "Return a list of the included files in OUTER-FILE."
1782 (let ((included-file-list (list outer-file))
1783 start)
1784 (with-current-buffer (find-file-noselect outer-file)
1785 (widen)
1786 (goto-char (point-min))
1787 (while (re-search-forward "^@include" nil t)
1788 (skip-chars-forward " \t")
1789 (setq start (point))
1790 (end-of-line)
1791 (skip-chars-backward " \t")
1792 (setq included-file-list
1793 (cons (buffer-substring start (point))
1794 included-file-list)))
1795 (nreverse included-file-list))))
1797 (defun texinfo-copy-next-section-title ()
1798 "Return the name of the immediately following section as a string.
1800 Start with point at the beginning of the node line. Leave point at the
1801 same place. If there is no title, returns an empty string."
1803 (save-excursion
1804 (end-of-line)
1805 (let ((node-end (or
1806 (save-excursion
1807 (if (re-search-forward "\\(^@node\\)" nil t)
1808 (match-beginning 0)))
1809 (point-max))))
1810 (if (re-search-forward texinfo-section-types-regexp node-end t)
1811 (progn
1812 (beginning-of-line)
1813 ;; copy title
1814 (let ((title
1815 (buffer-substring
1816 (progn (forward-word 1) ; skip over section type
1817 (skip-chars-forward " \t") ; and over spaces
1818 (point))
1819 (progn (end-of-line) (point)))))
1820 title))
1821 ""))))
1823 (defun texinfo-multi-file-update (files &optional update-everything)
1824 "Update first node pointers in each file in FILES.
1825 Return a list of the node names.
1827 The first file in the list is an outer file; the remaining are
1828 files included in the outer file with `@include' commands.
1830 If optional arg UPDATE-EVERYTHING non-nil, update every menu and
1831 pointer in each of the included files.
1833 Also update the `Top' level node pointers of the outer file.
1835 Requirements:
1837 * the first file in the FILES list must be the outer file,
1838 * each of the included files must contain exactly one highest
1839 hierarchical level node,
1840 * this node must be the first node in the included file,
1841 * each highest hierarchical level node must be of the same type.
1843 Thus, normally, each included file contains one, and only one, chapter.
1845 However, when an included file does not have any node lines in
1846 it, this command does not try to create a menu entry for it.
1847 Consequently, you can include any file, such as a version or an
1848 update file without node lines, not just files that are
1849 chapters."
1851 ;; The menu-list has the form:
1852 ;;
1853 ;; \(\(\"node-name1\" . \"title1\"\)
1854 ;; \(\"node-name2\" . \"title2\"\) ... \)
1855 ;;
1856 ;; However, there does not need to be a title field and this function
1857 ;; does not fill it; however a comment tells you how to do so.
1858 ;; You would use the title field if you wanted to insert titles in the
1859 ;; description slot of a menu as a description.
1861 (let ((case-fold-search t)
1862 menu-list next-node-name previous-node-name files-with-node-lines)
1864 ;; Create a new list of included files that only have node lines
1865 (while files
1866 (set-buffer (find-file-noselect (car files)))
1867 (widen)
1868 (goto-char (point-min))
1869 (when (re-search-forward "^@node" nil t)
1870 (setq files-with-node-lines (cons (car files) files-with-node-lines)))
1871 (setq files (cdr files)))
1872 (setq files-with-node-lines (nreverse files-with-node-lines))
1874 ;; Find the name of the first node in a subsequent file
1875 ;; and copy it into the variable next-node-name
1876 (set-buffer (find-file-noselect (car (cdr files-with-node-lines))))
1877 (widen)
1878 (goto-char (point-min))
1879 ;; The following search _must_ succeed, since we verified above
1880 ;; that this file does have a @node line.
1881 (re-search-forward "^@node" nil t)
1882 (beginning-of-line)
1883 (texinfo-check-for-node-name)
1884 (setq next-node-name (texinfo-copy-node-name))
1885 (push (cons next-node-name (prog1 "" (forward-line 1)))
1886 ;; Use following to insert section titles automatically.
1887 ;; (texinfo-copy-next-section-title)
1888 menu-list)
1890 ;; Go to outer file
1891 ;; `pop' is analogous to (prog1 (car PLACE) (setf PLACE (cdr PLACE)))
1892 (set-buffer (find-file-noselect (pop files-with-node-lines)))
1893 (goto-char (point-min))
1894 (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
1895 (error "This buffer needs a Top node"))
1896 (beginning-of-line)
1897 (texinfo-delete-existing-pointers)
1898 (end-of-line)
1899 (insert ", " next-node-name ", (dir), (dir)")
1900 (beginning-of-line)
1901 (setq previous-node-name "Top")
1903 (while files-with-node-lines
1905 (if (not (cdr files-with-node-lines))
1906 ;; No next file
1907 (setq next-node-name "")
1908 ;; Else,
1909 ;; find the name of the first node in the next file.
1910 (set-buffer (find-file-noselect (car (cdr files-with-node-lines))))
1911 (widen)
1912 (goto-char (point-min))
1913 ;; The following search _must_ succeed, since we verified
1914 ;; above that files in files-with-node-lines do have a @node
1915 ;; line.
1916 (re-search-forward "^@node" nil t)
1917 (beginning-of-line)
1918 (texinfo-check-for-node-name)
1919 (setq next-node-name (texinfo-copy-node-name))
1920 (push (cons next-node-name (prog1 "" (forward-line 1)))
1921 ;; Use following to insert section titles automatically.
1922 ;; (texinfo-copy-next-section-title)
1923 menu-list))
1925 ;; Go to node to be updated.
1926 (set-buffer (find-file-noselect (car files-with-node-lines)))
1927 (goto-char (point-min))
1928 (beginning-of-line)
1930 ;; Update other menus and nodes if requested.
1931 (if update-everything (texinfo-all-menus-update t))
1933 (beginning-of-line)
1934 (texinfo-delete-existing-pointers)
1935 (end-of-line)
1936 (insert ", " next-node-name ", " previous-node-name ", Top")
1938 (beginning-of-line)
1939 (setq previous-node-name (texinfo-copy-node-name))
1941 (setq files-with-node-lines (cdr files-with-node-lines)))
1942 (nreverse menu-list)))
1944 (defun texinfo-multi-files-insert-main-menu (menu-list)
1945 "Insert formatted main menu at point.
1946 Indents the first line of the description, if any, to the value of
1947 `texinfo-column-for-description'."
1949 (insert "@menu\n")
1950 (dolist (entry menu-list)
1951 ;; Every menu entry starts with a star and a space.
1952 (insert "* ")
1954 ;; Insert the node name (and menu entry name, if present).
1955 (let ((node-part (car entry)))
1956 (if (stringp node-part)
1957 ;; "Double colon" entry line; menu entry and node name are the same,
1958 (insert (format "%s::" node-part))
1959 ;; "Single colon" entry line; menu entry and node name are different.
1960 (insert (format "%s: %s." (car node-part) (cdr node-part)))))
1962 ;; Insert the description, if present.
1963 (when (cdr entry)
1964 ;; Move to right place.
1965 (indent-to texinfo-column-for-description 2)
1966 ;; Insert description.
1967 (insert (format "%s" (cdr entry))))
1969 (insert "\n")) ; end this menu entry
1970 (insert "@end menu"))
1972 (defun texinfo-multi-file-master-menu-list (files-list)
1973 "Return master menu list from files in FILES-LIST.
1974 Menu entries in each file collected using `texinfo-master-menu-list'.
1976 The first file in FILES-LIST must be the outer file; the others must
1977 be the files included within it. A main menu must already exist."
1978 (save-excursion
1979 (let (master-menu-list)
1980 (dolist (file files-list)
1981 (set-buffer (find-file-noselect file))
1982 (message "Working on: %s " (current-buffer))
1983 (goto-char (point-min))
1984 (setq master-menu-list
1985 (append master-menu-list (texinfo-master-menu-list))))
1986 master-menu-list)))
1988 \f
1989 ;;; The multiple-file update function
1991 (defun texinfo-multiple-files-update
1992 (outer-file &optional make-master-menu update-everything)
1993 "Update first node pointers in each file included in OUTER-FILE;
1994 create or update the `Top' level node pointers and the main menu in
1995 the outer file that refers to such nodes. This does not create or
1996 update menus or pointers within the included files.
1998 With optional MAKE-MASTER-MENU argument (prefix arg, if interactive),
1999 insert a master menu in OUTER-FILE in addition to creating or updating
2000 pointers in the first @node line in each included file and creating or
2001 updating the `Top' level node pointers of the outer file. This does
2002 not create or update other menus and pointers within the included
2003 files.
2005 With optional UPDATE-EVERYTHING argument (numeric prefix arg, if
2006 interactive), update all the menus and all the `Next', `Previous', and
2007 `Up' pointers of all the files included in OUTER-FILE before inserting
2008 a master menu in OUTER-FILE. Also, update the `Top' level node
2009 pointers of OUTER-FILE. Do NOT invoke this command with a numeric prefix
2010 arg, if your files use @node lines without the `Next', `Previous', `Up'
2011 pointers, because this could produce invalid Texinfo files due to known
2012 deficiencies in `texinfo-update-node': it does not support the @ignore
2013 and @if... directives.
2015 Notes:
2017 * this command does NOT save any files--you must save the
2018 outer file and any modified, included files.
2020 * except for the `Top' node, this command does NOT handle any
2021 pre-existing nodes in the outer file; hence, indices must be
2022 enclosed in an included file.
2024 Requirements:
2026 * each of the included files must contain exactly one highest
2027 hierarchical level node,
2028 * this highest node must be the first node in the included file,
2029 * each highest hierarchical level node must be of the same type.
2031 Thus, normally, each included file contains one, and only one,
2032 chapter."
2034 (interactive (cons
2035 (read-string
2036 "Name of outer `include' file: "
2037 (buffer-file-name))
2038 (cond
2039 ((not current-prefix-arg) '(nil nil))
2040 ((listp current-prefix-arg) '(t nil)) ; make-master-menu
2041 ((numberp current-prefix-arg) '(t t))))) ; update-everything
2043 (let* ((included-file-list (texinfo-multi-file-included-list outer-file))
2044 (files included-file-list)
2045 next-node-name
2046 previous-node-name
2047 ;; Update the pointers and collect the names of the nodes and titles
2048 (main-menu-list (texinfo-multi-file-update files update-everything)))
2050 ;; Insert main menu
2052 ;; Go to outer file
2053 (set-buffer (find-file-noselect (car included-file-list)))
2054 (if (texinfo-old-menu-p
2055 (point-min)
2056 (save-excursion
2057 (re-search-forward "^@include")
2058 (line-beginning-position)))
2059 ;; If found, leave point after word `menu' on the `@menu' line.
2060 (progn
2061 (texinfo-incorporate-descriptions main-menu-list)
2062 ;; Delete existing menu.
2063 (beginning-of-line)
2064 (delete-region
2065 (point)
2066 (save-excursion (re-search-forward "^@end menu") (point)))
2067 ;; Insert main menu
2068 (texinfo-multi-files-insert-main-menu main-menu-list))
2070 ;; Else no current menu; insert it before `@include'
2071 (texinfo-multi-files-insert-main-menu main-menu-list))
2073 ;; Insert master menu
2075 (if make-master-menu
2076 (progn
2077 ;; First, removing detailed part of any pre-existing master menu
2078 (goto-char (point-min))
2079 (if (search-forward texinfo-master-menu-header nil t)
2080 (progn
2081 (goto-char (match-beginning 0))
2082 ;; Check if @detailmenu kludge is used;
2083 ;; if so, leave point before @detailmenu.
2084 (search-backward "\n@detailmenu" (line-beginning-position -2) t)
2085 ;; Remove detailed master menu listing
2086 (let ((end-of-detailed-menu-descriptions
2087 (save-excursion ; beginning of end menu line
2088 (goto-char (texinfo-menu-end))
2089 (beginning-of-line) (forward-char -1)
2090 (point))))
2091 (delete-region (point) end-of-detailed-menu-descriptions))))
2093 ;; Create a master menu and insert it
2094 (texinfo-insert-master-menu-list
2095 (texinfo-multi-file-master-menu-list
2096 included-file-list)))))
2098 ;; Remove unwanted extra lines.
2099 (save-excursion
2100 (goto-char (point-min))
2102 (re-search-forward "^@menu")
2103 (forward-line -1)
2104 (insert "\n") ; Ensure at least one blank line.
2105 (delete-blank-lines)
2107 (re-search-forward "^@end menu")
2108 (forward-line 1)
2109 (insert "\n") ; Ensure at least one blank line.
2110 (delete-blank-lines))
2112 (message "Multiple files updated."))
2114 \f
2115 ;; Place `provide' at end of file.
2116 (provide 'texnfo-upd)
2118 ;;; texnfo-upd.el ends here