;;; texnfo-upd.el --- utilities for updating nodes and menus in Texinfo files;; Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.;; Author: Robert J. Chassell      ;; Maintainer: bug-texinfo@prep.ai.mit.edu;; Keywords: maint, tex, docs;; 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;; the Free Software Foundation; either version 2, or (at your option);; 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, Inc., 59 Temple Place - Suite 330,;; Boston, MA 02111-1307, USA.;;; Commentary:;; Known bug: update commands fail to ignore @ignore.;; Summary: how to use the updating commands;; 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.;;;; With a prefix argument, the `texinfo-update-node' and;; `texinfo-make-menu' functions do their jobs in the region.;;;; In brief, the functions for creating or updating nodes and menus, are:;; ;;     texinfo-update-node (&optional beginning end)            ;;     texinfo-every-node-update ()                        ;;     texinfo-sequential-node-update (&optional region-p);; ;;     texinfo-make-menu (&optional beginning end)              ;;     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 update node functions described in detail;; The `texinfo-update-node' command with no prefix 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 prefix 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-sequential-node-update' 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 menu making functions described in detail;; 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. ;;; Code:(defvar texinfo-master-menu-header  " --- 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-make-menu (&optional beginning end)  "Without any prefix argument, make or update a menu.Make the menu for the section enclosing the node found following point.A prefix argument means make or update menusfor nodes within or part of the marked region.Whenever a menu exists, and is being updated, the descriptions thatare associated with node names in the pre-existing menu areincorporated into the new menu.  Otherwise, the nodes' section titlesare inserted as descriptions."    (interactive   (if prefix-arg       (list (point) (mark))))  (if (null beginning)      (let ((level (texinfo-hierarchic-level)))        (texinfo-make-one-menu level)        (message "Menu updated"))    ;; else    (message "Making or updating menus in %s... " (buffer-name))    (save-excursion      (goto-char (min beginning end))      ;; find section type following point      (let ((level (texinfo-hierarchic-level))	    (region-end (max beginning end)))        (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 "Making or updating menus in %s...done" (buffer-name))))(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)       (beginning	(save-excursion	  (goto-char (texinfo-update-menu-region-beginning level))	  (end-of-line)	  (point)))       (end (texinfo-update-menu-region-end level))       (first (texinfo-menu-first-node beginning end))       (node-name (progn                    (goto-char beginning)                    (beginning-of-line)                    (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-incorporate-menu-entry-names 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.Update pre-existing master menu, if there is one.If called with a non-nil argument, this function first updates all thenodes in the buffer before updating the menus."  (interactive "P")  (let ((case-fold-search t)        master-menu-p)    (save-excursion      (push-mark (point-max) t)      (goto-char (point-min))      (message "Checking for a master menu in %s ... "(buffer-name))      (save-excursion        (if (search-forward texinfo-master-menu-header nil t)            (progn              ;; Check if @detailmenu kludge is used;              ;; if so, leave point before @detailmenu.              (search-backward "\n@detailmenu" 			       (save-excursion (forward-line -3) (point))			       t)	      ;; Remove detailed master menu listing              (setq master-menu-p t)              (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-p          (progn            (message "Updating all nodes in %s ... " (buffer-name))            (sleep-for 2)	    (texinfo-update-node (point-min) (point-max))))            (message "Updating all menus in %s ... " (buffer-name))              (sleep-for 2)      (texinfo-make-menu (point-max) (point-min))            (if master-menu-p          (progn            (message "Updating the master menu in %s... " (buffer-name))            (sleep-for 2)            (texinfo-master-menu nil))))        (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 beginningof the node if one is found; else do not move point."  (let ((case-fold-search t))    (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 beginningof the node if one is found; else do not move point."  (let ((case-fold-search t))    (cond     ((or (string-equal "top" level) (string-equal "chapter" level))      (if (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" region-end t)          (progn (beginning-of-line) t)))     (t      (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))))           region-end t)          (progn (beginning-of-line) t))))));;; 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 isan element of the list.  If the description does not exist, theelement consists only of the node name."  (goto-char beginning)  (let (new-menu-list)    (while (texinfo-menu-locate-entry-p level end)