* doc/emacs/misc.texi (Shell): Document async-shell-command.

* doc/emacs/building.texi (Grep Searching): Document zrgrep.

* doc/emacs/mini.texi (Completion Options):
* doc/lispref/minibuf.texi (Completion Styles): Document `initials' style.

6 files changed, 226 insertions, 63 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 62000a556c3..f6dfdc91e0f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,11 @@
+2009-12-29  Chong Yidong  <cyd@stupidchicken.com>
+
+        * misc.texi (Shell): Document async-shell-command.
+
+        * building.texi (Grep Searching): Document zrgrep.
+
+        * mini.texi (Completion Options): Mention `initals' completion style.
+
 2009-12-24  Chong Yidong  <cyd@stupidchicken.com>
 
         * emacs.texi (Top): Update node listing.
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 343eb646a83..619e1b0271d 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -356,8 +356,10 @@ listed in the buffer named @samp{*grep*}.
 @item M-x grep-find
 @itemx M-x find-grep
 @itemx M-x rgrep
-Run @code{grep} via @code{find}, with user-specified arguments, and
-collect output in the buffer named @samp{*grep*}.
+Run @code{grep} via @code{find}, and collect output in the buffer
+named @samp{*grep*}.
+@item M-x zrgrep
+Run @code{zgrep} and collect output in the buffer named @samp{*grep*}.
 @item M-x kill-grep
 Kill the running @code{grep} subprocess.
 @end table
@@ -400,21 +402,22 @@ the @code{find-grep-dired} command, in @ref{Dired and Find}.
 
 @findex lgrep
 @findex rgrep
+@findex zrgrep
   The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
 (recursive grep) are more user-friendly versions of @code{grep} and
 @code{grep-find}, which prompt separately for the regular expression
 to match, the files to search, and the base directory for the search.
-Case sensitivity of the search is controlled by the
-current value of @code{case-fold-search}.
+Case sensitivity of the search is controlled by the current value of
+@code{case-fold-search}.  The command @kbd{M-x zrgrep} is similar to
+@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to
+search the contents of gzipped files.
 
-These commands build the shell commands based on the variables
+  These commands build the shell commands based on the variables
 @code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
-(for @code{rgrep}).
+(for @code{rgrep}).  The files to search can use aliases defined in
+the variable @code{grep-files-aliases}.
 
-The files to search can use aliases defined in the variable
-@code{grep-files-aliases}.
-
-Subdirectories listed in the variable
+  Subdirectories listed in the variable
 @code{grep-find-ignored-directories} such as those typically used by
 various version control systems, like CVS and arch, are automatically
 skipped by @code{rgrep}.
@@ -854,11 +857,12 @@ multiple programs within one Emacs session.
 * Source Buffers::              Use the mouse in the fringe/margin to
                                 control your program.
 * Breakpoints Buffer::          A breakpoint control panel.
+* Threads Buffer::              Displays your threads.
 * Stack Buffer::                Select a frame from the call stack.
 * Other GDB-UI Buffers::        Input/output, locals, registers,
                                 assembler, threads and memory buffers.
 * Watch Expressions::           Monitor variable values in the speedbar.
-* Reverse Debugging::           Execute and reverse debug your program.
+* Multithreaded Debugging::     Debugging programs with several threads.
 @end menu
 
 @node GDB-UI Layout
@@ -883,7 +887,7 @@ displays the following frame layout:
 |--------------------------------+--------------------------------+
 |   Primary Source buffer        |   I/O buffer for debugged pgm  |
 |--------------------------------+--------------------------------+
-|   Stack buffer                 |   Breakpoints/Threads buffer   |
+|   Stack buffer                 |   Breakpoints/Thread buffer    |
 +--------------------------------+--------------------------------+
 @end group
 @end smallexample
@@ -1011,10 +1015,92 @@ Visit the source line for the current breakpoint
 Visit the source line for the breakpoint you click on.
 @end table
 
+@vindex gdb-show-threads-by-default
 When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
 shares its window with the threads buffer.  To switch from one to the
 other click with @kbd{Mouse-1} on the relevant button in the header
-line.
+line, or press @kbd{TAB} inside that buffer.  If
+@code{gdb-show-threads-by-default} is non-@code{nil}, the threads
+buffer, rather than the breakpoints buffer, is shown at start up.
+
+@node Threads Buffer
+@subsubsection Threads Buffer
+
+@findex gdb-select-thread
+The threads buffer displays a summary of all threads currently in your
+program (@pxref{Threads, Threads, Debugging programs with multiple
+threads, gdb, The GNU debugger}).  Move point to any thread in the list
+and press @key{RET} to select it (@code{gdb-select-thread}) and
+display the associated source in the primary source buffer.
+Alternatively, click @kbd{Mouse-2} on a thread to select it.  Contents
+of all GDB buffers are updated whenever you select a thread.
+
+  You can customize variables under @code{gdb-buffers} group to select
+fields included in threads buffer.
+
+@table @code
+@item gdb-thread-buffer-verbose-names
+@vindex gdb-thread-buffer-verbose-names
+Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in
+threads buffer.
+
+@item gdb-thread-buffer-arguments
+@vindex gdb-thread-buffer-arguments
+Show arguments of thread top frames in threads buffer.
+
+@item gdb-thread-buffer-locations
+@vindex gdb-thread-buffer-locations
+Show file information or library names in threads buffer.
+
+@item gdb-thread-buffer-addresses
+@vindex gdb-thread-buffer-addresses
+Show addresses for thread frames in threads buffer.
+@end table
+
+  It’s possible to observe information for several threads
+simultaneously (in addition to buffers which show information for
+currently selected thread) using the following keys from the threads
+buffer.
+
+@table @kbd
+@item d
+@kindex d @r{(GDB threads buffer)}
+@findex gdb-display-disassembly-for-thread
+Display disassembly buffer for the thread at current line.
+(@code{gdb-display-disassembly-for-thread})
+
+@item f
+@kindex f @r{(GDB threads buffer)}
+@findex gdb-display-stack-for-thread
+Display stack buffer for the thread at current line.
+(@code{gdb-display-stack-for-thread}).
+
+@item l
+@kindex l @r{(GDB threads buffer)}
+@findex gdb-display-locals-for-thread
+Display locals buffer for the thread at current line.
+(@code{gdb-display-locals-for-thread}).
+
+@item r
+@kindex r @r{(GDB threads buffer)}
+@findex gdb-display-registers-for-thread
+Display registers buffer for the thread at current line.
+(@code{gdb-display-registers-for-thread}).
+@end table
+
+Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and
+@kbd{R} displays the corresponding buffer in a new frame.
+
+  When you create a buffer showing information about some specific
+thread, it becomes bound to that thread and keeps showing actual
+information while you debug your program.  Every GDB buffer contains a
+number of thread it shows information for in its mode name.  Thread
+number is also included in the buffer name of bound buffers to prevent
+buffer names clashing.
+
+Further commands are available in the threads buffer which depend on the
+mode of GDB that is used for controlling execution of your program.
+(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}).
 
 @node Stack Buffer
 @subsubsection Stack Buffer
