Update and enhance documentation of display of control characters.

 doc/emacs/display.texi (Text Display): Update the description,
 cross-references, and indexing related to display of control
 characters and raw bytes.
 doc/lispref/display.texi (Usual Display): Update the description,
 cross-references, and indexing related to display of control
 characters and raw bytes.

4 files changed, 57 insertions, 34 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 8cef196c90d..9abed71d1c7 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,9 @@
+2011-11-26  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Text Display): Update the description,
+        cross-references, and indexing related to display of control
+        characters and raw bytes.
+
 2011-11-25  Chong Yidong  <cyd@gnu.org>
 
         * frames.texi (Frames): Rewrite introduction.
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index a7ecc0dc551..4334d99461f 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1216,7 +1216,7 @@ characters include @acronym{ASCII} numbers, letters, and punctuation
 characters, as well as many non-@acronym{ASCII} characters.
 
 @vindex tab-width
-@cindex control character
+@cindex control characters on display
   The @acronym{ASCII} character set contains non-printing @dfn{control
 characters}.  Two of these are displayed specially: the newline
 character (Unicode code point @code{U+000A}) is displayed by starting
@@ -1228,19 +1228,21 @@ value between 1 and 1000, inclusive.  Note that how the tab character
 in the buffer is displayed has nothing to do with the definition of
 @key{TAB} as a command.
 
-  Other @acronym{ASCII} control characters are displayed as a caret
+  Other @acronym{ASCII} control characters, whose codes are below
+@code{U+0020} (octal 40, decimal 32), are displayed as a caret
 (@samp{^}) followed by the non-control version of the character, with
 the @code{escape-glyph} face.  For instance, the @samp{control-A}
 character, @code{U+0001}, is displayed as @samp{^A}.
 
+@cindex octal escapes
 @vindex ctl-arrow
-  The non-@acronym{ASCII}, non-printing characters @code{U+0080}
-(octal 200) through @code{U+009F} (octal 237) are displayed as octal
-escape sequences, with the @code{escape-glyph} face.  For instance,
+  The raw bytes with codes @code{U+0080} (octal 200) through
+@code{U+009F} (octal 237) are displayed as @dfn{octal escape
+sequences}, with the @code{escape-glyph} face.  For instance,
 character code @code{U+0098} (octal 230) is displayed as @samp{\230}.
 If you change the buffer-local variable @code{ctl-arrow} to
-@code{nil}, @acronym{ASCII} control characters are also displayed as
-octal escape sequences instead of caret escape sequences.
+@code{nil}, the @acronym{ASCII} control characters are also displayed
+as octal escape sequences instead of caret escape sequences.
 
 @vindex nobreak-char-display
 @cindex non-breaking space
@@ -1270,10 +1272,12 @@ elisp, The Emacs Lisp Reference Manual}.
   On graphical displays, some characters may have no glyphs in any of
 the fonts available to Emacs.  These @dfn{glyphless characters} are
 normally displayed as boxes containing the hexadecimal character code.
-You can control the display method by customizing the variable
-@code{glyphless-char-display-control}.  @xref{Glyphless Chars,,
-Glyphless Character Display, elisp, The Emacs Lisp Reference Manual},
-for details.
+Similarly, on text terminals, characters that cannot be displayed
+using the terminal encoding (@pxref{Terminal Coding}) are normally
+displayed as question signs.  You can control the display method by
+customizing the variable @code{glyphless-char-display-control}.
+@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs
+Lisp Reference Manual}, for details.
 
 @node Cursor Display
 @section Displaying the Cursor
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b0a7ce4ae47..72efbee0b5a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2011-11-26  Eli Zaretskii  <eliz@gnu.org>
+
+        * 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
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9849420b1f5..2032ecdc5bc 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5638,39 +5638,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 +5701,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