texnfo-upd.el 63.7 KB
Newer Older
Eric S. Raymond's avatar
Eric S. Raymond committed
1
;;; texnfo-upd.el --- a utility for updating nodes and menus in Texinfo files.
Robert J. Chassell's avatar
Robert J. Chassell committed
2

Eric S. Raymond's avatar
Eric S. Raymond committed
3 4 5
;; Author: Bob Chassell <bob@gnu.ai.mit.edu>
;; Version: 2.00
;; Last-Modified: 14 Dec 1990
Eric S. Raymond's avatar
Eric S. Raymond committed
6
;; Keywords: maint, tex, docs
Robert J. Chassell's avatar
Robert J. Chassell committed
7

Jim Blandy's avatar
Jim Blandy committed
8
;;;; Copyright 1989, 1990, 1992 Free Software Foundation
Robert J. Chassell's avatar
Robert J. Chassell committed
9 10 11 12 13

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
Jim Blandy's avatar
Jim Blandy committed
14
;; the Free Software Foundation; either version 2, or (at your option)
Robert J. Chassell's avatar
Robert J. Chassell committed
15 16 17 18 19 20 21 22 23 24 25
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

Eric S. Raymond's avatar
Eric S. Raymond committed
26
;;; Commentary:
Robert J. Chassell's avatar
Robert J. Chassell committed
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149

;;;; Summary

; (Much of the following commentary ought eventually be incorporated
; into the Texinfo Manual.)

; The node and menu updating functions automatically

;   * insert missing `@node' lines,
;   * insert the `Next', `Previous' and `Up' pointers of a node,
;   * insert or update the menu for a section, 
;   * create a master menu for a Texinfo source file.

; Passed an argument, the `texinfo-update-node' and
; `texinfo-make-menu' functions do their jobs in the region.

; These functions replace doing these jobs by hand.
; You may find them helpful.

; In brief, the functions for creating or updating nodes and menus, are:
; 
;     texinfo-update-node (&optional region-p)            
;     texinfo-every-node-update ()                        
;     texinfo-sequential-node-update (&optional region-p)
; 
;     texinfo-make-menu (&optional region-p)              
;     texinfo-all-menus-update ()                         
;     texinfo-master-menu ()
;
;     texinfo-insert-node-lines  (&optional title-p)
; 
;     texinfo-indent-menu-description (column &optional region-p)

; The `texinfo-column-for-description' variable specifies the column to
; which menu descriptions are indented. 

; Texinfo file structure
; ----------------------

; To use the updating commands, you must structure your Texinfo file
; hierarchically.  Each `@node' line, with the exception of the top
; node, must be accompanied by some kind of section line, such as an
; `@chapter' or `@section' line.  Each node-line/section-line
; combination must look like this:

;      @node    Lists and Tables, Cross References, Structuring, Top
;      @comment node-name,        next,             previous,    up
;      @chapter Making Lists and Tables

; or like this (without the `@comment' line):

;      @node    Lists and Tables, Cross References, Structuring, Top
;      @chapter Making Lists and Tables

; If the file has a `top' node, it must be called `top' or `Top' and
; be the first node in the file.


;;;; The updating functions in detail
;    --------------------------------

; The `texinfo-update-node' function without an argument inserts
; the correct next, previous and up pointers for the node in which
; point is located (i.e., for the node preceding point).

; With an argument, the `texinfo-update-node' function inserts the
; correct next, previous and up pointers for the nodes inside the
; region.

; It does not matter whether the  `@node' line has pre-existing
; `Next', `Previous', or `Up' pointers in it.  They are removed.

; The `texinfo-every-node-update' function runs `texinfo-update-node'
; on the whole buffer.

; The `texinfo-update-node' function inserts the immediately following
; and preceding node into the `Next' or `Previous' pointers regardless
; of their hierarchical level.  This is only useful for certain kinds
; of text, like a novel, which you go through sequentially.  

; The `texinfo-make-menu' function without an argument creates or
; updates a menu for the section encompassing the node that follows
; point.  With an argument, it makes or updates menus for the nodes
; within or part of the marked region.

; Whenever an existing menu is updated, the descriptions from
; that menu are incorporated into the new menu.  This is done by copying
; descriptions from the existing menu to the entries in the new menu
; that have the same node names.  If the node names are different, the
; descriptions are not copied to the new menu.

; Menu entries that refer to other Info files are removed since they
; are not a node within current buffer.  This is a deficiency.

; The `texinfo-all-menus-update' function runs `texinfo-make-menu'
; on the whole buffer.

; The `texinfo-master-menu' function creates an extended menu located
; after the top node.  (The file must have a top node.)  The function
; first updates all the regular menus in the buffer (incorporating the
; descriptions from pre-existing menus), and then constructs a master
; menu that includes every entry from every other menu.  (However, the
; function cannot update an already existing master menu; if one
; exists, it must be removed before calling the function.)

; The `texinfo-indent-menu-description' function indents every
; description in the menu following point, to the specified column.
; Non-nil argument (prefix, if interactive) means indent every
; description in every menu in the region.  This function does not
; indent second and subsequent lines of a multi-line description.

; The `texinfo-insert-node-lines' function inserts `@node' before the
; `@chapter', `@section', and such like lines of a region in a Texinfo
; file where the `@node' lines are missing.
; 
; With a non-nil argument (prefix, if interactive), the function not
; only inserts `@node' lines but also inserts the chapter or section
; titles as the names of the corresponding nodes; and inserts titles
; as node names in pre-existing `@node' lines that lack names.
; 
; Since node names should be more concise than section or chapter
; titles, node names so inserted will need to be edited manually.

Eric S. Raymond's avatar
Eric S. Raymond committed
150
;;; Code:
Robert J. Chassell's avatar
Robert J. Chassell committed
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
 
;;;; Menu Making Functions

(defun texinfo-make-menu (&optional region-p)
  "Without any prefix argument, make or update a menu.
Make the menu for the section enclosing the node found following point.

Non-nil argument (prefix, if interactive) means make or update menus
for nodes within or part of the marked region.

Whenever a menu exists, and is being updated, the descriptions that
are associated with node names in the pre-existing menu are
incorporated into the new menu.  Otherwise, the nodes' section titles
are inserted as descriptions."
  
  (interactive "P")
  (if (not region-p)
      (let ((level (texinfo-hierarchic-level)))
        (texinfo-make-one-menu level)
        (message "Done...updated the menu.  You may save the buffer."))
    ;; else
    (message "Making or updating menus... ")
    (let ((beginning (region-beginning))
	  (region-end (region-end))
          (level (progn         ; find section type following point
                   (goto-char (region-beginning))
                   (texinfo-hierarchic-level))))
      (if (= region-end beginning)
          (error "Please mark a region!"))
      (save-excursion
        (save-restriction
          (widen)
          
          (while  (texinfo-find-lower-level-node level region-end)
            (setq level (texinfo-hierarchic-level)) ; new, lower level
            (texinfo-make-one-menu level))
          
          (while (and (< (point) region-end)
                      (texinfo-find-higher-level-node level region-end))
            (setq level (texinfo-hierarchic-level))
            (while (texinfo-find-lower-level-node level region-end)
              (setq level (texinfo-hierarchic-level)) ; new, lower level
              (texinfo-make-one-menu level))))))
    (message "Done...updated menus.  You may save the buffer.")))

(defun texinfo-make-one-menu (level)
  "Make a menu of all the appropriate nodes in this section.
`Appropriate nodes' are those associated with sections that are 
at the level specified by LEVEL.  Point is left at the end of menu."
  (let*
      ((case-fold-search t)
Jim Blandy's avatar
Jim Blandy committed
202 203 204 205 206
       (beginning
	(save-excursion
	  (goto-char (texinfo-update-menu-region-beginning level))
	  (end-of-line)
	  (point)))
Robert J. Chassell's avatar
Robert J. Chassell committed
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
       (end (texinfo-update-menu-region-end level))
       (first (texinfo-menu-first-node beginning end))
       (node-name (progn
                    (goto-char beginning)
                    (texinfo-copy-node-name)))
       (new-menu-list (texinfo-make-menu-list beginning end level)))
    (if (texinfo-old-menu-p beginning first)
        (progn
          (texinfo-incorporate-descriptions new-menu-list)
          (texinfo-delete-old-menu beginning first)))
    (texinfo-insert-menu new-menu-list node-name)))