@@ -1051,7 +1137,7 @@ as are the commands to send signals to the debugged program.
 @item Locals Buffer
 The locals buffer displays the values of local variables of the
 current frame for simple data types (@pxref{Frame Info, Frame Info,
-Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
+Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
 click @kbd{Mouse-2} on the value if you want to edit it.
 
 Arrays and structures display their type only.  With GDB 6.4 or later,
@@ -1070,27 +1156,12 @@ With GDB 6.4 or later, recently changed register values display with
 press @key{SPC} to toggle the display of floating point registers
 (@code{toggle-gdb-all-registers}).
 
-@item Assembler Buffer
-The assembler buffer displays the current frame as machine code.  An
+@item Disassembly Buffer
+The disassembly buffer displays the current frame as machine code.  An
 arrow points to the current instruction, and you can set and remove
 breakpoints as in a source buffer.  Breakpoint icons also appear in
 the fringe or margin.
 
-@item Threads Buffer
-@findex gdb-threads-select
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}).  Move point to any thread in the
-list and press @key{RET} to select it (@code{gdb-threads-select}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it.  If the
-locals buffer is visible, its contents update to display the variables
-that are local in the new thread.
-
-When there is more than one main thread and the threads buffer is
-present, Emacs displays the selected thread number in the mode line of
-many of the GDB-UI Buffers.
-
 @item Memory Buffer
 The memory buffer lets you examine sections of program memory
 (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
@@ -1103,8 +1174,9 @@ size for these data items.
 
 When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
 shares its window with the breakpoints buffer, and the locals buffer
-with the registers buffer.  To switch from one to the other click with
-@kbd{Mouse-1} on the relevant button in the header line.
+with the registers buffer. To switch from one to the other click with
+@kbd{Mouse-1} on the relevant button in the header line or press
+@kbd{TAB} inside the buffer.
 
 @node Watch Expressions
 @subsubsection Watch Expressions
@@ -1172,26 +1244,96 @@ expressions updates, set @code{gdb-speedbar-auto-raise} to
 non-@code{nil}.  This can be useful if you are debugging with a full
 screen Emacs frame.
 
-@node Reverse Debugging
-@subsubsection Reverse Debugging
-
-  The GDB tool bar shares many buttons with the other GUD debuggers
-for tasks like stepping and printing expressions.  It also has a
-further set of buttons that allow reverse debugging (@pxref{Process
-Record and Replay, , ,gdb, The GNU debugger}).  This is useful when it
-takes a long time to reproduce the conditions where your program fails
-or for transient problems, like race conditions in multi-threaded
-programs, where a failure might otherwise be hard to reproduce.
-
-To use reverse debugging, set a breakpoint slightly before the
-location of interest and run your program to that point.  Enable
-process recording by clicking on the record button.  At this point, a
-new set of buttons appear.  These buttons allow program execution in
-the reverse direction.  Run your program over the code where the
-problem occurs, and then use the new set of buttons to retrace your
-steps, examine values, and analyze the problem.  When analysis is
-complete, turn off process recording by clicking on the record button
-again.
+@node Multithreaded Debugging
+@subsubsection Stopping and Starting Multi-threaded Programs
+@cindex Multithreaded debugging in GDB
+
+@subsubheading All-stop Debugging
+
+In all-stop mode, whenever your program stops, @emph{all} threads of
+execution stop.  Likewise, whenever you restart the program, all
+threads start executing.  @xref{All-Stop Mode, , All-Stop Mode, gdb,
+The GNU debugger}.  You can enable this behaviour in Emacs by setting
+@code{gdb-non-stop-setting} to @code{nil} before starting a debugging
+session.
+
+@subsubheading Non-stop Debugging
+@cindex Non-stop debugging in GDB
+
+For some multi-threaded targets, GDB supports a further mode of
+operation in which you can examine stopped program threads in the
+debugger while other threads continue to execute freely.
+@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}.
+This is referred to as @dfn{non-stop} mode.
+
+Versions of GDB prior to 7.0 do not support non-stop mode and it does
+not work on all targets.  In such cases, Emacs uses all-stop mode
+regardless of the value of @code{gdb-non-stop-setting}.
+
+@vindex gdb-non-stop-setting
+If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the
+default value), Emacs tries to start GDB in non-stop mode.  Note that
+GDB debugging session needs to be restarted for change of this setting
+to take effect.
+
+@vindex gdb-switch-when-another-stopped
+When a thread stops in non-stop mode, Emacs automatically switches to
+that thread.  It may be undesirable to allow switching of current
+thread when some other stopped thread is already selected.  Set
+@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this.
+
+@vindex gdb-switch-reasons
+Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop.  Customize
+@code{gdb-switch-reasons} to select stop reasons which make Emacs
+switch thread.
+
+@vindex gdb-stopped-hooks
+The variable @code{gdb-stopped-hooks} allows you to execute your
+functions whenever some thread stops.
+
+  In non-stop mode, you can switch between different modes for GUD
+execution control commands.
+
+@vindex gdb-gud-control-all-threads
+@table @dfn
+@item Non-stop/A
+
+When @code{gdb-gud-control-all-threads} is @code{t} (the default
+value), interruption and continuation commands apply to all threads,
+so you can halt or continue all your threads with one command using
+@code{gud-stop-subjob} and @code{gud-cont}, respectively.  The
+@samp{Go} button is shown on the toolbar when at least one thread is
+stopped, whereas @samp{Stop} button is shown when at least one thread
+is running.
+
+@item Non-stop/T
+
+When @code{gdb-gud-control-all-threads} is @code{nil}, only the
+current thread is stopped/continued.  @samp{Go} and @samp{Stop}
+buttons on the GUD toolbar are shown depending on the state of current
+thread.
+@end table
+
+You can change the current value of @code{gdb-gud-control-all-threads}
+from the tool bar or from @samp{GUD->GDB-MI} menu.
+
+  Stepping commands always apply to the current thread.
+
+@subsubheading Fine Thread Control
+
+  In non-stop mode, you can interrupt/continue your threads without
+selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
+under point, @kbd{c} continues it, @kbd{s} steps through.  More such
+commands may be added in the future.
+
+Combined with creating bound buffers for any thread, this allows you
+to change and track state of many threads in the same time.
+
+  Note that when you interrupt a thread, it stops with @samp{signal
+received} reason.  If that reason is included in your
+@code{gdb-switch-reasons} (it is by default), Emacs will switch to
+that thread.
 
 @node Executing Lisp
 @section Executing Lisp Expressions
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 37d483d3f9d..0dd01f2b0c0 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -456,12 +456,13 @@ default value is @code{nil}).
 using the variable @code{completion-styles}.  Its value should be a
 list of symbols, each representing a @dfn{completion style}; valid
 style symbols are @code{basic}, @code{partial-completion},
