[Emacs-diffs] /srv/bzr/emacs/trunk r106127: More edits to Display chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106127
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2011-10-18 17:11:17 -0400
message:
  More edits to Display chapter of Emacs manual.
  
  * doc/emacs/display.texi (Fringes): Move overflow-newline-into-fringe here,
  from Line Truncation node.
  (Standard Faces): Note that only the background of the cursor face
  has an effect.
  (Cursor Display): Fix descriptions of cursor face
  and bar cursor blinking.
  (Text Display): Document nobreak-char-display more clearly.
  (Line Truncation): Add xref to Split Window node.
  (Display Custom): Don't bother documenting baud-rate or
  no-redraw-on-reenter.
  
  * doc/emacs/search.texi (Slow Isearch): Node removed.
modified:
  admin/FOR-RELEASE
  doc/emacs/ChangeLog
  doc/emacs/display.texi
  doc/emacs/emacs.texi
  doc/emacs/search.texi
  etc/NEWS

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2011-10-15 16:37:45 +0000
+++ b/admin/FOR-RELEASE 2011-10-18 21:11:17 +0000
@@ -162,7 +162,7 @@
 custom.texi       
 dired.texi        
 dired-xtra.texi
-display.texi      
+display.texi      cyd
 emacs.texi        
 emacs-xtra.texi
 emerge-xtra.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-10-18 06:52:32 +0000
