Skip to content

GitLab

Commit 26e533e2 authored by Chong Yidong's avatar Chong Yidong
Browse files
Options

* 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.
parent 659e4408
Hide whitespace changes
Inline Side-by-side
Showing with 265 additions and 81 deletions
doc/emacs/ChangeLog
View file @ 26e533e2
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.
......
doc/emacs/building.texi
View file @ 26e533e2
......@@ -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
......
doc/emacs/mini.texi
View file @ 26e533e2
......@@ -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
......
doc/emacs/misc.texi
View file @ 26e533e2
......@@ -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
......
doc/lispref/ChangeLog
View file @ 26e533e2
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.
......
doc/lispref/minibuf.texi
View file @ 26e533e2
......@@ -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
......
etc/NEWS
View file @ 26e533e2
......@@ -26,27 +26,27 @@ so we will look at it and add it to the manual.
** New configure options for Emacs developers
These are not new features; only the configure flags are new.
---
*** --enable-profiling builds Emacs with profiling enabled.
This might not work on all platforms.
---
*** --enable-checking[=OPTIONS] builds emacs with extra runtime checks.
---
** `make install' now consistently ignores umask, creating a
world-readable install.
** Emacs compiles with Gconf support by default, if it is detected.
** Emacs compiles with Gconf support, if it is detected.
Use the configure option --without-gconf to disable this.
* Startup Changes in Emacs 23.2
+++
** The command-line option -Q (--quick) also inhibits loading X resources.
However, if Emacs is compiled with the Lucid or Motif toolkit, X
resource settings for the graphical widgets are still applied.
On Windows, the -Q option causes Emacs to ignore Registry settings,
but environment variables set on the Registry are still honored.
+++
*** The new variable `inhibit-x-resources' shows whether X resources
were loaded.
......@@ -55,9 +55,11 @@ were loaded.
* Changes in Emacs 23.2
+++
** The maximum size of buffers (and the largest fixnum) is doubled.
On typical 32bit systems, buffers can now be up to 512MB.
---
** The default value of `trash-directory' is now nil.
This means that `move-file-to-trash' trashes files according to
freedesktop.org specifications, the same method used by the Gnome,
......@@ -80,13 +82,14 @@ disable this with the configure option --without-gconf).
via the XSETTINGS mechanism. This includes antialias, hinting,
hintstyle, RGBA, DPI and lcdfilter changes.
+++
** Killing a buffer with a running process now asks for confirmation.
To remove this query, remove `process-kill-buffer-query-function' from
`kill-buffer-query-functions', or set the appropriate process flag
with `set-process-query-on-exit-flag'.
** File-local variable changes
+++
*** Specifying a minor mode as a local variables enables that mode,
unconditionally. The previous behavior, toggling the mode, was
neither reliable nor generally desirable.
......@@ -104,17 +107,18 @@ and copying them to and from file-local variable lists:
`copy-file-locals-to-dir-locals'.
** Internationalization changes
+++
*** Unibyte sessions are now considered obsolete.
This refers to the EMACS_UNIBYTE environment variable as well as the
--unibyte, --multibyte, --no-multibyte, and --no-unibyte command line
arguments. Customizing enable-multibyte-characters and setting
default-enable-multibyte-characters are also deprecated.
---
*** New coding system `utf-8-hfs'.
This is suitable for default-file-name-coding-system on Mac OS X; see
international/ucs-normalize.el.
---
** Function arguments in *Help* buffers are now shown in upper-case.
Customize `help-downcase-arguments' to t to show them in lower-case.
......@@ -127,11 +131,11 @@ Customize `help-downcase-arguments' to t to show them in lower-case.
becomes the primary selection (for interaction with other window
applications). If you enable this, you might want to bind
`mouse-yank-primary' to Mouse-2.
+++
*** When `save-interprogram-paste-before-kill' is non-nil, the kill
commands save the interprogram-paste selection into the kill ring
before doing anything else. This avoids losing the selection.
+++
*** When `kill-do-not-save-duplicates' is non-nil, identical
subsequent kills are not duplicated in the `kill-ring'.
......@@ -140,7 +144,7 @@ subsequent kills are not duplicated in the `kill-ring'.
*** The new command `completion-at-point' provides mode-sensitive completion.
*** tab-always-indent set to `complete' lets TAB do completion as well.
+++
*** The new completion-style `initials' is available.
For instance, this can complete M-x lch to list-command-history.
......@@ -151,6 +155,7 @@ are displayed in the *Completions* buffer. If you set it to
+++
** The default value of `blink-matching-paren-distance' is increased.
---
** M-n provides more default values in the minibuffer for commands
that read file names. These include the file name at point (when ffap
is loaded without ffap-bindings), the file name on the current line
......@@ -158,14 +163,20 @@ is loaded without ffap-bindings), the file name on the current line
(for Dired commands that operate on several directories, such as copy,
rename, or diff).
+++
** M-r is bound to the new `move-to-window-line-top-bottom'.
This moves point to the window center, top and bottom on successive
invocations, in the same spirit as the C-l (recenter-top-bottom)
command.
+++
** The new variable `recenter-positions' determines the default
cycling order of C-l (`recenter-top-bottom').
+++
** The abbrevs file is now a file named abbrev_defs in
user-emacs-directory; but the old location, ~/.abbrev_defs, is used if
that file exists.
* Changes in Specialized Modes and Packages in Emacs 23.2
......@@ -180,11 +191,15 @@ cycling order of C-l (`recenter-top-bottom').
** pcomplete provides a new command `pcomplete-std-completion' which
is similar to `pcomplete' but using the standard completion UI code.
** .calc.el and .abbrev_defs obey user-emacs-directory.
** Calc
+++
*** The Calc settings file is now a file named calc.el in
user-emacs-directory; but the old location, ~/.calc.el, is used if
that file exists.
** Calc graphing commands (`g f' etc.) now work on MS-Windows,
if you have the native Windows port of Gnuplot version 3.8 or later
installed.
---
*** Graphing commands (`g f' etc.) now work on MS-Windows, if you have
the native Windows port of Gnuplot version 3.8 or later installed.
** Calendar and diary
......@@ -224,8 +239,8 @@ on the page edge advances to the next/previous page.
watch expressions. These features require GDB 7.0 or later.
** Grep
A new command `zrgrep' searches recursively in gzipped files.
+++
*** A new command `zrgrep' searches recursively in gzipped files.
** Info
......@@ -366,6 +381,7 @@ and let commands run under that user permissions. It works even when
`default-directory' is already remote. Calling the external commands
is possible by `*su' or `*sudo', repectively.
---
*** When running in a new enough xterm (newer than version 242), emacs
asks xterm what the background color is and it sets up faces
accordingly for a dark background if needed (the current default is to
......@@ -442,8 +458,10 @@ mode from `auto-mode-alist' (or Fundamental mode) and `image-minor-mode'.
** New function `completion-in-region' to use the standard completion
facilities on a particular region of text.
+++
** The 4th arg to all-completions (aka hide-spaces) is declared obsolete.
---
** read-file-name-predicate is obsolete. It was used to pass the predicate
to read-file-name-internal because read-file-name-internal abused its `pred'
argument to pass the current directory, but this hack is not needed
......@@ -451,6 +469,7 @@ any more.
** Frame parameter changes
+++
*** You can give the `fullscreen' frame parameter the value `maximized'.
This maximizes the frame.
......@@ -458,6 +477,7 @@ This maximizes the frame.
*** The new frame parameter `sticky' makes Emacs frames sticky in
virtual desktops.
---
** completion-base-size is obsoleted by completion-base-position.
This change causes a few backward incompatibilities, mostly with
choose-completion-string-functions where the `mini-p' argument has
......@@ -491,11 +511,12 @@ now only take a single `command' argument.
a `process-file' call does not change a remote file. By this, file
name handlers like Tramp can apply optimizations.
+++
** Hash tables have a new printed representation that is readable.
The feature `hashtable-print-readable' identifies this new
functionality.
** Functions performing Unicode normalization are added. They are:
** New functions performing Unicode normalization are added:
ucs-normalize-NFD-region, ucs-normalize-NFD-string,
ucs-normalize-NFC-region, ucs-normalize-NFC-string,
ucs-normalize-NFKD-region, ucs-normalize-NFKD-string,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment