upstream

10 files changed, 109 insertions, 49 deletions

diff --git a/lisp/textmodes/artist.el b/lisp/textmodes/artist.el
index 0efabc2135a..2e90a4bf241 100644
--- a/lisp/textmodes/artist.el
+++ b/lisp/textmodes/artist.el
@@ -3960,11 +3960,11 @@ The 2-point shape SHAPE is drawn from X1, Y1 to X2, Y2."
 ;; Implementation note: This really should honor the interval-fn entry
 ;; in the master table, `artist-mt', which would mean leaving a timer
 ;; that calls `draw-fn' every now and then. That timer would then have
-;; to be cancelled and reinstalled whenever the user moves the cursor.
+;; to be canceled and reinstalled whenever the user moves the cursor.
 ;; This could be done, but what if the user suddenly switches to another
 ;; drawing mode, or even kills the buffer! In the mouse case, it is much
 ;; simpler: when at the end of `artist-mouse-draw-continously', the
-;; user has released the button, so the timer will always be cancelled
+;; user has released the button, so the timer will always be canceled
 ;; at that point.
 (defun artist-key-draw-continously (x y)
   "Draw current continuous shape at X,Y."
@@ -4455,7 +4455,7 @@ If N is negative, move backward."
   "Set current fill character to be C."
   (interactive "cType fill char (type RET to turn off): ")
   (cond ((eq c ?\r) (setq artist-fill-char-set nil)
-		    (message "Fill cancelled"))
+		    (message "Fill canceled"))
 	(t	    (setq artist-fill-char-set t)
 		    (setq artist-fill-char c)
 		    (message "Fill set to \"%c\"" c))))
@@ -5589,7 +5589,7 @@ The event, EV, is the mouse event."
 ;;         of drawing mode.
 ;;
 ;;         You should provide these functions. You might think that
-;;         only you is using your type of mode, so noone will be able
+;;         only you is using your type of mode, so no one will be able
 ;;         to switch to another operation of the same type of mode,
 ;;         but someone else might base a new drawing mode upon your
 ;;         work.
diff --git a/lisp/textmodes/fill.el b/lisp/textmodes/fill.el
index b8614b16f82..610b0c71357 100644
--- a/lisp/textmodes/fill.el
+++ b/lisp/textmodes/fill.el
@@ -82,7 +82,7 @@ reinserts the fill prefix in each resulting line."
       (setq fill-prefix nil)))
   (if fill-prefix
       (message "fill-prefix: \"%s\"" fill-prefix)
-    (message "fill-prefix cancelled")))
+    (message "fill-prefix canceled")))
 
 (defcustom adaptive-fill-mode t
   "Non-nil means determine a paragraph's fill prefix from its text."
@@ -383,7 +383,7 @@ and `fill-nobreak-invisible'."
   "Char-table of characters that don't use space between words.")
 
 (progn
-  ;; Register `kinsoku' for scripts HAN, KANA, BOPOMPFO, and CJK-MISS.
+  ;; Register `kinsoku' for scripts HAN, KANA, BOPOMOFO, and CJK-MISC.
   ;; Also tell that they don't use space between words.
   (map-char-table
    #'(lambda (key val)
diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el
index d0967d63740..ba7b84fe1dd 100644
--- a/lisp/textmodes/ispell.el
+++ b/lisp/textmodes/ispell.el
@@ -2499,7 +2499,7 @@ scrolling the current window.  Leave the new window selected."
       ;; hidden by new window, scroll it to just below new win
       ;; otherwise set top line of other win so it doesn't scroll.
       (if (< oldot top) (setq top oldot))
-      ;; if frame is unsplitable, temporarily disable that...
+      ;; if frame is unsplittable, temporarily disable that...
       (if (cdr (assq 'unsplittable (frame-parameters (selected-frame))))
 	  (let ((frame (selected-frame)))
 	    (modify-frame-parameters frame '((unsplittable . nil)))
@@ -3979,7 +3979,7 @@ Both should not be used to define a buffer-local dictionary."
 ; LocalWords:  AMStex hspace includeonly nocite epsfig displaymath eqnarray reg
 ; LocalWords:  minipage modeline pers dict unhighlight buf grep sync prev inc
 ; LocalWords:  fn oldot NB AIX msg init read's bufs pt cmd Quinlan eg
-; LocalWords:  uuencoded unidiff sc nn VM SGML eval IspellPersDict unsplitable
+; LocalWords:  uuencoded unidiff sc nn VM SGML eval IspellPersDict
 ; LocalWords:  lns XEmacs HTML casechars Multibyte
 
 ;;; ispell.el ends here
diff --git a/lisp/textmodes/picture.el b/lisp/textmodes/picture.el
index 678d48758da..3356ce195f2 100644
--- a/lisp/textmodes/picture.el
+++ b/lisp/textmodes/picture.el
@@ -742,7 +742,7 @@ by supplying an argument.
 Entry to this mode calls the value of `picture-mode-hook' if non-nil.
 
 Note that Picture mode commands will work outside of Picture mode, but
-they are not defaultly assigned to keys."
+they are not by default assigned to keys."
   (interactive)
   (if (eq major-mode 'picture-mode)
       (error "You are already editing a picture")
diff --git a/lisp/textmodes/reftex-dcr.el b/lisp/textmodes/reftex-dcr.el
index ff6ffffc382..2aecc34e2b0 100644
--- a/lisp/textmodes/reftex-dcr.el
+++ b/lisp/textmodes/reftex-dcr.el
@@ -212,7 +212,7 @@ to the functions `reftex-view-cr-cite' and `reftex-view-cr-ref'."
       (add-hook 'pre-command-hook 'reftex-highlight-shall-die)
 
       (when (eq how 'tmp-window)
-        ;; Resize window and arrange restauration
+        ;; Resize window and arrange restoration
         (shrink-window (1- (- (window-height) 9)))
         (recenter '(4))
         (add-hook 'pre-command-hook 'reftex-restore-window-conf))
diff --git a/lisp/textmodes/remember.el b/lisp/textmodes/remember.el
index 07a4fae9c30..c184a90dfc2 100644
--- a/lisp/textmodes/remember.el
+++ b/lisp/textmodes/remember.el
@@ -474,7 +474,7 @@ If this is nil, then `diary-file' will be used instead."
           (replace-match
            (let ((style (if (boundp 'calendar-date-style)
                             calendar-date-style
-                          ;; Don't complain about obsoleteness.
+                          ;; Don't complain about obsolescence.
                           (if (with-no-warnings european-calendar-style)
                               'european
                             'american))))
diff --git a/lisp/textmodes/rst.el b/lisp/textmodes/rst.el
index 64dffe78d50..f2dba1575c2 100644
--- a/lisp/textmodes/rst.el
+++ b/lisp/textmodes/rst.el
@@ -243,7 +243,7 @@
     (define-key map [(control ?=)] 'rst-adjust) ;; (Does not work on the Mac OSX.)
     ;; Display the hierarchy of decorations implied by the current document contents.
     (define-key map [(control c) (control h)] 'rst-display-decorations-hierarchy)
-    ;; Homogeneize the decorations in the document.
+    ;; Homogenize the decorations in the document.
     (define-key map [(control c) (control s)] 'rst-straighten-decorations)
 ;;    (define-key map [(control c) (control s)] 'rst-straighten-deco-spacing)
 
diff --git a/lisp/textmodes/table.el b/lisp/textmodes/table.el
index 65f6d98ef79..6f9e592d8ed 100644
--- a/lisp/textmodes/table.el
+++ b/lisp/textmodes/table.el
@@ -345,7 +345,7 @@
 ;; Above code is well known ~/.emacs idiom for customizing a mode
 ;; specific keymap however it does not work for this package.  This is
 ;; because there is no table mode in effect.  This package does not
-;; use a local map therefor you must modify `table-cell-map'
+;; use a local map therefore you must modify `table-cell-map'
 ;; explicitly.  The correct way of achieving above task is:
 ;;
 ;;   (add-hook 'table-cell-map-hook
@@ -2155,7 +2155,7 @@ specified."
 (defun table-shorten-cell (n)
   "Shorten the current cell by N lines by shrinking the cell vertically.
 Shortening is done by removing blank lines from the bottom of the cell
-and possibly from the top of the cell as well.  Therefor, the cell
+and possibly from the top of the cell as well.  Therefore, the cell
 must have some bottom/top blank lines to be shorten effectively.  This
 is applicable to all the cells aligned horizontally with the current
 one because they are also shortened in order to keep the rectangular
@@ -4293,7 +4293,7 @@ cache buffer into the designated cell in the table buffer."
     (car (table--get-coordinate (cdr (table--horizontal-cell-list nil t))))
     (1+ (cdr (table--get-coordinate (cdr (table--vertical-cell-list nil t))))))))
 
-(defun table-call-interactively (function &optional recoard-flag keys)
+(defun table-call-interactively (function &optional record-flag keys)
   "Call FUNCTION, or a table version of it if applicable.
 See `call-interactively' for full description of the arguments."
   (let ((table-func (intern-soft (format "*table--cell-%s" function))))
@@ -4301,7 +4301,7 @@ See `call-interactively' for full description of the arguments."
      (if (and table-func
 	      (table--point-in-cell-p))
 	 table-func
-       function) recoard-flag keys)))
+       function) record-flag keys)))
 
 (defun table-funcall (function &rest arguments)
   "Call FUNCTION, or a table version of it if applicable.
diff --git a/lisp/textmodes/texinfmt.el b/lisp/textmodes/texinfmt.el
index a337d6f9f40..b186b02851d 100644
--- a/lisp/textmodes/texinfmt.el
+++ b/lisp/textmodes/texinfmt.el
@@ -2088,11 +2088,11 @@ This command is executed when texinfmt sees @item inside @multitable."
         (table-entry-height 0)
         ;; unformatted row looks like:  A1  @tab  A2  @tab  A3
         ;; extract-row command deletes the source line in the table.
-        (unformated-row (texinfo-multitable-extract-row)))
+        (unformatted-row (texinfo-multitable-extract-row)))
     ;; Use a temporary buffer
     (set-buffer (get-buffer-create texinfo-multitable-buffer-name))
     (delete-region (point-min) (point-max))
-    (insert unformated-row)
+    (insert unformatted-row)
     (goto-char (point-min))
 ;; 1. Check for correct number of @tab in line.
     (let ((tab-number 1))               ; one @tab between two columns
diff --git a/lisp/textmodes/texnfo-upd.el b/lisp/textmodes/texnfo-upd.el
index 047bba72ccd..69d68a76d4b 100644
--- a/lisp/textmodes/texnfo-upd.el
+++ b/lisp/textmodes/texnfo-upd.el
@@ -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 menus are
+;; present in a single file; use `texinfo-multiple-files-update' for
+;; multi-file manuals.  The function constructs a master menu that
+;; includes every entry from every other menu.  Use this command to
+;; create or update the @detailmenu menu after you've created or
+;; updated all the menus in the file, including the menu in the Top
+;; node, using the `texinfo-make-menu' or the `texinfo-all-menus-update'
+;; command.
 
 ;; 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,20 +873,35 @@ 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.
-
-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'.
+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 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!
+
+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:
@@ -909,10 +954,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))))
 
@@ -978,7 +1024,7 @@ However, there does not need to be a title field."
   (let ((first-chapter
 	 (save-excursion (re-search-forward "^@node\\|^@include") (point))))
     (unless (re-search-forward "^@menu" first-chapter t)
-      (error "Buffer lacks ordinary `Top' menu in which to insert master")))
+      (error "Buffer lacks a menu in its first node; create it, then run me again")))
   (beginning-of-line)
   (delete-region      ; buffer must have ordinary top menu
    (point)
@@ -1119,7 +1165,7 @@ error if the node is not the top node and a section is not found."
 	 "texinfo-specific-section-type: Chapter or section not found"))))))
 
 (defun texinfo-hierarchic-level ()
-  "Return the general hierarchal level of the next node in a texinfo file.
+  "Return the general hierarchical level of the next node in a texinfo file.
 Thus, a subheading or appendixsubsec is of type subsection."
   (let ((case-fold-search t))
     (cadr (assoc
@@ -1207,6 +1253,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 +1297,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 +1990,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: