upstream i think

6 files changed, 200 insertions, 123 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 293f253c545..37de62be976 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,26 @@
+2011-11-26  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Truncation):
+        * text.texi (Special Properties): Describe what a stretch-glyph is
+        instead of using that term without explanation.  Make the
+        cross-references more accurate.
+
+        * display.texi (Usual Display): Update the description,
+        cross-references, and indexing related to display of control
+        characters and raw bytes.
+
+2011-11-25  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Splitting Windows): Fix description of
+        window-combination-limit.  Suggested by Eli Zaretskii.
+
+2011-11-23  Chong Yidong  <cyd@gnu.org>
+
+        * windows.texi (Window Sizes): Move window-top-line,
+        window-left-column, and window-*-pixel-edges to Coordinates and
+        Windows node.
+        (Coordinates and Windows): Restore window-edges doc.
+
 2011-11-21  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Windows and Frames, Splitting Windows): Fix
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9849420b1f5..a9921d7443d 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -193,10 +193,12 @@ a window, that forces truncation.
 @defvar wrap-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
 ``prefix'' that is prepended to every continuation line at
-display-time.  (If lines are truncated, the wrap-prefix is never
-used.)  It may be a string, an image, or a stretch-glyph; the value is
-interpreted in the same way as a @code{display} text property.
-@xref{Display Property}.
+display time.  (If lines are truncated, the wrap-prefix is never
+used.)  It may be a string or an image (@pxref{Other Display Specs}),
+or a stretch of whitespace such as specified by the @code{:width} or
+@code{:align-to} display properties (@pxref{Specified Space}).  The
+value is interpreted in the same way as a @code{display} text
+property.  @xref{Display Property}.
 
 A wrap-prefix may also be specified for regions of text, using the
 @code{wrap-prefix} text or overlay property.  This takes precedence
@@ -206,9 +208,11 @@ over the @code{wrap-prefix} variable.  @xref{Special Properties}.
 @defvar line-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
 ``prefix'' that is prepended to every non-continuation line at
-display-time.  It may be a string, an image, or a stretch-glyph; the
-value is interpreted in the same way as a @code{display} text
-property.  @xref{Display Property}.
+display time.  It may be a string or an image (@pxref{Other Display
+Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).  The value is interpreted in the same way as a @code{display}
+text property.  @xref{Display Property}.
 
 A line-prefix may also be specified for regions of text using the
 @code{line-prefix} text or overlay property.  This takes precedence
@@ -5638,39 +5642,45 @@ code.  You can override these conventions by setting up a display table
 @itemize @bullet
 @item
 Character codes 32 through 126 map to glyph codes 32 through 126.
-Normally this means they display as themselves.
+Normally this means they display as themselves, but a display table
+can change that.
 
 @item
 Character code 9 is a horizontal tab.  It displays as whitespace
 up to a position determined by @code{tab-width}.
 
 @item
-Character code 10 is a newline.
+Character code 10 is a newline.  It is normally invisible on display,
+and has the effect of ending the preceding line and starting a new
+line.
 
 @item
-All other codes in the range 0 through 31, and code 127, display in one
-of two ways according to the value of @code{ctl-arrow}.  If it is
-non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @acronym{ASCII} code for @samp{^}.  (A display table can
-specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
-just like the codes in the range 128 to 255.
-
-On MS-DOS terminals, Emacs arranges by default for the character code
-127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon.  This glyph is used to display non-@acronym{ASCII} characters
-that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
-emacs, The GNU Emacs Manual}.
-
+All other codes in the range 0 through 31 display in one of two ways
+according to the value of @code{ctl-arrow}.  If it is non-@code{nil},
+these codes map to sequences of two glyphs, where the first glyph is
+the @acronym{ASCII} code for @samp{^}.  (A display table can specify a
+glyph to use instead of @samp{^}.)  Otherwise, these codes map just
+like the raw bytes in the range 128 to 255 (described below).
+
+@cindex octal escapes
 @item
-Character codes 128 through 255 map to sequences of four glyphs, where
-the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
-digit characters representing the character code in octal.  (A display
-table can specify a glyph to use instead of @samp{\}.)
+Raw bytes (@pxref{Text Representations}) with codes 128 through 255,
+and the @acronym{ASCII} control character with code 127, display as
+sequences of four glyphs, where the first glyph is the @acronym{ASCII}
+code for @samp{\}, and the others are digit characters representing
+the character code in octal.  (A display table can specify a glyph to
+use instead of @samp{\}.)  This is known as the @dfn{octal escape}
+display.
 
 @item
-Multibyte character codes above 256 are displayed as themselves, or as
-a question mark or a hex code or an empty box if the terminal cannot
-display that character.
+Non-@acronym{ASCII} character codes above 127 are displayed as
+themselves, if the terminal and the available fonts support them.
+Characters that are not supported by the terminal, or (on window
+systems) have no fonts available for them, are displayed as a question
+mark or a hex code or an empty box.  @xref{Glyphless Chars}, for how
+to control display of the characters not supported by the terminal or
+fonts.  Display tables can change how a character is displayed, even
+if it is supported.
 @end itemize
 
   The usual display conventions apply even when there is a display
@@ -5695,7 +5705,8 @@ mode line using the new values, call the function
 This buffer-local variable controls how control characters are
 displayed.  If it is non-@code{nil}, they are displayed as a caret
 followed by the character: @samp{^A}.  If it is @code{nil}, they are
-displayed as a backslash followed by three octal digits: @samp{\001}.
+displayed as octal escapes: a backslash followed by three octal
+digits, as in @samp{\001}.
 @end defopt
 
 @defopt tab-width
diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile
index 5c0a6d0f5ea..e0d77ee0541 100644
--- a/doc/lispref/spellfile
+++ b/doc/lispref/spellfile
@@ -253,7 +253,6 @@ deletable
 deletion'
 delq
 depiction
-descendents
 deselecting
 destructive'
 destructively'
@@ -299,7 +298,6 @@ excess'
 exec
 exitcode
 expression'
-extendible
 extra'
 fails'
 fascist
@@ -660,7 +658,7 @@ the'
 tildes
 time's
 to'
-towars
+towards
 transportable
 txt
 types'
@@ -674,7 +672,6 @@ undefine
 undefines
 underfull
 undo's
-undodata
 unevaluated'
 unexec
 unexpand
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 3a081dddc61..fc12939bec5 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3191,10 +3191,12 @@ controls the total height of the display line ending in that newline.
 
 @item wrap-prefix
 If text has a @code{wrap-prefix} property, the prefix it defines will
-be added at display-time to the beginning of every continuation line
+be added at display time to the beginning of every continuation line
 due to text wrapping (so if lines are truncated, the wrap-prefix is
-never used).  It may be a string, an image, or a stretch-glyph such as
-used by the @code{display} text-property.  @xref{Display Property}.
+never used).  It may be a string or an image (@pxref{Other Display
+Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).
 
 A wrap-prefix may also be specified for an entire buffer using the
 @code{wrap-prefix} buffer-local variable (however, a
@@ -3203,9 +3205,11 @@ the @code{wrap-prefix} variable).  @xref{Truncation}.
 
 @item line-prefix
 If text has a @code{line-prefix} property, the prefix it defines will
-be added at display-time to the beginning of every non-continuation
-line.  It may be a string, an image, or a stretch-glyph such as used
-by the @code{display} text-property.  @xref{Display Property}.
+be added at display time to the beginning of every non-continuation
+line.  It may be a string or an image (@pxref{Other Display
+Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).
 
 A line-prefix may also be specified for an entire buffer using the
 @code{line-prefix} buffer-local variable (however, a
@@ -3762,7 +3766,7 @@ Additionally, if two fields are separated by another field with the
 special value @code{boundary}, then any point within this special
 field is also considered to be ``on the boundary.''
 
-Commands like @kbd{C-a} with no argumemt, that normally move backward
+Commands like @kbd{C-a} with no argument, that normally move backward
 to a specific kind of location and stay there once there, probably
 should specify @code{nil} for @var{escape-from-edge}.  Other motion
 commands that check fields should probably pass @code{t}.
@@ -4322,5 +4326,3 @@ If you do want modification hooks to be run in a particular piece of
 code that is itself run from a modification hook, then rebind locally
 @code{inhibit-modification-hooks} to @code{nil}.
 @end defvar
-
-
diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt
index 53a9f58cd01..6eb11a92f47 100644
--- a/doc/lispref/two-volume-cross-refs.txt
+++ b/doc/lispref/two-volume-cross-refs.txt
@@ -34,7 +34,7 @@ where each volume starts with a higher page number since I find it
 harder to go to the right place in the volume.)
 
 References to the same volume are just the page number; references to
-the other volume are a volumne number (in Roman numerals) preceding
+the other volume are a volume number (in Roman numerals) preceding
 the page number.
 
 For example, in Volume I:
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bb1b0524689..437b6db8d58 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -376,7 +376,7 @@ Bars}).  At the top of the window is an optional header line
 line (@pxref{Mode Line Format}).
 
   Emacs provides several functions for finding the height and width of
-a window.  Except where noted, these heights and widths are reported
+a window.  Except where noted, Emacs reports window heights and widths
 as integer numbers of lines and columns respectively.  On a graphical
 display, each ``line'' and ``column'' actually corresponds to the
 height and width of a ``default'' character specified by the frame's
@@ -439,26 +439,6 @@ that of the root window on that frame.  If @var{window} is omitted or
 @code{nil}, it defaults to the selected window.
 @end defun
 
-@cindex window position
-  The following functions can be used to determine the position of a
-window relative to the window area of its frame:
-
-@defun window-top-line &optional window
-This function returns the distance, in lines, between the top of
-@var{window} and the top of the frame's window area.  For instance,
-the return value is 0 if there is no window above @var{window}.  If
-@var{window} is omitted or @code{nil}, it defaults to the selected
-window.
-@end defun
-
-@defun window-left-column &optional window
-This function returns the distance, in columns, between the left edge
-of @var{window} and the left edge of the frame's window area.  For
-instance, the return value is 0 if there is no window to the left of
-@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
-@end defun
-
 @cindex window body height
 @cindex body height of a window
 @cindex window body width
@@ -535,45 +515,12 @@ can be resized in the desired direction.  To determine that, use the
 function @code{window-resizable}.  @xref{Resizing Windows}.
 @end defun
 
-  The following functions can be used to find a window's size and
-position in pixels.  Though mostly useful on graphical displays, they
-can also be called on text-only terminals, where the screen area of
-each text character is taken to be ``one pixel''.
-
-@defun window-pixel-edges &optional window
-This function return a list of pixel coordinates for the edges of
-@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
-
-The return value has the form @code{(@var{left} @var{top} @var{right}
-@var{bottom})}.  The list elements are, respectively, the X coordinate
-of the left window edge, the Y coordinate of the top edge, one more
-than the X coordinate of the right edge, and one more than the Y
-coordinate of the bottom edge.  The origin coordinate @samp{(0,0)} is
-taken to be the top left corner of the frame's window area.
-
-These edge values include the space used by the window's scroll bar,
-margins, fringes, header line, and mode line, if any.
-@end defun
-
-@defun window-inside-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates for the window's text area, rather than
-the edge coordinates for the window itself.  @var{window} must specify
-a live window.
-@end defun
-
-@defun window-absolute-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen.
-@end defun
-
-@defun window-inside-absolute-pixel-edges &optional window
-This function is like @code{window-inside-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen.  @var{window} must specify a live window.
-@end defun
+  @xref{Coordinates and Windows}, for more functions that report the
+positions of various parts of a window relative to the frame, from
+which you can calculate its size.  In particular, you can use the
+functions @code{window-pixel-edges} and
+@code{window-inside-pixel-edges} to find the size in pixels, for
+graphical displays.
 
 @node Resizing Windows
 @section Resizing Windows
@@ -943,8 +890,9 @@ direction as the existing window combination (otherwise, a new
 internal window is created anyway).  The default is @code{nil}.  Other
 values are reserved for future use.
 
-Thus, if the value is always @code{t}, each window tree is a binary
-tree: each window except the root window has exactly one sibling.
+Thus, if the value of this variable is at all times @code{t}, then at
+all times every window tree is a binary tree (a tree where each window
+except the root window has exactly one sibling).
 
 Furthermore, @code{split-window} calls
 @code{set-window-combination-limit} on the newly-created internal
@@ -2976,32 +2924,90 @@ is off the screen due to horizontal scrolling:
 @end group
 @end example
 
-
 @node Coordinates and Windows
 @section Coordinates and Windows
+@cindex frame-relative coordinate
+@cindex coordinate, relative to frame
+@cindex window position
+
+  This section describes functions that report the position of a
+window.  Most of these functions report positions relative to the
+window's frame.  In this case, the coordinate origin @samp{(0,0)} lies
+near the upper left corner of the frame.  For technical reasons, on
+graphical displays the origin is not located at the exact corner of
+the graphical window as it appears on the screen.  If Emacs is built
+with the GTK+ toolkit, the origin is at the upper left corner of the
+frame area used for displaying Emacs windows, below the title-bar,
+GTK+ menu bar, and tool bar (since these are drawn by the window
+manager and/or GTK+, not by Emacs).  But if Emacs is not built with
+GTK+, the origin is at the upper left corner of the tool bar (since in
+this case Emacs itself draws the tool bar).  In both cases, the X and
+Y coordinates increase rightward and downward respectively.
+
+  Except where noted, X and Y coordinates are reported in integer
+character units, i.e. numbers of lines and columns respectively.  On a
+graphical display, each ``line'' and ``column'' corresponds to the
+height and width of a default character specified by the frame's
+default font.
+
+@defun window-edges &optional window
+This function returns a list of the edge coordinates of @var{window}.
+If @var{window} is omitted or @code{nil}, it defaults to the selected
+window.
 
-This section describes how to relate screen coordinates to windows.
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}.  These list elements are, respectively, the X
+coordinate of the leftmost column occupied by the window, the Y
+coordinate of the topmost row, the X coordinate one column to the
+right of the rightmost column, and the Y coordinate one row down from
+the bottommost row.
 