+++ b/doc/emacs/ChangeLog       2011-10-18 21:11:17 +0000
@@ -1,3 +1,18 @@
+2011-10-18  Chong Yidong  <address@hidden>
+
+       * display.texi (Fringes): Move overflow-newline-into-fringe here,
+       from Line Truncation node.
+       (Standard Faces): Note that only the background of the cursor face
+       has an effect.
+       (Cursor Display): Fix descriptions of cursor face
+       and bar cursor blinking.
+       (Text Display): Document nobreak-char-display more clearly.
+       (Line Truncation): Add xref to Split Window node.
+       (Display Custom): Don't bother documenting baud-rate or
+       no-redraw-on-reenter.
+
+       * search.texi (Slow Isearch): Node removed.
+
 2011-10-18  Glenn Morris  <address@hidden>
 
        * maintaining.texi (Registering): Remove vc-initial-comment.  (Bug#9745)

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-10-18 01:42:28 +0000
+++ b/doc/emacs/display.texi    2011-10-18 21:11:17 +0000
@@ -554,7 +554,7 @@
 The face for displaying control characters and escape sequences
 (@pxref{Text Display}).
 @item nobreak-space
-The face for displaying ``non-breaking'' space characters (@pxref{Text
+The face for displaying ``no-break'' space characters (@pxref{Text
 Display}).
 @end table
 
@@ -599,7 +599,8 @@
 between the text area and the window's right and left borders.)
 @xref{Fringes}.
 @item cursor
-This face determines the color of the text cursor.
+The @code{:background} attribute of this face specifies the color of
+the text cursor.  @xref{Cursor Display}.
 @item tooltip
 This face is used for tooltip text.  By default, if Emacs is built
 with GTK support, tooltips are drawn via GTK and this face has no
@@ -901,9 +902,14 @@
 @section Window Fringes
 @cindex fringes
 
-  On a graphical display, each Emacs window normally has narrow
address@hidden set-fringe-style
address@hidden fringe-mode
+  On graphical displays, each Emacs window normally has narrow
 @dfn{fringes} on the left and right edges.  The fringes are used to
 display symbols that provide information about the text in the window.
+You can type @kbd{M-x fringe-mode} to disable the fringes, or modify
+their width.  This command affects fringes in all frames; to modify
+fringes on the selected frame only, use @kbd{M-x set-fringe-style}.
 
   The most common use of the fringes is to indicate a continuation
 line (@pxref{Continuation Lines}).  When one line of text is split
@@ -924,17 +930,18 @@
 boundaries (@pxref{Displaying Boundaries}), and where a program you
 are debugging is executing (@pxref{Debuggers}).
 
address@hidden set-fringe-style
address@hidden fringe-mode
-  You can enable and disable the fringes for all frames using
address@hidden fringe-mode}.  To enable and disable the fringes
-for the selected frame, use @kbd{M-x set-fringe-style}.
address@hidden overflow-newline-into-fringe
+  The fringe is also used for drawing the cursor, if the current line
+is exactly as wide as the window and point is at the end of the line.
+To disable this, change the variable
address@hidden to @code{nil}; this causes Emacs
+to continue or truncate lines that are exactly as wide as the window.
 
 @node Displaying Boundaries
 @section Displaying Boundaries
 
 @vindex indicate-buffer-boundaries
-  On a graphical display, Emacs can indicate the buffer boundaries in
+  On graphical displays, Emacs can indicate the buffer boundaries in
 the fringes.  If you enable this feature, the first line and the last
 line are marked with angle images in the fringes.  This can be
 combined with up and down arrow images which say whether it is
@@ -1127,14 +1134,15 @@
 @vindex display-time-mail-file
 @vindex display-time-mail-directory
   The word @samp{Mail} appears after the load level if there is mail
-for you that you have not read yet.  On a graphical display you can use
-an icon instead of @samp{Mail} by customizing
address@hidden; this may save some space on the mode
-line.  You can customize @code{display-time-mail-face} to make the mail
-indicator prominent.  Use @code{display-time-mail-file} to specify
-the mail file to check, or set @code{display-time-mail-directory}
-to specify the directory to check for incoming mail (any nonempty regular
-file in the directory is considered as ``newly arrived mail'').
+for you that you have not read yet.  On graphical displays, you can
+use an icon instead of @samp{Mail} by customizing
address@hidden; this may save some space on the
+mode line.  You can customize @code{display-time-mail-face} to make
+the mail indicator prominent.  Use @code{display-time-mail-file} to
+specify the mail file to check, or set
address@hidden to specify the directory to check
+for incoming mail (any nonempty regular file in the directory is
+considered as ``newly arrived mail'').
 
 @cindex mail (on mode line)
 @findex display-battery-mode
@@ -1152,7 +1160,7 @@
 @cindex mode line, 3D appearance
 @cindex attributes of mode line, changing
 @cindex non-integral number of lines in a window
-  On a graphical display, the mode line is drawn as a 3D box.  If you
+  On graphical displays, the mode line is drawn as a 3D box.  If you
 don't like this effect, you can disable it by customizing the
 @code{mode-line} face and setting its @code{box} attribute to
 @code{nil}.  @xref{Face Customization}.
@@ -1218,17 +1226,23 @@
 octal escape sequences instead of caret escape sequences.
 
 @vindex nobreak-char-display
address@hidden non-breaking space, display
address@hidden non-breaking hyphen, display
address@hidden soft hyphen, display
-  There are two special ``non-breaking'' versions of the space and
-hyphen characters, which are used where a line should not be broken.
-Emacs normally displays these characters with special faces
-(respectively, @code{nobreak-space} and @code{escape-glyph}) to
-distinguish them from ordinary spaces and hyphens.  You can turn off
-this feature by setting the variable @code{nobreak-char-display} to
address@hidden  If you set the variable to any other value, that means to
-prefix these characters with an escape character.
address@hidden non-breaking space
address@hidden non-breaking hyphen
address@hidden soft hyphen
+  Some address@hidden characters have the same appearance as an
address@hidden space or hyphen (minus) character.  Such characters
+can cause problems if they are entered into a buffer without your
+realization, e.g. by yanking; for instance, source code compilers
+typically do not treat address@hidden spaces as whitespace
+characters.  To deal with this problem, Emacs displays such characters
+specially: it displays @code{U+00A0} (no-break space) with the
address@hidden face, and it displays @code{U+00AD} (soft
+hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking
+hyphen) with the @code{escape-glyph} face.  To disable this, change
+the variable @code{nobreak-char-display} to @code{nil}.  If you give
+this variable a address@hidden and address@hidden value, Emacs instead
+displays such characters as a highlighted backslash followed by a
+space or hyphen.
 
   You can customize the way any particular character code is displayed
 by means of a display table.  @xref{Display Tables,, Display Tables,
@@ -1246,48 +1260,61 @@
 
 @node Cursor Display
 @section Displaying the Cursor
address@hidden text cursor
+
address@hidden visible-cursor
+  On a text terminal, the cursor's appearance is controlled by the
+terminal, largely out of the control of Emacs.  Some terminals offer
+two different cursors: a ``visible'' static cursor, and a ``very
+visible'' blinking cursor.  By default, Emacs uses the very visible
+cursor, and switches to it when you start or resume Emacs.  If the
+variable @code{visible-cursor} is @code{nil} when Emacs starts or
+resumes, it uses the normal cursor.
+
address@hidden cursor face
address@hidden cursor-type
+  On a graphical display, many more properties of the text cursor can
+be altered.  To customize its color, change the @code{:background}
+attribute of the face named @code{cursor} (@pxref{Face
+Customization}).  (The other attributes of this face have no effect;
+the text shown under the cursor is drawn using the frame's background
+color.)  To change its shape, customize the buffer-local variable
address@hidden; possible values are @code{box} (the default),
address@hidden (a hollow box), @code{bar} (a vertical bar), @code{(bar
+. @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a
+horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n}
+pixels tall), or @code{nil} (no cursor at all).
 
 @findex blink-cursor-mode
address@hidden cursor, blinking
address@hidden blinking cursor
 @vindex blink-cursor-alist
address@hidden cursor, locating visually
address@hidden cursor, blinking
-  You can customize the cursor's color, and whether it blinks, using
-the @code{cursor} Custom group (@pxref{Easy Customization}).  On
-a graphical display, the command @kbd{M-x blink-cursor-mode} enables
-or disables the blinking of the cursor.  (On text terminals, the
-terminal itself blinks the cursor, and Emacs has no control over it.)
-You can control how the cursor appears when it blinks off by setting
-the variable @code{blink-cursor-alist}.
-
address@hidden cursor-type
-  You can change the shape of the cursor from the default ``box'' look
-to a bar by altering the @code{cursor-type} variable.
-
address@hidden visible-cursor
-  Some text terminals offer two different cursors: the normal cursor
-and the very visible cursor, where the latter may be e.g. bigger or
-blinking.  By default Emacs uses the very visible cursor, and switches
-to it when you start or resume Emacs.  If the variable
address@hidden is @code{nil} when Emacs starts or resumes, it
-doesn't switch, so it uses the normal cursor.
-
address@hidden cursor in non-selected windows
address@hidden cursor-in-non-selected-windows
-  Normally, the cursor appears in non-selected windows without
-blinking, with the same appearance as when the blinking cursor blinks
-``off.''  For a box cursor, this is a hollow box; for a bar cursor,
-this is a thinner bar.  To turn off cursors in non-selected windows,
-customize the variable @code{cursor-in-non-selected-windows} and
-assign it a @code{nil} value.
+  To disable cursor blinking, change the variable
address@hidden to @code{nil} (@pxref{Easy Customization}),
+or add the line @code{(blink-cursor-mode 0)} to your init file.
+Alternatively, you can change how the cursor looks when it ``blinks
+off'' by customizing the list variable @code{blink-cursor-alist}.
+Each element in the list should have the form @code{(@var{on-type}
+. @var{off-type})}; this means that if the cursor is displayed as
address@hidden when it blinks on (where @var{on-type} is one of the
+cursor types described above), then it is displayed as @var{off-type}
+when it blinks off.
 
 @vindex x-stretch-cursor
 @cindex wide block cursor
-  On graphical displays, Emacs can optionally draw the block cursor
-as wide as the character under the cursor---for example, if the cursor
-is on a tab character, it would cover the full width occupied by that
-tab character.  To enable this feature, set the variable
+  Some characters, such as tab characters, are ``extra wide''.  When
+the cursor is positioned over such a character, it is normally drawn
+with the default character width.  You can make the cursor stretch to
+cover wide characters, by changing the variable
 @code{x-stretch-cursor} to a address@hidden value.
 
address@hidden cursor in non-selected windows
address@hidden cursor-in-non-selected-windows
+  The cursor normally appears in non-selected windows as a
+non-blinking hollow box.  (For a bar cursor, it instead appears as a
+thinner bar.)  To turn off cursors in non-selected windows, change the
+variable @code{cursor-in-non-selected-windows} to @code{nil}.
+
 @findex hl-line-mode
 @findex global-hl-line-mode
 @cindex highlight current line
@@ -1297,18 +1324,17 @@
 global-hl-line-mode} enables or disables the same mode globally.
 
 @node Line Truncation
address@hidden Truncation of Lines
address@hidden Line Truncation
 
 @cindex truncation
 @cindex line truncation, and fringes
-  As an alternative to continuation (@pxref{Continuation Lines}), Emacs
-can display long lines by @dfn{truncation}.  This means that all the
-characters that do not fit in the width of the screen or window do not
-appear at all.  On graphical displays, a small straight arrow in the
-fringe indicates truncation at either end of the line.  On text-only
-terminals, @samp{$} appears in the leftmost column when there is text
-truncated to the left, and in the rightmost column when there is text
-truncated to the right.
+  As an alternative to continuation (@pxref{Continuation Lines}),
+Emacs can display long lines by @dfn{truncation}.  This means that all
+the characters that do not fit in the width of the screen or window do
+not appear at all.  On graphical displays, a small straight arrow in
+the fringe indicates truncation at either end of the line.  On
+text-only terminals, this is indicated with @samp{$} signs in the
+leftmost and/or rightmost columns.
 
 @vindex truncate-lines
 @findex toggle-truncate-lines
@@ -1320,21 +1346,12 @@
 are truncated; if it is @code{nil}, they are continued onto multiple
 screen lines.  Setting the variable @code{truncate-lines} in any way
 makes it local to the current buffer; until that time, the default
-value is in effect.  The default value is normally @code{nil}.
-
address@hidden @vindex truncate-partial-width-windows  @c Idx entry is in Split 
Windows.
-  If the variable @code{truncate-partial-width-windows} is
address@hidden, it forces truncation rather than continuation in any
-window less than the full width of the screen or frame, regardless of
-the value of @code{truncate-lines}.  See also @ref{Display,, Display,
-elisp, The Emacs Lisp Reference Manual}.
-
address@hidden overflow-newline-into-fringe
-  If the variable @code{overflow-newline-into-fringe} is
address@hidden on a graphical display, then Emacs does not continue or
-truncate a line which is exactly as wide as the window.  Instead, the
-newline overflows into the right fringe, and the cursor appears in the
-fringe when positioned on that newline.
+value, which is normally @code{nil}, is in effect.
+
address@hidden truncate-partial-width-windows
+  If a split window becomes too narrow, Emacs may automatically enable
+line truncation.  @xref{Split Window}, for the variable
address@hidden which controls this.
 
 @node Visual Line Mode
 @section Visual Line Mode
@@ -1387,11 +1404,8 @@
 @node Display Custom
 @section Customization of Display
 
-  This section describes variables (@pxref{Variables}) that you can
-change to customize how Emacs displays.  Beginning users can skip
-it.
address@hidden the reason for that pxref is because an xref early in the
address@hidden ``echo area'' section leads here.
+  This section describes variables that control miscellaneous aspects
+of the appearance of the Emacs screen.  Beginning users can skip it.
 
 @vindex visible-bell
   If the variable @code{visible-bell} is address@hidden, Emacs attempts
@@ -1405,18 +1419,6 @@
 to start, or zero, meaning don't echo at all.  The value takes effect when
 there is someting to echo.  @xref{Echo Area}.
 
address@hidden baud-rate
-  The variable @address@hidden holds the output
-speed of the terminal.  Setting this variable does not change the
-speed of actual data transmission, but the value is used for
-calculations.  On text-only terminals, it affects padding, and
-decisions about whether to scroll part of the screen or redraw it
-instead.  It also affects the behavior of incremental search.  On
-graphical displays, @code{baud-rate} is only used to determine how
-frequently to look for pending input during display updating.  A
-higher value of @code{baud-rate} means that check for pending input
-will be done less frequently.
-
 @cindex mouse pointer
 @cindex hourglass pointer display
 @vindex display-hourglass
@@ -1458,15 +1460,3 @@
 result in text that is hard to read.  Call the function
 @code{tty-suppress-bold-inverse-default-colors} with a address@hidden
 argument to suppress the effect of bold-face in this case.
-
address@hidden no-redraw-on-reenter
-  On a text-only terminal, when you reenter Emacs after suspending, Emacs
-normally clears the screen and redraws the entire display.  On some
-terminals with more than one page of memory, it is possible to arrange
-the termcap entry so that the @samp{ti} and @samp{te} strings (output
-to the terminal when Emacs is entered and exited, respectively) switch
-between pages of memory so as to use one page for Emacs and another
-page for other output.  On such terminals, you might want to set the variable
address@hidden address@hidden; this tells Emacs to
-assume, when resumed, that the screen page it is using still contains
-what Emacs last wrote there.

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-10-18 01:42:28 +0000
+++ b/doc/emacs/emacs.texi      2011-10-18 21:11:17 +0000
@@ -388,7 +388,6 @@
                           or else edit the search string.
 * Isearch Scroll::      Scrolling during an incremental search.
 * Isearch Minibuffer::  Incremental search of the minibuffer history.
-* Slow Isearch::        Incremental search features for slow terminals.
 
 Replacement Commands
 

=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi     2011-10-01 21:54:33 +0000
+++ b/doc/emacs/search.texi     2011-10-18 21:11:17 +0000
@@ -60,7 +60,6 @@
                           or else edit the search string.
 * Isearch Scroll::      Scrolling during an incremental search.
 * Isearch Minibuffer::  Incremental search of the minibuffer history.
-* Slow Isearch::        Incremental search features for slow terminals.
 @end menu
 
 @node Basic Isearch
@@ -362,30 +361,6 @@
 afterwards.  Cancelling the search, with @kbd{C-g}, restores the
 contents of the minibuffer when you began the search.
 
address@hidden Slow Isearch
address@hidden Slow Terminal Incremental Search
-
-  Incremental search on a slow terminal uses a modified style of display
-that is designed to take less time.  Instead of redisplaying the buffer at
-each place the search gets to, it creates a new single-line window and uses
-that to display the line that the search has found.  The single-line window
-comes into play as soon as point moves outside of the text that is already
-on the screen.
-
-  When you terminate the search, the single-line window is removed.
-Emacs then redisplays the window in which the search was done, to show
-its new position of point.
-
address@hidden search-slow-speed
-  The slow terminal style of display is used when the terminal baud rate is
-less than or equal to the value of the variable @code{search-slow-speed},
-initially 1200.  See also the discussion of the variable @code{baud-rate}
-(@pxref{baud-rate,, Customization of Display}).
-
address@hidden search-slow-window-lines
-  The number of lines to use in slow terminal search display is controlled
-by the variable @code{search-slow-window-lines}.  Its normal value is 1.
-
 @node Nonincremental Search
 @section Nonincremental Search
 @cindex nonincremental search

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-10-18 15:55:20 +0000
+++ b/etc/NEWS  2011-10-18 21:11:17 +0000
@@ -109,9 +109,9 @@
 *** Completion can cycle, depending on completion-cycle-threshold.
 +++
 *** New completion style `substring'.
-
++++
 *** Completion style can be set per-category `completion-category-overrides'.
-
++++
 *** Completion of buffers now uses substring completion by default.
 
 ** Mail changes
@@ -225,6 +225,10 @@
 ---
 *** New input methods for Farsi: farsi and farsi-translit.
 
++++
+*** `nobreak-char-display' now also highlights Unicode hyphen chars
+(U+2010 and U+2011).
+
 ** Improved GTK integration
 
 *** GTK scroll-bars are now placed on the right by default.