Function: texinfo-multi-file-update

texinfo-multi-file-update is a byte-compiled function defined in texnfo-upd.el.gz.

Signature

(texinfo-multi-file-update FILES &optional UPDATE-EVERYTHING)

Documentation

Update first node pointers in each file in FILES.

Return a list of the node names.

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.

However, when an included file does not have any node lines in it, this command does not try to create a menu entry for it. Consequently, you can include any file, such as a version or an update file without node lines, not just files that are chapters.

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/texnfo-upd.el.gz
(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.

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.

However, when an included file does not have any node lines in
it, this command does not try to create a menu entry for it.
Consequently, you can include any file, such as a version or an
update file without node lines, not just files that are
chapters."

;; The menu-list has the form:
;;
;;     ((\"node-name1\" . \"title1\")
;;      (\"node-name2\" . \"title2\") ... )
;;
;; However, there does not need to be a title field and this function
;; does not fill it; however a comment tells you how to do so.
;; You would use the title field if you wanted to insert titles in the
;; description slot of a menu as a description.

  (let ((case-fold-search t)
	menu-list next-node-name previous-node-name files-with-node-lines)

    ;; Create a new list of included files that only have node lines
    (while files
      (set-buffer (find-file-noselect (car files)))
      (widen)
      (goto-char (point-min))
      (when (re-search-forward "^@node" nil t)
        (setq files-with-node-lines (cons (car files) files-with-node-lines)))
      (setq files (cdr files)))
    (setq files-with-node-lines (nreverse files-with-node-lines))

    ;; Find the name of the first node in a subsequent file
    ;; and copy it into the variable  next-node-name
    (set-buffer (find-file-noselect (car (cdr files-with-node-lines))))
    (widen)
    (goto-char (point-min))
    ;; The following search _must_ succeed, since we verified above
    ;; that this file does have a @node line.
    (re-search-forward "^@node" nil t)
    (beginning-of-line)
    (texinfo-check-for-node-name)
    (setq next-node-name (texinfo-copy-node-name))
    (push (cons next-node-name (prog1 "" (forward-line 1)))
	  ;; Use following to insert section titles automatically.
	  ;; (texinfo-copy-next-section-title)
	  menu-list)

    ;; Go to outer file
    ;; `pop' is analogous to (prog1 (car PLACE) (setf PLACE (cdr PLACE)))
    (set-buffer (find-file-noselect (pop files-with-node-lines)))
    (goto-char (point-min))
    (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
	(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")

    (while files-with-node-lines

      (if (not (cdr files-with-node-lines))
	  ;; No next file
	  (setq next-node-name "")
	;; Else,
	;; find the name of the first node in the next file.
	(set-buffer (find-file-noselect (car (cdr files-with-node-lines))))
	(widen)
	(goto-char (point-min))
	;; The following search _must_ succeed, since we verified
	;; above that files in files-with-node-lines do have a @node
	;; line.
	(re-search-forward "^@node" nil t)
	(beginning-of-line)
	(texinfo-check-for-node-name)
	(setq next-node-name (texinfo-copy-node-name))
	(push (cons next-node-name (prog1 "" (forward-line 1)))
	      ;; Use following to insert section titles automatically.
	      ;; (texinfo-copy-next-section-title)
	      menu-list))

      ;; Go to node to be updated.
      (set-buffer (find-file-noselect (car files-with-node-lines)))
      (goto-char (point-min))
      (beginning-of-line)

      ;; Update other menus and nodes if requested.
      (if update-everything (texinfo-all-menus-update t))

      (beginning-of-line)
      (texinfo-delete-existing-pointers)
      (end-of-line)
      (insert ", " next-node-name ", " previous-node-name ", Top")

      (beginning-of-line)
      (setq previous-node-name (texinfo-copy-node-name))

      (setq files-with-node-lines (cdr files-with-node-lines)))
    (nreverse menu-list)))