Function: texinfo-master-menu

texinfo-master-menu is an autoloaded, interactive and byte-compiled function defined in texnfo-upd.el.gz.

Signature

(texinfo-master-menu UPDATE-ALL-NODES-MENUS-P)

Documentation

Make a master menu for a whole Texinfo file.

Remove pre-existing master menu, if there is one.

This function supports only single-file manuals. For multi-file manuals, use texinfo-multiple-files-update.

This function creates or updates the @detailmenu section of a master menu that follows the Top node. It replaces any existing detailed menu that follows the top node. The detailed menu includes every entry from all the other menus. By default, the existing menus, including the menu in the Top node, are not updated according to the buffer contents, so all the menus should be updated first using texinfo-make-menu or texinfo-all-menus-update, which see. Alternatively, invoke this function with a prefix argument, see below.

Non-nil, non-numeric argument (C-u (universal-argument) prefix, if interactive) means first update all existing menus in the buffer (incorporating descriptions from pre-existing menus) before it constructs the master menu. If the argument is numeric (e.g., "\\[universal-argument] 2"), update all existing nodes as well, by calling texinfo-update-node on the entire file. Warning: do NOT invoke with a numeric argument if your Texinfo file uses @node lines without the Next, Previous, Up pointers, as the result could be an invalid Texinfo file!

The function removes and recreates the detailed part of an already existing master menu. This action assumes that the pre-existing master menu uses the standard texinfo-master-menu-header for the detailed menu.

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.

Indents the first line of descriptions, and leaves trailing whitespace in a menu that lacks descriptions, so descriptions will format well. In general, a menu should contain descriptions, because node names and section titles are often too short to explain a node well.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/texnfo-upd.el.gz
;;; Making the master menu

;;;###autoload
(defun texinfo-master-menu (update-all-nodes-menus-p)
  "Make a master menu for a whole Texinfo file.
Remove pre-existing master menu, if there is one.

This function supports only single-file manuals.  For multi-file
manuals, use `texinfo-multiple-files-update'.

This function creates or updates the @detailmenu section of a
master menu that follows the Top node.  It replaces any existing
detailed menu that follows the top node.  The detailed menu
includes every entry from all the other menus.  By default, the
existing menus, including the menu in the Top node, are not
updated according to the buffer contents, so all the menus should
be updated first using `texinfo-make-menu' or
`texinfo-all-menus-update', which see.  Alternatively, invoke
this function with a prefix argument, see below.

Non-nil, non-numeric argument (\\[universal-argument] prefix, if interactive) means
first update all existing menus in the buffer (incorporating
descriptions from pre-existing menus) before it constructs the
master menu.  If the argument is numeric (e.g., \"\\[universal-argument] 2\"),
update all existing nodes as well, by calling
`texinfo-update-node' on the entire file.  Warning: do NOT
invoke with a numeric argument if your Texinfo file uses @node
lines without the `Next', `Previous', `Up' pointers, as the
result could be an invalid Texinfo file!

The function removes and recreates the detailed part of an already
existing master menu.  This action assumes that the pre-existing
master menu uses the standard `texinfo-master-menu-header' for the
detailed menu.

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.

Indents the first line of descriptions, and leaves trailing whitespace
in a menu that lacks descriptions, so descriptions will format well.
In general, a menu should contain descriptions, because node names and
section titles are often too short to explain a node well."

  (interactive "P")
  (let ((case-fold-search t))
    (widen)
    (goto-char (point-min))

    ;; Move point to location after `top'.
    (if (not (re-search-forward "^@node [ \t]*top[ \t]*\\(,\\|$\\)" nil t))
	(error "This buffer needs a Top node"))

    (let ((first-chapter
	   (save-excursion
	     (or (re-search-forward "^@node" nil t)
		 (error "Too few nodes for a master menu"))
	     (point))))
      (if (search-forward texinfo-master-menu-header first-chapter t)
	  (progn
	    ;; Check if @detailmenu kludge is used;
	    ;; if so, leave point before @detailmenu.
	    (search-backward "\n@detailmenu" (line-beginning-position -2) t)
	    ;; Remove detailed master menu listing
	    (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
	  (when (numberp update-all-nodes-menus-p)
	    (message
	     "Making a master menu in %s ...first updating all nodes... "
	     (buffer-name))
	    (texinfo-update-node (point-min) (point-max)))
	  (message "Updating all menus in %s ... " (buffer-name))
	  (texinfo-make-menu (point-min) (point-max))))

    (message "Now making the master menu in %s... " (buffer-name))
    (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))

      (if (search-forward texinfo-master-menu-header nil t)
	  (progn
	    (goto-char (match-beginning 0))
	    ;; Check if @detailmenu kludge is used;
	    ;; if so, leave point before @detailmenu.
	    (search-backward "\n@detailmenu" (line-beginning-position -2) t)
	    (insert "\n")
	    (delete-blank-lines)
	    (goto-char (point-min))))

      (re-search-forward "^@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.")))