procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix documentation and one misfeature of Texinfo mode update commands.

Browse source 
lisp/textmodes/texnfo-upd.el: Update commentary.  Add a warning not
 to use texinfo-update-node and commands that call it if the
 Texinfo file uses @node lines without next/prev/up pointers.
 (texinfo-all-menus-update, texinfo-master-menu)
 (texinfo-update-node, texinfo-every-node-update)
 (texinfo-multiple-files-update): Doc fix.  Warn against updating
 all the @node lines.
 (texinfo-master-menu): Only call texinfo-update-node if the prefix
 argument is numeric.  See also this thread:
 http://lists.gnu.org/archive/html/emacs-devel/2011-12/msg00156.html.

Fixes: debbugs:2975
This commit is contained in:
Eli Zaretskii 2011-12-10 12:49:33 +02:00
parent cd0314dd85
commit e5d84bfe06
2 changed files with 87 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
lisp/ChangeLog
View file

@ -1,3 +1,16 @@
2011-12-10 Eli Zaretskii <eliz@gnu.org>
* textmodes/texnfo-upd.el: Update commentary. Add a warning not
to use texinfo-update-node and commands that call it if the
Texinfo file uses @node lines without next/prev/up pointers.
(texinfo-all-menus-update, texinfo-master-menu)
(texinfo-update-node, texinfo-every-node-update)
(texinfo-multiple-files-update): Doc fix. Warn against updating
all the @node lines.
(texinfo-master-menu): Only call texinfo-update-node if the prefix
argument is numeric. (Bug#2975) See also this thread:
http://lists.gnu.org/archive/html/emacs-devel/2011-12/msg00156.html.
2011-12-09 Manuel Gómez <mgrojo@gmail.com> (tiny change)
* speedbar.el (speedbar-supported-extension-expressions):

95
lisp/textmodes/texnfo-upd.el
View file

@ -23,7 +23,9 @@
;;; 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
@ -37,6 +39,16 @@
;; 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)
@ -89,6 +101,16 @@
;; 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.
@ -119,12 +141,15 @@
;; 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.
@ -142,7 +167,7 @@
;; 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.
;;; Code:
@ -330,8 +355,13 @@ at the level specified by LEVEL. Point is left at the end of menu."
"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.
@ -843,17 +873,25 @@ second and subsequent lines of a multi-line description."
(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'.
@ -909,10 +947,11 @@ section titles are often too short to explain a node well."
(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))))
@ -1207,6 +1246,11 @@ end of that region; it limits the search."
"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:
@ -1246,7 +1290,12 @@ which menu descriptions are indented. Its default value is 32."
(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))
@ -1934,7 +1983,11 @@ 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. 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: