[Emacs-diffs] /srv/bzr/emacs/trunk r106525: Update and enhance documentation of display of control characters.

[Eli Zaretskii]

------------------------------------------------------------
revno: 106525
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2011-11-26 15:51:58 +0200
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/display.texi
  doc/lispref/ChangeLog
  doc/lispref/display.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-11-25 15:43:34 +0000
+++ b/doc/emacs/ChangeLog       2011-11-26 13:51:58 +0000
@@ -1,3 +1,9 @@
+2011-11-26  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * frames.texi (Frames): Rewrite introduction.

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-11-24 01:58:14 +0000
+++ b/doc/emacs/display.texi    2011-11-26 13:51:58 +0000
@@ -1216,7 +1216,7 @@
 characters, as well as many address@hidden characters.
 
 @vindex tab-width
address@hidden control character
address@hidden 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 @@
 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
address@hidden (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}.
 
address@hidden octal escapes
 @vindex ctl-arrow
-  The address@hidden, 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
address@hidden (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
address@hidden, @acronym{ASCII} control characters are also displayed as
-octal escape sequences instead of caret escape sequences.
address@hidden, 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 @@
   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
address@hidden  @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}.
address@hidden Chars,, Glyphless Character Display, elisp, The Emacs
+Lisp Reference Manual}, for details.
 
 @node Cursor Display
 @section Displaying the Cursor

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-11-25 14:24:05 +0000
+++ b/doc/lispref/ChangeLog     2011-11-26 13:51:58 +0000
@@ -1,3 +1,9 @@
+2011-11-26  Eli Zaretskii  <address@hidden>
+
+       * 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  <address@hidden>
 
        * windows.texi (Splitting Windows): Fix description of

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2011-11-20 20:21:22 +0000
+++ b/doc/lispref/display.texi  2011-11-26 13:51:58 +0000
@@ -5638,39 +5638,45 @@
 @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.
-
address@hidden
-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
address@hidden, 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 address@hidden characters
-that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
-emacs, The GNU Emacs Manual}.
-
address@hidden
-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{\}.)
-
address@hidden
-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.
+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.
+
address@hidden
+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 address@hidden,
+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).
+
address@hidden octal escapes
address@hidden
+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.
+
address@hidden
address@hidden 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 @@
 This buffer-local variable controls how control characters are
 displayed.  If it is address@hidden, 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