(defun texinfo-all-menus-update (&optional update-all-nodes-p)
  "Update every regular menu in a Texinfo file.
You must remove the detailed part of a pre-existing master menu before
running this command, lest it be partly duplicated.

If called with a non-nil argument, this function first updates all the
nodes in the buffer before updating the menus."
  (interactive "P")
  (save-excursion
    (mark-whole-buffer)
    (message "Checking for a master menu... ")
    (save-excursion
      (if (re-search-forward texinfo-master-menu-header nil t)
          (error
           "Please remove existing master menu, lest it be partly duplicated!")))

  (if update-all-nodes-p
      (progn
        (message "First updating all nodes... ")
        (sleep-for 2)
        (mark-whole-buffer)
        (texinfo-update-node t)))

    (message "Updating all menus... ")
    (sleep-for 2)
    (texinfo-make-menu t)
    (message "Done...updated all the menus.  You may save the buffer.")))

(defun texinfo-find-lower-level-node (level region-end)
  "Search forward from point for node at any level lower than LEVEL.
Search is limited to the end of the marked region, REGION-END, 
and to the end of the menu region for the level.

Return t if the node is found, else nil.  Leave point at the beginning
of the node if one is found; else do not move point."

  (if (and (< (point) region-end)
           (re-search-forward
            (concat
             "\\(^@node\\).*\n"         ; match node line
             "\\(\\(\\(^@c\\).*\n\\)"   ; match comment line, if any
             "\\|"                      ; or
             "\\(^@ifinfo[ ]*\n\\)\\)?" ; ifinfo line, if any
             (eval (cdr (assoc level texinfo-update-menu-lower-regexps))))
            ;; the next higher level node marks the end of this
            ;; section, and no lower level node will be found beyond
            ;; this position even if region-end is farther off
            (texinfo-update-menu-region-end level) 
            t))
      (goto-char (match-beginning 1))))

(defun texinfo-find-higher-level-node (level region-end)
  "Search forward from point for node at any higher level than argument LEVEL.
Search is limited to the end of the marked region, REGION-END.

Return t if the node is found, else nil.  Leave point at the beginning
of the node if one is found; else do not move point."

  (if (and (< (point) region-end)
           (re-search-forward
            (concat
             "\\(^@node\\).*\n"         ; match node line
             "\\(\\(\\(^@c\\).*\n\\)"   ; match comment line, if any
             "\\|"                      ; or
             "\\(^@ifinfo[ ]*\n\\)\\)?" ; ifinfo line, if any
             (eval                      ; (won't ever find a `top' node)
              (cdr (assoc level texinfo-update-menu-higher-regexps))))
            nil
            t))
      (goto-char (match-beginning 1))))


;;;; Making the list of new menu entries

(defun texinfo-make-menu-list (beginning end level)
  "Make a list of node names and their descriptions.
Point is left at the end of the menu region, but the menu is not inserted.

First argument is position from which to start making menu list; 
second argument is end of region in which to try to locate entries;
third argument is the level of the nodes that are the entries.

Node names and descriptions are dotted pairs of strings.  Each pair is
an element of the list.  If the description does not exist, the
element consists only of the node name."
  (goto-char beginning)
  (let (new-menu-list)
    (while (texinfo-menu-locate-entry-p level end)
      (setq new-menu-list 
            (cons (cons 
                   (texinfo-copy-node-name)
                   (texinfo-copy-section-title))
                  new-menu-list)))
    (reverse new-menu-list)))

(defun texinfo-menu-locate-entry-p (level search-end)
  "Find a node that will be part of menu for this section.
First argument is a string such as \"section\" specifying the general
hierarchical level of the menu; second argument is a postion
specifying the end of the search.

The function returns t if the node is found, else nil.  It searches
forward from point, and leaves point at the beginning of the node.

The function finds entries of the same type.  Thus `subsections' and
`unnumberedsubsecs' will appear in the same menu."
  (if (re-search-forward
       (concat
        "\\(^@node\\).*\n"              ; match node line
        "\\(\\(\\(^@c\\).*\n\\)"        ; match comment line, if any
        "\\|"                           ; or
        "\\(^@ifinfo[ ]*\n\\)\\)?"      ; ifinfo line, if any
        (eval
         (cdr (assoc level texinfo-update-menu-same-level-regexps))))
       search-end
       t)
      (goto-char (match-beginning 1))))

(defun texinfo-copy-node-name ()
  "Return the node name as a string.

Start with point at the beginning of the node line; copy the text
after the node command up to the first comma on the line, if any, and
return the text as a string.  Leaves point at the beginning of the
line.  If there is no node name, returns an empty string."
  
  (save-excursion
    (buffer-substring
     (progn (forward-word 1)              ; skip over node command
            (skip-chars-forward " \t")    ; and over spaces
            (point))
     (if (search-forward
          ","
          (save-excursion (end-of-line) (point)) t) ; bound search
         (1- (point))
       (end-of-line) (point)))))

(defun texinfo-copy-section-title ()
  "Return the title of the section as a string.
The title is used as a description line in the menu when one does not
already exist.

Move point to the beginning of the appropriate section line by going
to the start of the text matched by last regexp searched for, which
must have been done by `texinfo-menu-locate-entry-p'."

  ;; could use the same re-search as in `texinfo-menu-locate-entry-p'
  ;; instead of using `match-beginning'; such a variation would be
  ;; more general, but would waste information already collected

  (goto-char (match-beginning 7))       ; match section name 

  (buffer-substring
   (progn (forward-word 1)              ; skip over section type
          (skip-chars-forward " \t")    ; and over spaces
          (point))
   (progn (end-of-line) (point))))


;;;; Handling the old menu

(defun texinfo-old-menu-p (beginning first)
  "Move point to the beginning of the menu for this section, if any.
Otherwise move point to the end of the first node of this section.
Return t if a menu is found, nil otherwise.

First argument is the position of the beginning of the section in which
the menu will be located; second argument is the position of the first
node within the section.

If no menu is found, the function inserts two newlines just before the
end of the section, and leaves point there where a menu ought to be."
  (goto-char beginning)
  (if (not (re-search-forward "^@menu" first 'goto-end))
      (progn (insert "\n\n") (forward-line -2) nil)
    t))

(defun texinfo-incorporate-descriptions (new-menu-list)
  "Copy the old menu line descriptions that exist to the new menu.

Point must be at beginning of old menu.

If the node-name of the new menu entry cannot be found in the old
menu, use the new section title for the description, but if the
node-name of the new menu is found in the old menu, replace the
section title with the old description, whatever it may be.

For this function, the new menu is a list made up of lists of dotted
pairs in which the first element of the pair is the node name and the
second element the description. The new menu is changed destructively.
The old menu is the menu as it appears in the texinfo file."
  
  (let ((new-menu-list-pointer new-menu-list)
        (end-of-menu (texinfo-menu-end)))
    (while new-menu-list
      (save-excursion                   ; keep point at beginning of menu 
        (if (search-forward
             (concat "\* "              ; so only menu entries are found
                     (car (car new-menu-list))
                     ":")               ; so only complete entries are found
             end-of-menu
             t) 
            (setcdr (car new-menu-list) 
                    (texinfo-menu-copy-old-description end-of-menu))))
      (setq new-menu-list (cdr new-menu-list))) 
    (setq new-menu-list new-menu-list-pointer)))

(defun texinfo-menu-copy-old-description (end-of-menu)
  "Return description field of old menu line as string.
Point must be located just after the node name.  Point left before description.
Single argument, END-OF-MENU, is position limiting search."
  (skip-chars-forward "[:.,\t\n ]+")
  ;; don't copy a carriage return at line beginning with asterisk!
  ;; do copy a description that begins with an `@'!
  (if (and (looking-at "\\(\\w+\\|@\\)")    
           (not (looking-at "\\(^\\* \\|^@end menu\\)")))  
      (buffer-substring
       (point)
       (save-excursion
         (re-search-forward "\\(^\\* \\|^@end menu\\)" end-of-menu t)
         (forward-line -1)
         (end-of-line)                  ; go to end of last description line
         (point)))
    ""))