-@code{emacs22}, and @code{emacs21}.  When completing, Emacs attempts
-to use the first completion style in the list; if this does not return
-any completion alternatives, it tries the next completion style in the
-list, and so on.  The completion rules described in @ref{Completion
-Commands} correspond to the default value of @code{completion-styles},
-which is @code{(basic partial-completion emacs22)}.
+@code{emacs22}, @code{emacs21}, and @code{initials}.  When completing,
+Emacs attempts to use the first completion style in the list; if this
+does not return any completion alternatives, it tries the next
+completion style in the list, and so on.  The completion rules
+described in @ref{Completion Commands} correspond to the default value
+of @code{completion-styles}, which is @code{(basic partial-completion
+emacs22)}.
 
 @cindex Icomplete mode
 @findex icomplete-mode
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 616ed0051d5..112af066fe8 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -485,6 +485,9 @@ Run the shell command line @var{cmd} and display the output
 Run the shell command line @var{cmd} with region contents as input;
 optionally replace the region with the output
 (@code{shell-command-on-region}).
+@item M-& @var{cmd} @key{RET}
+Run the shell command line @var{cmd} asynchronously, and display the
+output (@code{async-shell-command}).
 @item M-x shell
 Run a subshell with input and output through an Emacs buffer.
 You can then give commands interactively.
@@ -542,6 +545,11 @@ command's exit status (0 means success), when it is called from a Lisp
 program.  You do not get any status information for an asynchronous
 command, since it hasn't finished yet when @code{shell-command} returns.
 
+  You can also type @kbd{M-&} (@code{async-shell-command}) to execute
+a shell command asynchronously.  This behaves exactly like calling
+@code{shell-command} with @samp{&}, except that you do not need to add
+the @samp{&} to the shell command line.
+
 @kindex M-|
 @findex shell-command-on-region
   @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 36848e395d2..8e88e5026e8 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2009-12-29  Chong Yidong  <cyd@stupidchicken.com>
+
+        * minibuf.texi (Completion Styles): Document `initials' style.
+
 2009-12-25  Chong Yidong  <cyd@stupidchicken.com>
 
         * frames.texi (Resources): Describe inhibit-x-resources.
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 28dc9e8ba3d..4ded2749986 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1589,13 +1589,13 @@ procedure is used for listing completions, via the
 @var{all-completions} functions.
 @end defvar
 
-  By default, @code{completion-styles-alist} contains four pre-defined
+  By default, @code{completion-styles-alist} contains five pre-defined
 completion styles: @code{basic}, a basic completion style;
 @code{partial-completion}, which does partial completion (completing
 each word in the input separately); @code{emacs22}, which performs
-completion according to the rules used in Emacs 22; and
-@code{emacs21}, which performs completion according to the rules used
-in Emacs 21.
+completion according to the rules used in Emacs 22; @code{emacs21},
+which performs completion according to the rules used in Emacs 21; and
+@code{initials}, which completes acronyms and initialisms.
 
 @node Programmed Completion
 @subsection Programmed Completion