man/search.texi

[Luc Teirlinck]

I suggest the following changes to man/search.texi.

The sentence:

    You can make other commands usable within an incremental search by
  giving the command a address@hidden @code{isearch-scroll} property.

is cryptic to non-Elisp programmers.  Either one gives an example, as
the patch does, enabling non-Elisp programmers to use the feature, or,
alternatively, one could just delete the sentence instead.

The `\,' doc is even more cryptic to non-Elisp programmers.  The patch
explicitly says that it can be safely ignored if you are not an Elisp
programmer.  The `\?' feature requires no Elisp knowledge, so I put it
before the `\,' stuff.  It is easy to understand and does not require
an example.

The main part of the patch is an update for my recent changes to
{keep,flush}-lines.

The patch needs an anchor in man/display.texi, which the patch to that
file provides.

===File ~/search.texi-diff==================================
*** search.texi 23 Mar 2005 17:54:19 -0600      1.62
--- search.texi 03 Jul 2005 17:39:36 -0500      
***************
*** 294,300 ****
  @address@hidden (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
  within the search, thus letting you see more of the text near the
  current match.  You must run these commands via their key sequences to
! stay in the search---typing M-x @var{comand-name} will always
  terminate a search.
  
    You can give prefix arguments to these commands in the usual way.
--- 294,300 ----
  @address@hidden (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
  within the search, thus letting you see more of the text near the
  current match.  You must run these commands via their key sequences to
! stay in the search---typing M-x @var{command-name} will always
  terminate a search.
  
    You can give prefix arguments to these commands in the usual way.
***************
*** 309,314 ****
--- 309,324 ----
  
    You can make other commands usable within an incremental search by
  giving the command a address@hidden @code{isearch-scroll} property.
+ For example, to make @kbd{C-h l} usable within an incremental search
+ in all future Emacs sessions, you must first figure out (using
+ @kbd{C-h c C-h l}) that it runs the command @code{view-lossage}.  Then
+ you can put the following line in your @file{.emacs} file (@pxref{Init File}):
+ 
+ @example
+ (put 'view-lossage 'isearch-scroll t)
+ @end example
+ 
+ @noindent
  This works for commands that don't permanently change point, the
  buffer contents, the match data, the current buffer, or the selected
  window and frame.  The command must not delete the current window and
***************
*** 331,337 ****
  @vindex 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 @code{baud-rate} in @ref{Display Custom}.
  
  @vindex search-slow-window-lines
    The number of lines to use in slow terminal search display is controlled
--- 341,348 ----
  @vindex 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}).
  
  @vindex search-slow-window-lines
    The number of lines to use in slow terminal search display is controlled
***************
*** 1012,1018 ****
  performs the inverse transformation.  To include a @samp{\} in the
  text to replace with, you must enter @samp{\\}.
  
!   You can also use Lisp expressions to calculate parts of the
  replacement string.  To do this, write @samp{\,} followed by the
  expression in the replacement string.  Each replacement calculates the
  value of the expression and converts it to text without quoting (if
--- 1023,1037 ----
  performs the inverse transformation.  To include a @samp{\} in the
  text to replace with, you must enter @samp{\\}.
  
!   If you want to enter part of the replacement string by hand each
! time, use @samp{\?} in the replacement string.  Each replacement will
! ask you to edit the replacement string in the minibuffer, putting
! point where the @samp{\?} was.
! 
!   The remainder of this subsection is intended for specialized tasks
! and requires knowledge of Lisp.  Most readers can skip it.
! 
!   You can use Lisp expressions to calculate parts of the
  replacement string.  To do this, write @samp{\,} followed by the
  expression in the replacement string.  Each replacement calculates the
  value of the expression and converts it to text without quoting (if
***************
*** 1050,1071 ****
  \,(format "%-72sABC%05d" \& \#) @key{RET}
  @end example
  
-   If you want to enter part of the replacement string by hand each
- time, use @samp{\?} in the replacement string.  Each replacement will
- ask you to edit the replacement string in the minibuffer, putting
- point where the @samp{\?} was.  For example,
- 
- @example
- M-x replace-regexp @key{RET} address@hidden @key{RET}
- \&address@hidden:address@hidden @key{RET}
- @end example
- 
- @noindent
- will add labels starting with @address@hidden:address@hidden to occurrences of
- @address@hidden, but letting you edit each replacement before
- performing it.  To number the labels starting at 1, use @samp{\,(1+
- \#)} instead of @samp{\#}.
- 
  @node Replacement and Case, Query Replace, Regexp Replace, Replace
  @subsection Replace Commands and Case
  
--- 1069,1074 ----
***************
*** 1257,1263 ****
  for @var{regexp}.  To limit the search to part of the buffer, narrow
  to that part (@pxref{Narrowing}).  A numeric argument @var{n}
  specifies that @var{n} lines of context are to be displayed before and
! after each matching line.
  
  @kindex RET @r{(Occur mode)}
  @kindex o @r{(Occur mode)}
--- 1260,1267 ----
  for @var{regexp}.  To limit the search to part of the buffer, narrow
  to that part (@pxref{Narrowing}).  A numeric argument @var{n}
  specifies that @var{n} lines of context are to be displayed before and
! after each matching line.  Currently, occur can not correctly handle
! multiline matches.
  
  @kindex RET @r{(Occur mode)}
  @kindex o @r{(Occur mode)}
***************
*** 1271,1277 ****
  does not select it.
  
  Occur mode supports the @code{next-error} functionality described in
! in @ref{Compilation Mode}.
  
  @item M-x list-matching-lines
  Synonym for @kbd{M-x occur}.
--- 1275,1281 ----
  does not select it.
  
  Occur mode supports the @code{next-error} functionality described in
! @ref{Compilation Mode}.
  
  @item M-x list-matching-lines
  Synonym for @kbd{M-x occur}.
***************
*** 1290,1308 ****
  command operates on the region instead.
  
  @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
! Delete each line that contains a match for @var{regexp}, operating on
! the text after point.  In Transient Mark mode, if the region is
! active, the command operates on the region instead.
  
  @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
! Delete each line that @emph{does not} contain a match for
! @var{regexp}, operating on the text after point.  In Transient Mark
! mode, if the region is active, the command operates on the region
! instead.
  @end table
  
    You can also search multiple files under control of a tags table
! (@pxref{Tags Search}) or through Dired @kbd{A} command
  (@pxref{Operating on Files}), or ask the @code{grep} program to do it
  (@pxref{Grep Searching}).
  
--- 1294,1321 ----
  command operates on the region instead.
  
  @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
! This command deletes each line that contains a match for @var{regexp},
! operating on the text after point.  If a match is split across lines,
! it deletes all those lines.  It deletes the lines before starting to
! look for the next match; hence, it ignores a match starting on the
! same line at which another match ended.  It deletes the current line
! if it contains a match starting after point.  In Transient Mark mode,
! if the region is active, the command operates on the region instead.
! It deletes a line partially contained in the region if it contains a
! match entirely contained in the region.
  
  @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
! This command deletes each line that @emph{does not} contain a match for
! @var{regexp}, operating on the text after point.  If a match is split
! across lines, it keeps all those lines.  If point is not at the
! beginning of a line, it always keeps the current line.  In Transient
! Mark mode, if the region is active, the command operates on the region
! instead.  It never deletes lines that are only partially contained in
! the region (a newline that ends a line counts as part of that line).
  @end table
  
    You can also search multiple files under control of a tags table
! (@pxref{Tags Search}) or through the Dired @kbd{A} command
  (@pxref{Operating on Files}), or ask the @code{grep} program to do it
  (@pxref{Grep Searching}).
  
============================================================

===File ~/display.texi-diff=================================
Index: display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/display.texi,v
retrieving revision 1.95
diff -c -r1.95 display.texi
*** display.texi        25 Jun 2005 02:31:31 -0000      1.95
--- display.texi        5 Jul 2005 02:03:36 -0000
***************
*** 1135,1141 ****
  that do not override it.
  
  @vindex baud-rate
!   The variable @code{baud-rate} holds the output speed of the
  terminal, as far as Emacs knows.  Setting this variable does not
  change the speed of actual data transmission, but the value is used
  for calculations.  On terminals, it affects padding, and decisions
--- 1135,1141 ----
  that do not override it.
  
  @vindex baud-rate
!   The variable @address@hidden holds the output speed of the
  terminal, as far as Emacs knows.  Setting this variable does not
  change the speed of actual data transmission, but the value is used
  for calculations.  On terminals, it affects padding, and decisions
============================================================