* buffer.c (syms_of_buffer): Omit unneeded staticpros.
[emacs.git] / lisp / textmodes / texnfo-upd.el
1 ;;; texnfo-upd.el --- utilities for updating nodes and menus in Texinfo files
2
3 ;; Copyright (C) 1989-1992, 2001-2014 Free Software Foundation, Inc.
4
5 ;; Author: Robert J. Chassell
6 ;; Maintainer: bug-texinfo@gnu.org
7 ;; Keywords: maint, tex, docs
8
9 ;; This file is part of GNU Emacs.
10
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.
15
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.
20
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/>.
23
24 ;;; Commentary:
25
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).
29
30 ;; Summary: how to use the updating commands
31
32 ;; The node and menu updating functions automatically
33
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)
65
66 ;; The `texinfo-column-for-description' variable specifies the column to
67 ;; which menu descriptions are indented.
68
69 ;; Texinfo file structure
70 ;; ----------------------
71
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:
77
78 ;;      @node    Lists and Tables, Cross References, Structuring, Top
79 ;;      @comment node-name,        next,             previous,    up
80 ;;      @chapter Making Lists and Tables
81
82 ;; or like this (without the `@comment' line):
83
84 ;;      @node    Lists and Tables, Cross References, Structuring, Top
85 ;;      @chapter Making Lists and Tables
86
87 ;; If the file has a `top' node, it must be called `top' or `Top' and
88 ;; be the first node in the file.
89
90 \f
91 ;;; The update node functions described in detail
92
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).
96
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.
100
101 ;; It does not matter whether the  `@node' line has pre-existing
102 ;; `Next', `Previous', or `Up' pointers in it.  They are removed.
103
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.
113
114 ;; The `texinfo-every-node-update' function runs `texinfo-update-node'
115 ;; on the whole buffer.
116
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.
122
123 \f
124 ;;; The menu making functions described in detail
125
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.
130
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.
136
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.
139
140 ;; The `texinfo-all-menus-update' function runs `texinfo-make-menu'
141 ;; on the whole buffer.
142
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.
153
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.
159
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.
171
172 \f
173 ;;; Code:
174
175 (require 'texinfo)
176
177
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.")
182
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).")
187
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.")
191
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.")
195
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.")
199
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.")
209
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.")
237
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.")
276
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.
281
282 A prefix argument means make or update menus
283 for nodes within or part of the marked region.
284
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.
288
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."
293
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)
311
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))
316
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))))
329
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)))
353
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.
357
358 Only single-file manuals are supported by this function.  For
359 multi-file manuals, use `texinfo-multiple-files-update'.
360
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!
365
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))))
391
392       (when update-all-nodes-p
393         (message "Updating all nodes in %s ... " (buffer-name))
394         (texinfo-update-node (point-min) (point-max)))
395
396       (message "Updating all menus in %s ... " (buffer-name))
397       (texinfo-make-menu (point-max) (point-min))
398
399       (when master-menu-p
400         (message "Updating the master menu in %s... " (buffer-name))
401         (texinfo-master-menu nil)))
402
403     (message "Done...updated all the menus.  You may save the buffer.")))
404
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.
409
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)))))
430
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.
434
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.
437
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."
440
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)))))
459
460 \f
461 ;;; Making the list of new menu entries
462
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.
466
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.
470
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)))
484
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.
490
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.
493
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)))))
511
512 (defun texinfo-copy-node-name ()
513   "Return the node name as a string.
514
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."
519
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)))))
528
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.
533
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'."
537
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
541
542   (goto-char (match-beginning 7))       ; match section name
543
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))))
549
550 \f
551 ;;; Handling the old menu
552
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.
557
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.
561
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)
566       t
567     (insert "\n\n") (forward-line -2) nil))
568
569 (defun texinfo-incorporate-descriptions (new-menu-list)
570   "Copy the old menu line descriptions that exist to the new menu.
571
572 Point must be at beginning of old menu.
573
574 If the node-name of the new menu is found in the old menu, insert the
575 old description into the new entry.
576
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."
581
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)))))))
601
602 (defun texinfo-incorporate-menu-entry-names (new-menu-list)
603   "Copy any old menu entry names to the new menu.
604
605 Point must be at beginning of old menu.
606
607 If the node-name of the new menu entry cannot be found in the old
608 menu, do nothing.
609
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).
613
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.
617
618 NEW-MENU-LIST is changed destructively.  The old menu is the menu as it
619 appears in the texinfo file."
620
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))))))))
640
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     ""))
659
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"))))
667
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))))
679
680 \f
681 ;;; Inserting new menu
682
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.")
686
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.
694
695 MENU-LIST has form:
696
697     \(\(\"node-name1\" . \"description\"\)
698     \(\"node-name2\" . \"description\"\) ... \)
699
700 However, the description field might be nil.
701
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."
705
706   (insert "@menu\n")
707   (dolist (menu menu-list)
708     ;; Every menu entry starts with a star and a space.
709     (insert "* ")
710
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)))))
718
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))))
725
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)))
731
732 \f
733 ;;; Starting menu descriptions by inserting titles
734
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.
739
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."
742
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"))
751
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))))
759
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
792             )
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))))
812
813 \f
814 ;;; Handling description indentation
815
816 ;; Since the make-menu functions indent descriptions, these functions
817 ;; are useful primarily for indenting a single menu specially.
818
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."
824
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.")))))
844
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)))
856
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)))))
870
871 \f
872 ;;; Making the master menu
873
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.
877
878 This function supports only single-file manuals.  For multi-file
879 manuals, use `texinfo-multiple-files-update'.
880
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.
890
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!
900
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.
905
906 The master menu has the following format, which is adapted from the
907 recommendation in the Texinfo Manual:
908
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.
913
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.
918
919 Each of the menus in the detailed node listing is introduced by the
920 title of the section containing the menu.
921
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."
926
927   (interactive "P")
928   (let ((case-fold-search t))
929     (widen)
930     (goto-char (point-min))
931
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"))
935
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)))))
954
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))))
964
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))
969
970     ;; Remove extra newlines that texinfo-insert-master-menu-list
971     ;; may have inserted.
972
973     (save-excursion
974       (goto-char (point-min))
975
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))))
985
986       (re-search-forward "^@menu")
987       (forward-line -1)
988       (delete-blank-lines)
989
990       (re-search-forward "^@end menu")
991       (forward-line 1)
992       (delete-blank-lines))
993
994     (message
995      "Done...completed making master menu.  You may save the buffer.")))
996
997 (defun texinfo-master-menu-list ()
998   "Return a list of menu entries and header lines for the master menu.
999
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.
1002
1003 The master menu list has this form:
1004
1005     \(\(\(... \"entry-1-2\"  \"entry-1\"\) \"title-1\"\)
1006       \(\(... \"entry-2-2\"  \"entry-2-1\"\) \"title-2\"\)
1007       ...\)
1008
1009 However, there does not need to be a title field."
1010
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)))
1016
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)))
1032
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"))
1044
1045       (setq master-menu-list (cdr master-menu-list))
1046
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))))
1052
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'.
1060
1061       ;; Now, insert all the other menus
1062
1063       ;; The menu master-menu-list has a form like this:
1064       ;; ((("beta"  "alpha") "title-A")
1065       ;;  (("delta" "gamma") "title-B"))
1066
1067       (dolist (menu master-menu-list)
1068
1069         (message "Inserting menu for %s .... " (cadr menu))
1070         ;; insert title of menu section
1071         (insert "\n" (cadr menu) "\n\n")
1072
1073         ;; insert each menu entry
1074         (dolist (entry (reverse (car menu)))
1075           (insert "* " entry "\n")))
1076
1077       ;; Finish menu
1078
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"))))
1084
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))
1090
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         ""))))
1113
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))
1137
1138 \f
1139 ;;; Determining the hierarchical level in the texinfo file
1140
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.
1144
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")))))
1182
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))))
1190
1191 \f
1192 ;;; Locating the major positions
1193
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))))))
1225
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)))))
1250
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.
1255
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)))
1264
1265 \f
1266 ;;; Updating a node
1267
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.
1271
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.
1276
1277 The functions for creating or updating nodes and menus, and their
1278 keybindings, are:
1279
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)
1283
1284     texinfo-make-menu (&optional region-p)      \\[texinfo-make-menu]
1285     texinfo-all-menus-update ()                 \\[texinfo-all-menus-update]
1286     texinfo-master-menu ()
1287
1288     texinfo-indent-menu-description (column &optional region-p)
1289
1290 The `texinfo-column-for-description' variable specifies the column to
1291 which menu descriptions are indented. Its default value is 32."
1292
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."))))))
1314
1315 (defun texinfo-every-node-update ()
1316   "Update every node in a Texinfo file.
1317
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.")))
1326
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)))))
1347
1348 (defun texinfo-top-pointer-case ()
1349   "Insert pointers in the Top node.  This is a special case.
1350
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."
1355
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)"))
1370
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))))))
1386
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))
1396
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').
1400
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")))))
1504
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))
1521
1522 (defun texinfo-insert-pointer (beginning end level direction)
1523   "Insert the `Next', `Previous' or `Up' node name at point.
1524 Move point forward.
1525
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'."
1531
1532   (end-of-line)
1533   (insert
1534    ", "
1535    (save-excursion
1536      (texinfo-pointer-name
1537       (texinfo-find-pointer beginning end level direction)))))
1538
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)))
1544
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.)
1554
1555 (defun texinfo-sequential-node-update (&optional region-p)
1556   "Update one node (or many) in a Texinfo file with sequential pointers.
1557
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.
1562
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.
1566
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."
1571
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.")))))
1596
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."
1601
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)))))
1617
1618 (defun texinfo-sequentially-insert-pointer (level direction)
1619   "Insert the `Next', `Previous' or `Up' node name at point.
1620 Move point forward.
1621
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'."
1625
1626   (end-of-line)
1627   (insert
1628    ", "
1629    (save-excursion
1630      (texinfo-pointer-name
1631       (texinfo-sequentially-find-pointer level direction)))))
1632
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.
1637
1638 Return type of pointer (either `normal' or `no-pointer').
1639
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")))))
1671
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.
1677
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")
1684
1685   ;; Use marker; after inserting node lines, leave point at end of
1686   ;; region and mark at beginning.
1687
1688   (let (beginning-marker end-marker title last-section-position)
1689
1690     ;; Save current position on mark ring and set mark to end.
1691     (push-mark end t)
1692     (setq end-marker (mark-marker))
1693
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))
1739
1740     ;; Leave point at end of region, mark at beginning.
1741     (set-mark beginning)
1742
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."))))
1747
1748 \f
1749 ;;; Update and create menus for multi-file Texinfo sources
1750
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.
1756
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.
1764
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.
1770
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.
1776
1777 \f
1778 ;;; Auxiliary functions for multiple file updating
1779
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))))
1796
1797 (defun texinfo-copy-next-section-title ()
1798   "Return the name of the immediately following section as a string.
1799
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."
1802
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         ""))))
1822
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.
1826
1827 The first file in the list is an outer file; the remaining are
1828 files included in the outer file with `@include' commands.
1829
1830 If optional arg UPDATE-EVERYTHING non-nil, update every menu and
1831 pointer in each of the included files.
1832
1833 Also update the `Top' level node pointers of the outer file.
1834
1835 Requirements:
1836
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.
1842
1843 Thus, normally, each included file contains one, and only one, chapter.
1844
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."
1850
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.
1860
1861   (let ((case-fold-search t)
1862         menu-list next-node-name previous-node-name files-with-node-lines)
1863
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))
1873
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)
1889
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")
1902
1903     (while files-with-node-lines
1904
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))
1924
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)
1929
1930       ;; Update other menus and nodes if requested.
1931       (if update-everything (texinfo-all-menus-update t))
1932
1933       (beginning-of-line)
1934       (texinfo-delete-existing-pointers)
1935       (end-of-line)
1936       (insert ", " next-node-name ", " previous-node-name ", Top")
1937
1938       (beginning-of-line)
1939       (setq previous-node-name (texinfo-copy-node-name))
1940
1941       (setq files-with-node-lines (cdr files-with-node-lines)))
1942     (nreverse menu-list)))
1943
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'."
1948
1949   (insert "@menu\n")
1950   (dolist (entry menu-list)
1951     ;; Every menu entry starts with a star and a space.
1952     (insert "* ")
1953
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)))))
1961
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))))
1968
1969     (insert "\n")) ; end this menu entry
1970   (insert "@end menu"))
1971
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'.
1975
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)))
1987
1988 \f
1989 ;;; The multiple-file update function
1990
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.
1997
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.
2004
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.
2014
2015 Notes:
2016
2017   * this command does NOT save any files--you must save the
2018     outer file and any modified, included files.
2019
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.
2023
2024 Requirements:
2025
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.
2030
2031 Thus, normally, each included file contains one, and only one,
2032 chapter."
2033
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
2042
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)))
2049
2050     ;; Insert main menu
2051
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))
2069
2070       ;; Else no current menu; insert it before `@include'
2071       (texinfo-multi-files-insert-main-menu main-menu-list))
2072
2073     ;; Insert master menu
2074
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))))
2092
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)))))
2097
2098   ;; Remove unwanted extra lines.
2099   (save-excursion
2100     (goto-char (point-min))
2101
2102     (re-search-forward "^@menu")
2103     (forward-line -1)
2104     (insert  "\n")                      ; Ensure at least one blank line.
2105     (delete-blank-lines)
2106
2107     (re-search-forward "^@end menu")
2108     (forward-line 1)
2109     (insert  "\n")                      ; Ensure at least one blank line.
2110     (delete-blank-lines))
2111
2112   (message "Multiple files updated."))
2113
2114 \f
2115 ;; Place `provide' at end of file.
2116 (provide 'texnfo-upd)
2117
2118 ;;; texnfo-upd.el ends here