-@defun window-at x y &optional frame
-This function returns the window containing the specified cursor
-position in the frame @var{frame}.  The coordinates @var{x} and @var{y}
-are measured in characters and count from the top left corner of the
-frame.  If they are out of range, @code{window-at} returns @code{nil}.
+Note that these are the actual outer edges of the window, including
+any header line, mode line, scroll bar, fringes, and display margins.
+On a text-only terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
+neighbor.
+@end defun
 
-If you omit @var{frame}, the selected frame is used.
+@defun window-inside-edges &optional window
+This function is similar to @code{window-edges}, but the returned edge
+values are for the text area of the window.  They exclude any header
+line, mode line, scroll bar, fringes, display margins, and vertical
+separator.
 @end defun
 
-@defun coordinates-in-window-p coordinates window
-This function checks whether a particular frame position falls within
-the window @var{window}.
+@defun window-top-line &optional window
+This function returns the Y coordinate of the topmost row of
+@var{window}, equivalent to the @var{top} entry in the list returned
+by @code{window-edges}.
+@end defun
+
+@defun window-left-column &optional window
+This function returns the X coordinate of the leftmost column of
+@var{window}, equivalent to the @var{left} entry in the list returned
+by @code{window-edges}.
+@end defun
 
-The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
-. @var{y})}.  The coordinates @var{x} and @var{y} are measured in
-characters, and count from the top left corner of the screen or frame.
+  The following functions can be used to relate a set of
+frame-relative coordinates to a window:
 
-The value returned by @code{coordinates-in-window-p} is non-@code{nil}
-if the coordinates are inside @var{window}.  The value also indicates
-what part of the window the position is in, as follows:
+@defun window-at x y &optional frame
+This function returns the live window at the frame-relative
+coordinates @var{x} and @var{y}, on frame @var{frame}.  If there is no
+window at that position, the return value is @code{nil}.  If
+@var{frame} is omitted or @code{nil}, it defaults to the selected
+frame.
+@end defun
+
+@defun coordinates-in-window-p coordinates window
+This function checks whether a window @var{window} occupies the
+frame-relative coordinates @var{coordinates}, and if so which part of
+the window that is.  @var{window} should be a live window.
+@var{coordinates} should be a cons cell of the form @code{(@var{x}
+. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
+
+If there is no window at the specified position, the return value is
+@code{nil} .  Otherwise, the return value is one of the following:
 
 @table @code
 @item (@var{relx} . @var{rely})
@@ -3038,6 +3044,44 @@ The function @code{coordinates-in-window-p} does not require a frame as
 argument because it always uses the frame that @var{window} is on.
 @end defun
 
+  The following functions return window positions in pixels, rather
+than character units.  Though mostly useful on graphical displays,
+they can also be called on text-only terminals, where the screen area
+of each text character is taken to be ``one pixel''.
+
+@defun window-pixel-edges &optional window
+This function returns a list of pixel coordinates for the edges of
+@var{window}.  If @var{window} is omitted or @code{nil}, it defaults
+to the selected window.
+
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}.  The list elements are, respectively, the X pixel
+coordinate of the left window edge, the Y pixel coordinate of the top
+edge, one more than the X pixel coordinate of the right edge, and one
+more than the Y pixel coordinate of the bottom edge.
+@end defun
+
+@defun window-inside-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the pixel coordinates for the edges of the window's text area,
+rather than the pixel coordinates for the edges of the window itself.
+@var{window} must specify a live window.
+@end defun
+
+  The following functions return window positions in pixels, relative
+to the display screen rather than the frame:
+
+@defun window-absolute-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.
+@end defun
+
+@defun window-inside-absolute-pixel-edges &optional window
+This function is like @code{window-inside-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.  @var{window} must specify a live window.
+@end defun
 
 @node Window Configurations
 @section Window Configurations