(defun texinfo-menu-end ()
  "Return position of end of menu. Does not change location of point.
Signal an error if not end of menu."
  (save-excursion
    (if (re-search-forward "^@end menu" nil t)
        (point)
      (error "Menu does not have an end."))))

(defun texinfo-delete-old-menu (beginning first)
  "Delete the old menu.  Point must be in or after menu.
First argument is position of the beginning of the section in which
the menu will be located; second argument is the position of the first
node within the section."
  ;; No third arg to search, so error if search fails.
  (re-search-backward "^@menu" beginning)
  (delete-region (point)
                 (save-excursion
                   (re-search-forward "^@end menu" first)
                   (point))))


;;;; Inserting new menu

;; try 32, but perhaps 24 is better
(defvar texinfo-column-for-description 32
  "*Column at which descriptions start in a Texinfo menu.")

(defun texinfo-insert-menu (menu-list node-name)
  "Insert formatted menu at point.
Indents the first line of the description, if any, to the value of
texinfo-column-for-description.

MENU-LIST has form:

    \(\(\"node-name1\" . \"description\"\) 
    \(\"node-name\" . \"description\"\) ... \)

However, there does not need to be a description field."
  
  (insert "@menu\n")
  (while menu-list
    (if (cdr (car menu-list))       ; menu-list has description entry
        (progn
          (insert 
           (format "* %s::" (car (car menu-list)))) ; node-name entry
          (indent-to texinfo-column-for-description 2)
          (insert 
           (format "%s\n" (cdr (car menu-list)))))  ; description entry
        ;; else menu-list lacks description entry
      (insert
       (format "* %s::\n" (car (car menu-list)))))  ; node-name entry
    (setq menu-list (cdr menu-list)))
  (insert "@end menu")
  (message
   "Updated \"%s\" level menu following node: %s ... "
   level node-name))


;;;; Handling description indentation

; Since the make-menu functions indent descriptions, these functions
; are useful primarily for indenting a single menu specially.

(defun texinfo-indent-menu-description (column &optional region-p)
  "Indent every description in menu following point to COLUMN.  
Non-nil argument (prefix, if interactive) means indent every
description in every menu in the region.  Does not indent second and
subsequent lines of a multi-line description."
  
  (interactive
   "nIndent menu descriptions to (column number): \nP")
  (save-excursion
    (save-restriction
      (widen)
      (if (not region-p)
          (progn
            (re-search-forward "^@menu")
            (texinfo-menu-indent-description column)
            (message
             "Indented descriptions in menu.  You may save the buffer."))
        ;;else
        (message "Indenting every menu description in region... ")
        (goto-char (region-beginning))
        (while (and (< (point) (region-end))
                    (texinfo-locate-menu-p))
          (forward-line 1)
          (texinfo-menu-indent-description column))
        (message "Indenting done.  You may save the buffer.")))))

(defun texinfo-menu-indent-description (to-column-number)
  "Indent the Texinfo file menu description to TO-COLUMN-NUMBER.
Start with point just after the word `menu' in the `@menu' line and
leave point on the line before the `@end menu' line.  Does not indent
second and subsequent lines of a multi-line description."
  (let* ((beginning-of-next-line (point)))
    (while (< beginning-of-next-line
              (save-excursion     ; beginning of end menu line
                (goto-char (texinfo-menu-end))
                (beginning-of-line)
                (point)))
      (if (search-forward "::" (texinfo-menu-end) t)
          (progn
            (let ((beginning-white-space (point)))
              (skip-chars-forward " \t")  ; skip over spaces
              (if (looking-at "\\(@\\|\\w\\)+") ; if there is text
                  (progn
                    ;; remove pre-existing indentation
                    (delete-region beginning-white-space (point))
                    (indent-to-column to-column-number))))))
      ;; position point at beginning of next line
      (forward-line 1)                  
      (setq beginning-of-next-line (point)))))


;;;; Making the master menu

(defun texinfo-master-menu (update-all-nodes-menus-p)
  "Make a master menu for a whole Texinfo file.
Non-nil argument (prefix, if interactive) means first update all
existing nodes and menus.  Remove pre-existing master menu, if there is one.

This function creates a master menu that follows the top node.  The
master menu includes every entry from all the other menus.  It
replaces any existing ordinary menu that follows the top node.

If called with a non-nil argument, this function first updates all the
menus in the buffer (incorporating descriptions from pre-existing
menus) before it constructs the master menu.

The function removes the detailed part of an already existing master
menu.  This action depends on the pre-exisitng master menu using the
standard `texinfo-master-menu-header'.

The master menu has the following format, which is adapted from the
recommendation in the Texinfo Manual:

   * The first part contains the major nodes in the Texinfo file: the
     nodes for the chapters, chapter-like sections, and the major
     appendices.  This includes the indices, so long as they are in
     chapter-like sections, such as unnumbered sections.

   * The second and subsequent parts contain a listing of the other,
     lower level menus, in order.  This way, an inquirer can go
     directly to a particular node if he or she is searching for
     specific information.

Each of the menus in the detailed node listing is introduced by the
title of the section containing the menu."

  (interactive "P")
  (widen)
  (goto-char (point-min))

  ;; Move point to location after `top'.
Jim Blandy's avatar
Jim Blandy committed
598
  (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
Robert J. Chassell's avatar
Robert J. Chassell committed
599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792
      (error "This buffer needs a Top node!"))

  (let ((first-chapter                  
         (save-excursion (re-search-forward "^@node") (point))))
    (if (re-search-forward texinfo-master-menu-header first-chapter t)
        ;; Remove detailed master menu listing
        (progn
           (goto-char (match-beginning 0))
          (let ((end-of-detailed-menu-descriptions
                 (save-excursion     ; beginning of end menu line
                   (goto-char (texinfo-menu-end))
                   (beginning-of-line) (forward-char -1)
                   (point))))
            (delete-region (point) end-of-detailed-menu-descriptions)))))

  (if update-all-nodes-menus-p
      (progn
        (message "Making a master menu...first updating all nodes... ")
        (sleep-for 2)
        (mark-whole-buffer)
        (texinfo-update-node t)

        (message "Updating all menus... ")        
        (sleep-for 2)
        (mark-whole-buffer)
        (texinfo-make-menu t)))

  (message "Now making the master menu... ")
  (sleep-for 2)
  (goto-char (point-min))
  (texinfo-insert-master-menu-list
   (texinfo-master-menu-list))

  ;; Remove extra newlines that texinfo-insert-master-menu-list
  ;; may have inserted.

  (save-excursion
    (goto-char (point-min))
    
    (re-search-forward texinfo-master-menu-header)
    (goto-char (match-beginning 0))
    (insert "\n")
    (delete-blank-lines)
    
    (re-search-backward "^@menu")
    (forward-line -1)
    (delete-blank-lines)
    
    (re-search-forward "^@end menu")
    (forward-line 1)
    (delete-blank-lines))

  (message "Done...completed making master menu.  You may save the buffer."))

(defun texinfo-master-menu-list ()
  "Return a list of menu entries and header lines for the master menu.

Start with the menu for chapters and indices and then find each
following menu and the title of the node preceding that menu.

The master menu list has this form:

    \(\(\(... \"entry-1-2\"  \"entry-1\"\) \"title-1\"\)
      \(\(... \"entry-2-2\"  \"entry-2-1\"\) \"title-2\"\)
      ...\)

However, there does not need to be a title field."

  (let (master-menu-list)
    (while (texinfo-locate-menu-p)
      (setq master-menu-list 
            (cons (list
                   (texinfo-copy-menu)
                   (texinfo-copy-menu-title))
                  master-menu-list)))
    (reverse master-menu-list)))

(defun texinfo-insert-master-menu-list (master-menu-list)
  "Format and insert the master menu in the current buffer."
  (goto-char (point-min))
  (re-search-forward "^@menu")
  (beginning-of-line)
  (delete-region (point)        ; buffer must have ordinary top menu
                 (save-excursion
                   (re-search-forward "^@end menu")
                   (point)))

  (save-excursion                       ; leave point at beginning of menu
  ;; Handle top of menu
  (insert "\n@menu\n")
  ;; Insert chapter menu entries
  (setq this-very-menu-list (reverse (car (car master-menu-list))))
  ;;; Tell user what is going on.
  (message "Inserting chapter menu entry: %s ... " this-very-menu-list)
  (while this-very-menu-list
    (insert "* " (car this-very-menu-list) "\n")
    (setq this-very-menu-list (cdr this-very-menu-list)))
  
  (setq master-menu-list (cdr master-menu-list))

  (insert texinfo-master-menu-header)
  
  ;; Now, insert all the other menus

  ;; The menu master-menu-list has a form like this:
  ;; ((("beta"  "alpha") "title-A")
  ;;  (("delta" "gamma") "title-B"))

  (while master-menu-list

    (message
     "Inserting menu for %s .... " (car (cdr (car master-menu-list))))
    ;; insert title of menu section
    (insert "\n" (car (cdr (car master-menu-list))) "\n\n")

    ;; insert each menu entry
    (setq this-very-menu-list (reverse (car (car master-menu-list))))
    (while this-very-menu-list
      (insert "* " (car this-very-menu-list) "\n")
      (setq this-very-menu-list (cdr this-very-menu-list)))
    
    (setq master-menu-list (cdr master-menu-list)))
  
  ;; Finish menu
  (insert "@end menu\n\n")))

(defvar texinfo-master-menu-header
  "\n --- The Detailed Node Listing ---\n"
  "String inserted before lower level entries in Texinfo master menu.
It comes after the chapter-level menu entries.")

(defun texinfo-locate-menu-p ()
  "Find the next menu in the texinfo file.
If found, leave point after word `menu' on the `@menu' line, and return t.
If a menu is not found, do not move point and return nil."
  (re-search-forward "\\(^@menu\\)" nil t))

(defun texinfo-copy-menu-title  ()
  "Return the title of the section preceding the menu as a string.
If such a title cannot be found, return an empty string.  Do not move
point."
  (save-excursion
    (if (re-search-backward
         (concat
          "\\(^@node\\).*\n"            ; match node line
          "\\(\\(\\(^@c\\).*\n\\)"      ; match comment line, if any
          "\\|"                         ; or
          "\\(^@ifinfo[ ]*\n\\)\\)?"    ; ifinfo line, if any
          (eval
           (cdr
            (assoc (texinfo-hierarchic-level)
                   texinfo-update-menu-higher-regexps))))
         nil
         t)
        (texinfo-copy-section-title)
      " ")))

(defun texinfo-copy-menu ()
  "Return the entries of an existing menu as a list.
Start with point just after the word `menu' in the `@menu' line
and leave point on the line before the `@end menu' line."
  (let* (this-menu-list
         (end-of-menu (texinfo-menu-end)) ; position of end of `@end menu'
         (last-entry (save-excursion      ; position of beginning of
                                          ; last `* ' entry
                      (goto-char end-of-menu)
                      (re-search-backward "^\* ") ; handle multi-line desc.
                      (point))))
    (while (< (point) last-entry)
      (if (re-search-forward  "^\* " end-of-menu t)
          (progn
            (setq this-menu-list
                  (cons
                   (buffer-substring 
                    (point)
                    ;; copy multi-line descriptions
                    (save-excursion
                      (re-search-forward "\\(^\* \\|^@e\\)" nil t)
                      (- (point) 3)))
                   this-menu-list)))))
    this-menu-list))


;;;; Determining the hierarchical level in the texinfo file

(defun texinfo-specific-section-type () 
  "Return the specific type of next section, as a string.
For example, \"unnumberedsubsec\".  Return \"top\" for top node.

Searches forward for a section.  Hence, point must be before the
section whose type will be found.  Does not move point.  Signal an
error if the node is not the top node and a section is not found."
  (save-excursion
    (cond
Jim Blandy's avatar
Jim Blandy committed
793 794 795 796 797
     ((re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)"
			 (save-excursion
			   (end-of-line)
			   (point))
			 t)
Robert J. Chassell's avatar
Robert J. Chassell committed
798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824
      "top")
     ((re-search-forward texinfo-section-types-regexp nil t)
      (buffer-substring (progn (beginning-of-line) ; copy its name
                               (1+ (point)))
                        (progn (forward-word 1)
                               (point))))
     (t
      (error
       "texinfo-specific-section-type: Chapter or section not found.")))))

(defun texinfo-hierarchic-level ()
  "Return the general hierarchal level of the next node in a texinfo file.
Thus, a subheading or appendixsubsec is of type subsection."
  (cdr (assoc
        (texinfo-specific-section-type)
        texinfo-section-to-generic-alist)))


;;;; Locating the major positions

(defun texinfo-update-menu-region-beginning (level)  
  "Locate beginning of higher level section this section is within.
Return position of the beginning of the node line; do not move point.
Thus, if this level is subsection, searches backwards for section node.
Only argument is a string of the general type of section."
  
  (cond
Jim Blandy's avatar
Jim Blandy committed
825 826
   ((or (string-equal "top" level)
	(string-equal "chapter" level))
Robert J. Chassell's avatar
Robert J. Chassell committed
827
    (save-excursion
Jim Blandy's avatar
Jim Blandy committed
828 829 830
      (goto-char (point-min))
      (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t)
      (beginning-of-line)
Robert J. Chassell's avatar
Robert J. Chassell committed
831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948
      (point)))
   (t
    (save-excursion
      (re-search-backward
       (concat
        "\\(^@node\\).*\n"              ; match node line
        "\\(\\(\\(^@c\\).*\n\\)"        ; match comment line, if any
        "\\|"                           ; or
        "\\(^@ifinfo[ ]*\n\\)\\)?"      ; ifinfo line, if any
        (eval
         (cdr (assoc level texinfo-update-menu-higher-regexps))))
       nil
       'goto-beginning)
      (point)))))

(defun texinfo-update-menu-region-end (level)  
  "Locate end of higher level section this section is within.
Return position; do not move point.  Thus, if this level is a
subsection, find the node for the section this subsection is within.
If level is top or chapter, returns end of file.  Only argument is a
string of the general type of section."

  (save-excursion
    (if (re-search-forward
         (concat
          "\\(^@node\\).*\n"            ; match node line
          "\\(\\(\\(^@c\\).*\n\\)"      ; match comment line, if any
          "\\|"                         ; or
          "\\(^@ifinfo[ ]*\n\\)\\)?"    ; ifinfo line, if any
          (eval
           (cdr (assoc level texinfo-update-menu-higher-regexps))))
         nil
         'goto-end)
        (match-beginning 1)
      (point-max))))

(defun texinfo-menu-first-node (beginning end)
  "Locate first node of the section the menu will be placed in.  
Return position; do not move point.
The menu will be located just before this position.  

First argument is the position of the beginning of the section in
which the menu will be located; second argument is the position of the
end of that region; it limits the search."
  
  (save-excursion
    (goto-char beginning)
    (forward-line 1)
    (re-search-forward "^@node" end t)
    (beginning-of-line)
    (point)))


;;;; Alists and regular expressions for defining hierarchical levels

(defvar texinfo-section-to-generic-alist
  '(("top" . "top")

    ("chapter" . "chapter")
    ("unnumbered" . "chapter")
    ("majorheading" . "chapter")
    ("chapheading" . "chapter")
    ("appendix" . "chapter")
    
    ("section" . "section")
    ("unnumberedsec" . "section")
    ("heading" . "section")
    ("appendixsec" . "section")
    
    ("subsection" . "subsection")
    ("unnumberedsubsec" . "subsection")
    ("subheading" . "subsection")
    ("appendixsubsec" . "subsection")
    
    ("subsubsection" . "subsubsection")
    ("unnumberedsubsubsec" . "subsubsection")
    ("subsubheading" . "subsubsection")
    ("appendixsubsubsec" . "subsubsection"))
  "*An alist of specific and corresponding generic Texinfo section types.
The keys are strings specifying specific types of section; the values
are strings of their corresponding general types.")

(defvar texinfo-section-types-regexp
  "^@\\(chapter \\|sect\\|sub\\|unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
  "Regexp matching chapter, section, other headings (but not the top node).")

(defvar texinfo-chapter-level-regexp 
  "chapter\\|unnumbered \\|appendix \\|majorheading\\|chapheading"
  "Regular expression matching just the Texinfo chapter level headings.")

(defvar texinfo-section-level-regexp 
  "section\\|unnumberedsec\\|heading \\|appendixsec"
  "Regular expression matching just the Texinfo section level headings.")

(defvar texinfo-subsection-level-regexp 
  "subsection\\|unnumberedsubsec\\|subheading\\|appendixsubsec"
  "Regular expression matching just the Texinfo subsection level headings.")

(defvar texinfo-subsubsection-level-regexp
  "subsubsection\\|unnumberedsubsubsec\\|subsubheading\\|appendixsubsubsec"
  "Regular expression matching just the Texinfo subsubsection level headings.")

(defvar texinfo-update-menu-same-level-regexps
  '(("top" . "top[ \t]+")
    ("chapter" . 
     (concat "\\(^@\\)\\(" texinfo-chapter-level-regexp "\\)[ \t]*"))
    ("section" . 
     (concat "\\(^@\\)\\(" texinfo-section-level-regexp "\\)[ \t]*"))
    ("subsection" .  
     (concat "\\(^@\\)\\(" texinfo-subsection-level-regexp "\\)[ \t]+"))
    ("subsubsection" . 
     (concat "\\(^@\\)\\(" texinfo-subsubsection-level-regexp "\\)[ \t]+")))
  "*Regexps for searching for same level sections in a Texinfo file.
The keys are strings specifying the general hierarchical level in the
document; the values are regular expressions.")

(defvar texinfo-update-menu-higher-regexps
  '(("top" . "^@node [ \t]*DIR") 
Jim Blandy's avatar
Jim Blandy committed
949
    ("chapter" . "^@node [ \t]*top[ \t]*\\(,\\|$\\)")
Robert J. Chassell's avatar
Robert J. Chassell committed
950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038
    ("section" .
     (concat 
      "\\(^@\\("
      texinfo-chapter-level-regexp
      "\\)[ \t]*\\)"))
    ("subsection" .
     (concat 
      "\\(^@\\("
      texinfo-section-level-regexp
      "\\|"
      texinfo-chapter-level-regexp
      "\\)[ \t]*\\)"))
    ("subsubsection" .
     (concat 
      "\\(^@\\("
      texinfo-subsection-level-regexp
      "\\|"
      texinfo-section-level-regexp
      "\\|"
      texinfo-chapter-level-regexp
      "\\)[ \t]*\\)")))
  "*Regexps for searching for higher level sections in a Texinfo file.
The keys are strings specifying the general hierarchical level in the
document; the values are regular expressions.")

(defvar texinfo-update-menu-lower-regexps
  '(("top" . 
     (concat 
      "\\(^@\\("
      texinfo-chapter-level-regexp
      "\\|"
      texinfo-section-level-regexp
      "\\|"
      texinfo-subsection-level-regexp
      "\\|"
      texinfo-subsubsection-level-regexp
      "\\)[ \t]*\\)"))
    ("chapter" . 
     (concat 
      "\\(^@\\("
      texinfo-section-level-regexp
      "\\|"
      texinfo-subsection-level-regexp
      "\\|"
      texinfo-subsubsection-level-regexp
      "\\)[ \t]*\\)"))
    ("section" .
     (concat 
      "\\(^@\\("
      texinfo-subsection-level-regexp
      "\\|"
      texinfo-subsubsection-level-regexp
      "\\)[ \t]+\\)"))
    ("subsection" .
     (concat 
      "\\(^@\\("
      texinfo-subsubsection-level-regexp
      "\\)[ \t]+\\)"))
    ("subsubsection" . "nothing lower"))
  "*Regexps for searching for lower level sections in a Texinfo file.
The keys are strings specifying the general hierarchical level in the
document; the values are regular expressions.")


;;;; Updating a Node

(defun texinfo-update-node (&optional region-p)
  "Without any prefix argument, update the node in which point is located.
Non-nil argument (prefix, if interactive) means update the nodes in the
marked region.

The functions for creating or updating nodes and menus, and their
keybindings, are:

    texinfo-update-node (&optional region-p)    \\[texinfo-update-node]
    texinfo-every-node-update ()                \\[texinfo-every-node-update]
    texinfo-sequential-node-update (&optional region-p)

    texinfo-make-menu (&optional region-p)      \\[texinfo-make-menu]
    texinfo-all-menus-update ()                 \\[texinfo-all-menus-update]
    texinfo-master-menu ()

    texinfo-indent-menu-description (column &optional region-p)

The `texinfo-column-for-description' variable specifies the column to
which menu descriptions are indented. Its default value is 24."
  
  (interactive "P")
  (if (not region-p)
Jim Blandy's avatar
Jim Blandy committed
1039
      (let ((auto-fill-function nil)) ; update a single node
Robert J. Chassell's avatar
Robert J. Chassell committed
1040 1041 1042 1043 1044
        (if (not (re-search-backward "^@node" (point-min) t))
            (error "Node line not found before this position."))
        (texinfo-update-the-node)
        (message "Done...updated the node.  You may save the buffer."))
    ;; else
Jim Blandy's avatar
Jim Blandy committed
1045
    (let ((auto-fill-function nil)
Robert J. Chassell's avatar
Robert J. Chassell committed
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252
          (beginning (region-beginning))
	  (end (region-end)))
      (if (= end beginning)
          (error "Please mark a region!"))
      (save-restriction
	(narrow-to-region beginning end)
	(goto-char beginning)
        (push-mark)
	(while (re-search-forward "^@node" (point-max) t)
          (beginning-of-line)            
          (texinfo-update-the-node))
        (message "Done...updated nodes in region.  You may save the buffer.")))))

(defun texinfo-every-node-update ()
  "Update every node in a Texinfo file."
  (interactive)
  (save-excursion
    (mark-whole-buffer)
    (texinfo-update-node t)
    (message "Done...updated every node.       You may save the buffer.")))

(defun texinfo-update-the-node ()
  "Update one node.  Point must be at the beginning of node line.  
Leave point at the end of the node line."
  (texinfo-check-for-node-name)
  (texinfo-delete-existing-pointers)
  (message "Updating node: %s ... " (texinfo-copy-node-name))
  (save-restriction
    (widen)
    (let*
        ((case-fold-search t)
         (level (texinfo-hierarchic-level))
         (beginning (texinfo-update-menu-region-beginning level))
         (end (texinfo-update-menu-region-end level)))
      (if (string-equal level "top")
          (texinfo-top-pointer-case)
        ;; else
        (texinfo-insert-pointer beginning end level 'next)
        (texinfo-insert-pointer beginning end level 'previous)
        (texinfo-insert-pointer beginning end level 'up)
        (texinfo-clean-up-node-line)))))

(defun texinfo-top-pointer-case ()
  "Insert pointers in the Top node.  This is a special case.

The `Next' pointer is a pointer to a chapter or section at a lower
hierarchical level in the file.  The `Previous' and `Up' pointers are
to `(dir)'.  Point must be at the beginning of the node line, and is
left at the end of the node line."

  (texinfo-clean-up-node-line)
  (insert ", " 
          (save-excursion
            ;; There may be an @chapter or other such command between
            ;; the top node line and the next node line, as a title
            ;; for an `ifinfo' section. This @chapter command must
            ;; must be skipped.  So the procedure is to search for
            ;; the next `@node' line, and then copy its name.
            (if (re-search-forward "^@node" nil t)
                (progn
                  (beginning-of-line)
                  (texinfo-copy-node-name))
              " "))
          ", (dir), (dir)"))

(defun texinfo-check-for-node-name ()
  "Determine whether the node has a node name.  Prompt for one if not.
Point must be at beginning of node line.  Does not move point."
  (save-excursion
    (forward-word 1)                    ; skip over node command
    (skip-chars-forward " \t")          ; and over spaces
    (if (not (looking-at "[^,\t\n ]+")) ; regexp based on what info looks for
                                        ; alternatively, use "[a-zA-Z]+"
        (let ((node-name (read-from-minibuffer "Node name: ")))
          (insert " " node-name)))))

(defun texinfo-delete-existing-pointers ()
  "Delete `Next', `Previous', and `Up' pointers.  
Starts from the current position of the cursor, and searches forward
on the line for a comma and if one is found, deletes the rest of the
line, including the comma.  Leaves point at beginning of line."
  (if (search-forward "," (save-excursion (end-of-line) (point)) t)
      (progn
        (goto-char (1- (point)))
        (kill-line nil)))
  (beginning-of-line))

(defun texinfo-find-pointer (beginning end level direction)
  "Move point to section associated with next, previous, or up pointer.
Return type of pointer (either 'normal or 'no-pointer).

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is a string specifying the general kind
of section such as \"chapter\ or \"section\".  When looking for the
`Next' pointer, the section found will be at the same hierarchical
level in the Texinfo file; when looking for the `Previous' pointer,
the section found will be at the same or higher hierarchical level in
the Texinfo file; when looking for the `Up' pointer, the section found
will be at some level higher in the Texinfo file.  The fourth argument
\(one of 'next, 'previous, or 'up\) specifies whether to find the
`Next', `Previous', or `Up' pointer."

  (cond ((eq direction 'next)
         (forward-line 3)             ; skip over current node
         (if (re-search-forward
              (eval
               (cdr (assoc level texinfo-update-menu-same-level-regexps)))
              end
              t)
             'normal
           'no-pointer))
        ((eq direction 'previous)
         (if (re-search-backward
              (concat
               "\\("
               (eval
                (cdr (assoc level texinfo-update-menu-same-level-regexps)))
               "\\|"
               (eval
                (cdr (assoc level texinfo-update-menu-higher-regexps)))
               "\\)")
              beginning
              t)
             'normal
           'no-pointer))
        ((eq direction 'up)
         (if (re-search-backward
             (eval (cdr (assoc level texinfo-update-menu-higher-regexps)))
              (save-excursion
                (goto-char beginning)
                (beginning-of-line)
                (point))
              t)
             'normal
           'no-pointer))
        (t
         (error "texinfo-find-pointer: lack proper arguments"))))

(defun texinfo-pointer-name (kind)
  "Return the node name preceding the section command.
The argument is the kind of section, either normal or no-pointer."
  (let (name)
    (cond ((eq kind 'normal)
           (end-of-line)                ; this handles prev node top case
           (re-search-backward          ; when point is already 
            "^@node"                    ; at the beginning of @node line
            (save-excursion (forward-line -3))
            t)
           (setq name (texinfo-copy-node-name)))
	  ((eq kind 'no-pointer)
	   (setq name " ")))	; put a blank in the pointer slot
    name))

(defun texinfo-insert-pointer (beginning end level direction)
  "Insert the `Next', `Previous' or `Up' node name at point.
Move point forward.  

The first and second arguments bound the search for a pointer to the
beginning and end, respectively, of the enclosing higher level
section.  The third argument is the hierarchical level of the Texinfo
file, a string such as \"section\".  The fourth argument is direction
towards which the pointer is directed, one of `next, `previous, or
'up."

  (end-of-line)
  (insert
   ", "
   (save-excursion
     (texinfo-pointer-name
      (texinfo-find-pointer beginning end level direction)))))

(defun texinfo-clean-up-node-line ()
  "Remove extra commas, if any, at end of node line."
  (end-of-line)
  (skip-chars-backward ", ")
  (delete-region (point) (save-excursion (end-of-line) (point))))


;;;; Updating nodes sequentially
; These sequential update functions insert `Next' or `Previous'
; pointers that point to the following or preceding nodes even if they
; are at higher or lower hierarchical levels.  This means that if a
; section contains one or more subsections, the section's `Next'
; pointer will point to the subsection and not the following section.
; (The subsection to which `Next' points will most likely be the first
; item on the section's menu.)

(defun texinfo-sequential-node-update (&optional region-p)
  "Update one node (or many) in a Texinfo file with sequential pointers.

This function causes the `Next' or `Previous' pointer to point to the
immediately preceding or following node, even if it is at a higher or
lower hierarchical level in the document.  Continually pressing `n' or
`p' takes you straight through the file.

Without any prefix argument, update the node in which point is located.
Non-nil argument (prefix, if interactive) means update the nodes in the
marked region.

This command makes it awkward to navigate among sections and
subsections; it should be used only for those documents that are meant
to be read like a novel rather than a reference, and for which the
Info `g*' command is inadequate."
  
  (interactive "P")
  (if (not region-p)
Jim Blandy's avatar
Jim Blandy committed
1253
      (let ((auto-fill-function nil))   ; update a single node
Robert J. Chassell's avatar
Robert J. Chassell committed
1254 1255 1256 1257 1258 1259
        (if (not (re-search-backward "^@node" (point-min) t))
            (error "Node line not found before this position."))
        (texinfo-sequentially-update-the-node)
        (message 
         "Done...sequentially updated the node .  You may save the buffer."))
    ;; else
Jim Blandy's avatar
Jim Blandy committed
1260
    (let ((auto-fill-function nil)
Robert J. Chassell's avatar
Robert J. Chassell committed
1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535
          (beginning (region-beginning))
          (end (region-end)))
      (if (= end beginning)
          (error "Please mark a region!"))
      (save-restriction
        (narrow-to-region beginning end)
        (goto-char beginning)
        (push-mark)
        (while (re-search-forward "^@node" (point-max) t)
          (beginning-of-line)            
          (texinfo-sequentially-update-the-node))
        (message 
         "Done...updated the nodes in sequence.  You may save the buffer.")))))

(defun texinfo-sequentially-update-the-node ()
  "Update one node such that the pointers are sequential. 
A `Next' or `Previous' pointer points to any preceding or following node,
regardless of its hierarchical level."

        (texinfo-check-for-node-name)
        (texinfo-delete-existing-pointers)
        (message 
         "Sequentially updating node: %s ... " (texinfo-copy-node-name))
        (save-restriction
          (widen)
          (let*
              ((case-fold-search t)
               (level (texinfo-hierarchic-level)))
            (if (string-equal level "top")
                (texinfo-top-pointer-case)
              ;; else
              (texinfo-sequentially-insert-pointer level 'next)
              (texinfo-sequentially-insert-pointer level 'previous)
              (texinfo-sequentially-insert-pointer level 'up)
              (texinfo-clean-up-node-line)))))

(defun texinfo-sequentially-find-pointer (level direction)
  "Find next or previous pointer sequentially in Texinfo file, or up pointer.
Move point to section associated with the pointer.  Find point even if
it is in a different section.

Return type of pointer (either 'normal or 'no-pointer).

The first argument is a string specifying the general kind of section
such as \"chapter\ or \"section\".  The section found will be at the
same hierarchical level in the Texinfo file, or, in the case of the up
pointer, some level higher.  The second argument (one of 'next,
'previous, or 'up) specifies whether to find the `Next', `Previous',
or `Up' pointer."
  
  (cond ((eq direction 'next)
         (forward-line 3)             ; skip over current node
         (if (re-search-forward 
              texinfo-section-types-regexp
              (point-max)
              t)
             'normal
           'no-pointer))
        ((eq direction 'previous)
         (if (re-search-backward 
              texinfo-section-types-regexp
              (point-min)
              t)
             'normal
           'no-pointer))
        ((eq direction 'up)
         (if (re-search-backward
              (eval (cdr (assoc level texinfo-update-menu-higher-regexps)))
              beginning
              t)
             'normal
           'no-pointer))
        (t
         (error "texinfo-sequential-find-pointer: lack proper arguments"))))

(defun texinfo-sequentially-insert-pointer (level direction)
  "Insert the `Next', `Previous' or `Up' node name at point.
Move point forward.  

The first argument is the hierarchical level of the Texinfo file, a
string such as \"section\".  The second argument is direction, one of
`next, `previous, or 'up."

  (end-of-line)
  (insert
   ", "
   (save-excursion
     (texinfo-pointer-name
      (texinfo-sequentially-find-pointer level direction)))))


;;;; Inserting `@node' lines
; The `texinfo-insert-node-lines' function inserts `@node' lines as needed
; before the `@chapter', `@section', and such like lines of a region
; in a Texinfo file.

(defun texinfo-insert-node-lines (&optional title-p)
  "Insert missing `@node' lines in region of Texinfo file.
Non-nil argument (prefix, if interactive) means also to insert the
section titles as node names; and also to insert the section titles as
node names in pre-existing @node lines that lack names."
  (interactive "P")
  (save-excursion
    (let ((begin-region  (region-beginning))
          (end-region (region-end)))
      (goto-char begin-region)
      (while (< (point) end-region)
        (re-search-forward texinfo-section-types-regexp nil 'end)
        ;; copy title, since most often, we will need it
        (let ((title
               (progn
                 (beginning-of-line)
                 (forward-word 1)
                 (skip-chars-forward " \t")
                 (buffer-substring
                  (point)
                  (save-excursion (end-of-line) (point))))))
          ;; insert a node if necessary
          (if (re-search-backward
               "^@node"
               (save-excursion
                 (forward-line -3)
                 (point))
               t)
              ;;  @node present, and point at beginning of that line
              (forward-word 1)
            ;; else @node missing, insert one
            (progn
              (beginning-of-line)       ; beginning of `@section' line
              (insert "@node\n")
              (backward-char 1)))       ; leave point just after `@node'
          ;; insert a title if warranted
          (if title-p
              (progn
                (skip-chars-forward " \t")
                ;; use regexp based on what info looks for
                ;; (alternatively, use "[a-zA-Z]+")
                (if (not (looking-at "[^,\t\n ]+")) 
                    (progn
                      (beginning-of-line) 
                      (forward-word 1)
                      (insert " " title)
                      (message "Inserted title %s ... " title)))))
          ;; in any case, go forward beyond current section title
          (forward-line 3)))))
  (if title-p
      (message
       "Done inserting node lines and titles.  You may save the buffer.")
    (message "Done inserting node lines.  You may save the buffer.")))


;;;; Update and create menus for multi-file Texinfo sources

;;  1. M-x texinfo-multiple-files-update 
;;
;;     Read the include file list of an outer Texinfo file and
;;     update all highest level nodes in the files listed and insert a
;;     main menu in the outer file after its top node.

;;  2. C-u M-x texinfo-multiple-files-update 
;;
;;     Same as 1, but insert a master menu.  (Saves reupdating lower
;;     level menus and nodes.)  This command simply reads every menu,
;;     so if the menus are wrong, the master menu will be wrong.
;;     Similarly, if the lower level node pointers are wrong, they
;;     will stay wrong.

;;  3. C-u 2 M-x texinfo-multiple-files-update 
;;
;;     Read the include file list of an outer Texinfo file and
;;     update all nodes and menus in the files listed and insert a
;;     master menu in the outer file after its top node.

;;; Note: these functions:
;;;
;;;   * Do not save or delete any buffers.  You may fill up your memory.
;;;   * Do not handle any pre-existing nodes in outer file.  
;;;     Hence, you may need a file for indices.


;;;; Auxiliary functions for multiple file updating

(defun texinfo-multi-file-included-list (outer-file)
  "Return a list of the included files in OUTER-FILE."
  (let ((included-file-list (list outer-file))
        start)
    (save-excursion
      (switch-to-buffer (find-file-noselect outer-file))
      (widen)
      (goto-char (point-min))
      (while (re-search-forward "^@include" nil t)
        (skip-chars-forward " \t")
        (setq start (point))
        (end-of-line)
        (skip-chars-backward " \t")   
        (setq included-file-list
              (cons (buffer-substring start (point))
                    included-file-list)))
      (nreverse included-file-list))))

(defun texinfo-copy-next-section-title ()
  "Return the name of the immediately following section as a string.

Start with point at the beginning of the node line.  Leave point at the
same place.  If there is no title, returns an empty string."

  (save-excursion
    (end-of-line)
    (let ((section-end (or 
                        (save-excursion
                          (re-search-forward "\\(^@node\\)" nil t)
                          (match-beginning 0))
                        (point-max))))
      (if (re-search-forward texinfo-section-types-regexp section-end t)
          ;; copy title
          (let ((title
                 (buffer-substring
                  (progn (forward-word 1)           ; skip over section type
                         (skip-chars-forward " \t") ; and over spaces
                         (point))
                  (progn (end-of-line) (point)))))
            title)
        ""))))

(defun texinfo-multi-file-update (files &optional update-everything)
  "Update first node pointers in each file in FILES.
Return a list of the node names and the title immediate following them.

The first file in the list is an outer file; the remaining are
files included in the outer file with `@include' commands.

If optional arg UPDATE-EVERYTHING non-nil, update every menu and
pointer in each of the included files.

Also update the `Top' level node pointers of the outer file.

Requirements:

  * the first file in the FILES list must be the outer file,
  * each of the included files must contain exactly one highest
    hierarchical level node, 
  * this node must be the first node in the included file,
  * each highest hierarchical level node must be of the same type.

Thus, normally, each included file contains one, and only one,
chapter.

The menu-list has the form:

    \(\(\"node-name1\" . \"title1\"\) 
      \(\"node-name2\" . \"title2\"\) ... \)

However, there does not need to be a title field."
  
  (let (menu-list)
    
    ;; Find the name of the first node of the first included file.
    (switch-to-buffer (find-file-noselect (car (cdr files))))
    (widen)
    (goto-char (point-min))
    (if (not (re-search-forward "^@node" nil t))
        (error "No `@node' line found in %s !" (buffer-name)))
    (beginning-of-line)
    (texinfo-check-for-node-name)
    (setq next-node-name (texinfo-copy-node-name))
    
    (setq menu-list
          (cons (cons 
                 next-node-name
                 (texinfo-copy-next-section-title))
                menu-list))
    
    ;; Go to outer file
    (switch-to-buffer (find-file-noselect (car files)))
    (goto-char (point-min))
Jim Blandy's avatar
Jim Blandy committed
1536
    (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
Robert J. Chassell's avatar
Robert J. Chassell committed
1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727
        (error "This buffer needs a Top node!"))
    (beginning-of-line)
    (texinfo-delete-existing-pointers)
    (end-of-line)
    (insert ", " next-node-name ", (dir), (dir)")
    (beginning-of-line)
    (setq previous-node-name "Top")
    (setq files (cdr files))
    
    (while files
      
      (if (not (cdr files))
          ;; No next file
          (setq next-node-name "")
        ;; Else,
        ;; find the name of the first node in the next file.
        (switch-to-buffer (find-file-noselect (car (cdr files))))
        (widen)
        (goto-char (point-min))
        (if (not (re-search-forward "^@node" nil t))
            (error "No `@node' line found in %s !" (buffer-name)))
        (beginning-of-line)
        (texinfo-check-for-node-name)
        (setq next-node-name (texinfo-copy-node-name))
        (setq menu-list
              (cons (cons 
                     next-node-name
                     (texinfo-copy-next-section-title))
                    menu-list)))

      ;; Go to node to be updated.
      (switch-to-buffer (find-file-noselect (car files)))
      (goto-char (point-min))
      (if (not (re-search-forward "^@node" nil t))
          (error "No `@node' line found in %s !" (buffer-name)))
      (beginning-of-line)
      (texinfo-delete-existing-pointers)
      (end-of-line)
      (insert ", " next-node-name ", " previous-node-name ", " up-node-name)
      
      (beginning-of-line)
      (setq previous-node-name (texinfo-copy-node-name))
      
      ;; Update other menus and nodes if requested.
      (if update-everything (texinfo-all-menus-update t))
      
      (setq files (cdr files)))
    (nreverse menu-list)))

(defun texinfo-multi-files-insert-main-menu (menu-list)
  "Insert formatted main menu at point.
Indents the first line of the description, if any, to the value of
texinfo-column-for-description."

  (insert "@menu\n")
  (while menu-list
    (if (cdr (car menu-list))       ; menu-list has description entry
        (progn
          (insert 
           (format "* %s::" (car (car menu-list)))) ; node-name entry
          (indent-to texinfo-column-for-description 2)
          (insert 
           (format "%s\n" (cdr (car menu-list)))))  ; description entry
        ;; else menu-list lacks description entry
      (insert
       (format "* %s::\n" (car (car menu-list)))))  ; node-name entry
    (setq menu-list (cdr menu-list)))
  (insert "@end menu"))


(defun texinfo-multi-file-master-menu-list (files-list)
  "Return master menu list from files in FILES-LIST.
Menu entries in each file collected using `texinfo-master-menu-list'.

The first file in FILES-LIST must be the outer file; the others must
be the files included within it.  A main menu must already exist."
  (save-excursion
    (let (master-menu-list)
      (while files-list
        (switch-to-buffer (find-file-noselect (car files-list)))
        (message "Working on: %s " (current-buffer))
        (goto-char (point-min))
        (setq master-menu-list
              (append master-menu-list (texinfo-master-menu-list)))
        (setq files-list (cdr files-list)))
      master-menu-list)))


;;;; The multiple-file update function

(defun texinfo-multiple-files-update
  (outer-file &optional update-everything make-master-menu)
  "Update first node pointers in each file included in OUTER-FILE;
create or update main menu in the outer file that refers to such nodes. 
This does not create or update menus or pointers within the included files.

With optional MAKE-MASTER-MENU argument (prefix arg, if interactive),
insert a master menu in OUTER-FILE.  This does not create or update
menus or pointers within the included files.

With optional UPDATE-EVERYTHING argument (numeric prefix arg, if
interactive), update all the menus and all the `Next', `Previous', and
`Up' pointers of all the files included in OUTER-FILE before inserting
a master menu in OUTER-FILE.

The command also updates the `Top' level node pointers of OUTER-FILE.

Notes: 

  * this command does NOT save any files--you must save the
    outer file and any modified, included files.

  * except for the `Top' node, this command does NOT handle any
    pre-existing nodes in the outer file; hence, indices must be
    enclosed in an included file.

Requirements:

  * each of the included files must contain exactly one highest
    hierarchical level node, 
  * this highest node must be the first node in the included file,
  * each highest hierarchical level node must be of the same type.

Thus, normally, each included file contains one, and only one,
chapter."

  (interactive "fName of outer `include' file: ")

  (cond (current-prefix-arg
         (setq make-master-menu (listp current-prefix-arg))
         (setq update-everything (numberp current-prefix-arg))))

  (let* ((included-file-list (texinfo-multi-file-included-list outer-file))
         (files included-file-list)
         main-menu-list
         next-node-name
         previous-node-name
         (up-node-name "Top"))

;;; Update the pointers 
;;; and collect the names of the nodes and titles
    (setq main-menu-list (texinfo-multi-file-update files update-everything))

;;; Insert main menu

  ;; Go to outer file
  (switch-to-buffer (find-file-noselect (car included-file-list)))
  (if (texinfo-old-menu-p
       (point-min)
       (save-excursion
         (re-search-forward "^@include")
         (beginning-of-line)
         (point)))

      ;; If found, leave point after word `menu' on the `@menu' line.
      (progn
        (texinfo-incorporate-descriptions main-menu-list)
        ;; Delete existing menu.
        (beginning-of-line)
        (delete-region
         (point)
         (save-excursion (re-search-forward "^@end menu") (point)))
        ;; Insert main menu
        (texinfo-multi-files-insert-main-menu main-menu-list))

    ;; Else no current menu; insert it before `@include'
    (texinfo-multi-files-insert-main-menu main-menu-list))

;;; Insert master menu

  (if make-master-menu
      (progn
        ;; First, removing detailed part of any pre-existing master menu
        (goto-char (point-min))
        (if (re-search-forward texinfo-master-menu-header nil t)
            ;; Remove detailed master menu listing
            (progn
              (goto-char (match-beginning 0))
              (let ((end-of-detailed-menu-descriptions
                     (save-excursion     ; beginning of end menu line
                       (goto-char (texinfo-menu-end))
                       (beginning-of-line) (forward-char -1)
                       (point))))
                (delete-region (point) end-of-detailed-menu-descriptions))))

        ;; Create a master menu and insert it
        (texinfo-insert-master-menu-list 
         (texinfo-multi-file-master-menu-list 
          included-file-list)))))
  (message "Multiple files updated."))

Jim Blandy's avatar
Jim Blandy committed
1728 1729
(provide 'texnfo-upd)

Eric S. Raymond's avatar
Eric S. Raymond committed
1730
;;; texnfo-upd.el ends here