;;; Commentary:
-;; Known bug: update commands fail to ignore @ignore.
+;; Known bug: update commands fail to ignore @ignore, and fail to DTRT
+;; with the @if... directives (so expect trouble when the manual uses
+;; different @node lines or @menu items in @iftex and in @ifnottex).
;; Summary: how to use the updating commands
;; With a prefix argument, the `texinfo-update-node' and
;; `texinfo-make-menu' functions do their jobs in the region.
;;
+;; Important note: We do NOT recommend use of these commands to update
+;; the `Next', `Previous' and `Up' pointers on @node lines. Most
+;; manuals, including those whose Texinfo files adhere to the strucure
+;; described below, don't need these pointers, because makeinfo will
+;; generate them automatically (see the node "makeinfo Pointer
+;; Creation" in the Texinfo manual). By contrast, due to known bugs
+;; described above, texinfo-update-node etc. could produce incorrect
+;; pointers, and thus make a perfectly valid Texinfo file into an
+;; invalid one. You _have_ been warned!
+;;
;; In brief, the functions for creating or updating nodes and menus, are:
;;
;; texinfo-update-node (&optional beginning end)
;; It does not matter whether the `@node' line has pre-existing
;; `Next', `Previous', or `Up' pointers in it. They are removed.
+;; Warning: Since the pre-existing pointers are replaced with the ones
+;; computed by `texinfo-update-node', and since this function has
+;; known bugs with the more advanced Texinfo features (see above), it
+;; could produce an invalid Texinfo file. You are well advised not to
+;; use this function, except if you know what you are doing and
+;; exercise extreme caution. Keep in mind that most manuals do not
+;; need the `Next', `Previous', and `Up' pointers to be present on the
+;; @node lines; makeinfo will automatically generate them when it
+;; produces the Info or HTML versions of the manual.
+
;; The `texinfo-every-node-update' function runs `texinfo-update-node'
;; on the whole buffer.
;; 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.)
+;; after the top node. (The file must have a top node.) This
+;; function works only on Texinfo files all of whose @node lines are
+;; present in a single file; use `texinfo-multiple-files-update' for
+;; multi-file manuals. 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.
;; 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.
+;; titles, you will usually want to manually edit node names so inserted.
\f
;;; Code:
"Update every regular menu in a Texinfo file.
Update pre-existing master menu, if there is one.
+Only single-file manuals are supported by this function. For
+multi-file manuals, use `texinfo-multiple-files-update'.
+
If called with a non-nil argument, this function first updates all the
-nodes in the buffer before updating the menus.
+nodes in the buffer before updating the menus. Do NOT invoke this
+command with an argument if your Texinfo file uses @node lines without
+the `Next', `Previous', and `Up' pointers!
Indents the first line of descriptions, and leaves trailing whitespace
in a menu that lacks descriptions, so descriptions will format well.
(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.
+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'.
+
+Non-nil, non-numeric argument (C-u 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., \"C-u 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!
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-existing master menu using the
standard `texinfo-master-menu-header'.
(if update-all-nodes-menus-p
(progn
- (message "Making a master menu in %s ...first updating all nodes... "
- (buffer-name))
- (texinfo-update-node (point-min) (point-max))
-
+ (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))))
"Without any prefix argument, update the node in which point is located.
Interactively, a prefix argument means to operate on the region.
+Warning: do NOT use this function if your Texinfo file uses @node
+lines without the `Next', `Previous', `Up' pointers, because the
+result could be an invalid Texinfo file due to known deficiencies
+in this command: it does not support @ignore and @if* directives.
+
The functions for creating or updating nodes and menus, and their
keybindings, are:
(message "Done...nodes updated in region. You may save the buffer."))))))
(defun texinfo-every-node-update ()
- "Update every node in a Texinfo file."
+ "Update every node in a Texinfo file.
+
+Warning: do NOT use this function if your Texinfo file uses @node
+lines without the `Next', `Previous', `Up' pointers, because the
+result could be an invalid Texinfo file due to known deficiencies
+in this command: it does not support @ignore and @if* directives."
(interactive)
(save-excursion
(texinfo-update-node (point-min) (point-max))
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. Also, update the `Top' level node
-pointers of OUTER-FILE.
+pointers of OUTER-FILE. Do NOT invoke this command with a numeric prefix
+arg, if your files use @node lines without the `Next', `Previous', `Up'
+pointers, because this could produce invalid Texinfo files due to known
+deficiencies in `texinfo-update-node': it does not support the @ignore
+and @if... directives.
Notes:
projects / emacs.git / commitdiff