comparison man/misc.texi @ 69737:cd14e584d88e

Many cleanups. (beginning): Add to summary of topics. (Shell): Put eshell xref at the end. Remove eshell from table. (Thumbnails): New node.

69736:5b3262d81466

  This chapter contains several brief topics that do not fit anywhere
else: reading netnews, running shell commands and shell subprocesses,
using a single shared Emacs for utilities that expect to run an editor
as a subprocess, printing hardcopy, sorting text, narrowing display to
part of the buffer, editing double-column files and binary files, saving
an Emacs session for later resumption, emulating other editors, and
various diversions and amusements.

@end iftex

@ifnottex
@raisesections

@end menu

@node Buffers of Gnus
@subsection Gnus Buffers

As opposed to most normal Emacs packages, Gnus uses a number of
different buffers to display information and to receive commands.  The
three buffers users spend most of their time in are the @dfn{group
buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.

The @dfn{group buffer} contains a list of groups.  This is the first
buffer Gnus displays when it starts up.  It normally displays only the
groups to which you subscribe and that contain unread articles.  Use
this buffer to select a specific group.

The @dfn{summary buffer} lists one line for each article in a single
group.  By default, the author, the subject and the line number are
displayed for each article, but this is customizable, like most aspects
of Gnus display.  The summary buffer is created when you select a group
in the group buffer, and is killed when you exit the group.  Use this
buffer to select an article.

The @dfn{article buffer} displays the article.  In normal Gnus usage,
you don't select this buffer---all useful article-oriented commands work
in the summary buffer.  But you can select the article buffer, and
execute all Gnus commands from that buffer, if you want to.

@node Gnus Startup
@subsection When Gnus Starts Up

At startup, Gnus reads your @file{.newsrc} news initialization file

Select articles from the summary buffer.  Each article selected is
displayed in the article buffer in a large window, below the summary
buffer in its small window.
@end enumerate

  Each Gnus buffer has its own special commands; however, the meanings
of any given key in the various Gnus buffers are usually analogous, even
if not identical.  Here are commands for the group and summary buffers:

@table @kbd
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q

  Emacs has commands for passing single command lines to inferior shell
processes; it can also run a shell interactively with input and output
to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
emulator window.

There is a shell implemented entirely in Emacs, documented in a separate
manual.  @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.

@table @kbd
@item M-! @var{cmd} @key{RET}
Run the shell command line @var{cmd} and display the output
(@code{shell-command}).

You can then give commands interactively.
@item M-x term
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
Full terminal emulation is available.
@item M-x eshell
@findex eshell
Start the Emacs shell.
@end table

@menu
* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.

  If the shell command line ends in @samp{&}, it runs asynchronously.
For a synchronous shell command, @code{shell-command} returns the
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.

@kindex M-|
@findex shell-command-on-region
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
passes the contents of the region as the standard input to the shell
command, instead of no input.  If a numeric argument is used, meaning
insert the output in the current buffer, then the old region is deleted
first and the output replaces it as the contents of the region.  It
returns the command's exit status when it is called from a Lisp program.

  One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
the buffer.  For instance, if the buffer contains a GPG key, type
@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
to the @code{gpg} program.  That program will ignore everything except
the encoded keys, and will output a list of the keys it contains.

@vindex shell-file-name
  Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
shell to use.  This variable is initialized based on your @env{SHELL}
environment variable when Emacs is started.  If the file name does not
specify a directory, the directories in the list @code{exec-path} are
searched; this list is initialized based on the environment variable
@env{PATH} when Emacs is started.  Your @file{.emacs} file can override
either or both of these default initializations.@refill

  Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
unless you end the command with @samp{&} to make it asynchronous.  To
stop waiting, type @kbd{C-g} to quit; that terminates the shell
command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
normally generates in the shell.  Emacs waits until the command
actually terminates.  If the shell command doesn't stop (because it
ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
the command a @code{SIGKILL} signal which is impossible to ignore.

  Asynchronous commands ending in @samp{&} feed their output into

  To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
@kbd{C-x @key{RET} c} immediately beforehand.  @xref{Communication Coding}.

@vindex shell-command-default-error-buffer
  Error output from the command is normally intermixed with the regular
output.  If you set the variable
@code{shell-command-default-error-buffer} to a string, which is a buffer
name, error output is inserted before point in the buffer of that name.

@node Interactive Shell
@subsection Interactive Inferior Shell

@findex shell

  To make multiple subshells, you can invoke @kbd{M-x shell} with a
prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
name and create (or reuse) a subshell in that buffer.  You can also
rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.  All the
subshells in different buffers run independently and in parallel.

@vindex explicit-shell-file-name
@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable

@var{shellname} is the name of the file that the shell was loaded
from.  For example, if you use bash, the file sent to it is
@file{~/.emacs_bash}.

  To specify a coding system for the shell, you can use the command
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can also
specify a coding system after starting the shell by using @kbd{C-x
@key{RET} p} in the shell buffer.  @xref{Communication Coding}.

@cindex @env{EMACS} environment variable
  Unless the environment variable @env{EMACS} is already defined,
Emacs defines it in the subshell, with value @code{t}.  A shell script
can check this variable to determine whether it has been run from an

@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
At end of buffer send line as input; otherwise, copy current line to
end of buffer and send it (@code{comint-send-input}).  When a line is
copied, any prompt at the beginning of the line (text output by
programs preceding your input) is omitted.  @xref{Shell Prompts}, for
how Shell mode recognizes prompts.

@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@findex comint-dynamic-complete
Complete the command name or file name before point in the shell buffer

@findex wordstar-mode
@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
key bindings.
@end table

@node Hyperlinking, Dissociated Press, Emulation, Top
@section Hyperlinking and Navigation Features

@cindex hyperlinking
@cindex navigation
  Various modes documented elsewhere have hypertext features so that

@kindex C-S-Mouse-3 @r{(FFAP)}
Display a menu of files and URLs mentioned in current buffer, then
find the one you select (@code{ffap-menu}).
@end table

@node Dissociated Press, Amusements, Hyperlinking, Top
@section Dissociated Press

@findex dissociated-press
  @kbd{M-x dissociated-press} is a command for scrambling a file of text
either word by word or character by character.  Starting from a buffer of

one run of consecutive words or characters and the start of the next.
That is, if it has just output `president' and then decides to jump
to a different point in the file, it might spot the `ent' in `pentagon'
and continue from there, producing `presidentagon'.@footnote{This
dissociword actually appeared during the Vietnam War, when it was very
appropriate.}  Long sample texts produce the best results.

@cindex againformation
  A positive argument to @kbd{M-x dissociated-press} tells it to operate
character by character, and specifies the number of overlap characters.  A
negative argument tells it to operate word by word and specifies the number
of overlap words.  In this mode, whole words are treated as the elements to
be permuted, rather than characters.  No argument is equivalent to an
argument of two.  For your againformation, the output goes only into the
buffer @samp{*Dissociation*}.  The buffer you start with is not changed.

@cindex Markov chain
@cindex ignoriginal
@cindex techniquitous
  Dissociated Press produces nearly the same results as a Markov chain
based on a frequency table constructed from the sample text.  It is,
however, an independent, ignoriginal invention.  Dissociated Press
techniquitously copies several consecutive characters from the sample
between random choices, whereas a Markov chain would choose randomly for
each word or character.  This makes for more plausible sounding results,
and runs faster.

@cindex outragedy
@cindex buggestion
@cindex properbose
@cindex mustatement
@cindex developediment
@cindex userenced
  It is a mustatement that too much use of Dissociated Press can be a
developediment to your real work.  Sometimes to the point of outragedy.
And keep dissociwords out of your documentation, if you want it to be well
userenced and properbose.  Have fun.  Your buggestions are welcome.

@node Amusements, Customization, Dissociated Press, Top
@section Other Amusements

@findex blackbox
@findex mpuz
@findex 5x5
@cindex puzzles
  @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are kinds of puzzles.
@code{blackbox} challenges you to determine the location of objects
inside a box by tomography.  @code{mpuz} displays a multiplication
puzzle with letters standing for digits in a code that you must
guess---to guess a value, type a letter and then the digit you think it
stands for.  The aim of @code{5x5} is to fill in all the squares.

69737:cd14e584d88e

  This chapter contains several brief topics that do not fit anywhere
else: reading netnews, running shell commands and shell subprocesses,
using a single shared Emacs for utilities that expect to run an editor
as a subprocess, printing hardcopy, sorting text, narrowing display to
part of the buffer, editing double-column files and binary files,
saving an Emacs session for later resumption, following hyperlinks,
browsing images, emulating other editors, and various diversions and
amusements.

@end iftex

@ifnottex
@raisesections

@end menu

@node Buffers of Gnus
@subsection Gnus Buffers

Unlike most Emacs packages, Gnus uses several buffers to display
information and to receive commands.  The three Gnus buffers users use
most are the @dfn{group buffer}, the @dfn{summary buffer} and the
@dfn{article buffer}.

The @dfn{group buffer} contains a list of newsgroups.  This is the
first buffer Gnus displays when it starts up.  It normally displays
only the groups to which you subscribe and that contain unread
articles.  Use this buffer to select a specific group.

The @dfn{summary buffer} lists one line for each article in a single
group.  By default, the author, the subject and the line number are
displayed for each article, but this is customizable, like most aspects
of Gnus display.  The summary buffer is created when you select a group
in the group buffer, and is killed when you exit the group.  Use this
buffer to select an article.

The @dfn{article buffer} displays the article.  In normal Gnus usage,
you see this buffer but you don't select it---all useful
article-oriented commands work in the summary buffer.  But you can
select the article buffer, and execute all Gnus commands from that
buffer, if you want to.

@node Gnus Startup
@subsection When Gnus Starts Up

At startup, Gnus reads your @file{.newsrc} news initialization file

Select articles from the summary buffer.  Each article selected is
displayed in the article buffer in a large window, below the summary
buffer in its small window.
@end enumerate

  Each Gnus buffer has its own special commands; the meanings of any
given key in the various Gnus buffers are usually analogous, even if
not identical.  Here are commands for the group and summary buffers:

@table @kbd
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q

  Emacs has commands for passing single command lines to inferior shell
processes; it can also run a shell interactively with input and output
to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
emulator window.

@table @kbd
@item M-! @var{cmd} @key{RET}
Run the shell command line @var{cmd} and display the output
(@code{shell-command}).

You can then give commands interactively.
@item M-x term
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
Full terminal emulation is available.
@end table

  @kbd{M-x eshell} invokes a shell implemented entirely in Emacs.  It
is documented in a separate manual.  @xref{Top,Eshell,Eshell, eshell,
Eshell: The Emacs Shell}.

@menu
* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.

  If the shell command line ends in @samp{&}, it runs asynchronously.
For a synchronous shell command, @code{shell-command} returns the
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.

@kindex M-|
@findex shell-command-on-region
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
passes the contents of the region as the standard input to the shell
command, instead of no input.  With a numeric argument, meaning insert
the output in the current buffer, it deletes the old region and the
output replaces it as the contents of the region.  It returns the
command's exit status, like @kbd{M-!}.

  One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
the buffer.  For instance, if the buffer contains a GPG key, type
@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to
the @code{gpg} program.  That program will ignore everything except
the encoded keys, and will output a list of the keys the buffer
contains.

@vindex shell-file-name
  Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify
the shell to use.  This variable is initialized based on your
@env{SHELL} environment variable when Emacs is started.  If the file
name is relative, Emacs searches the directories in the list
@code{exec-path}; this list is initialized based on the environment
variable @env{PATH} when Emacs is started.  Your @file{.emacs} file
can override either or both of these default initializations.

  Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
unless you end the command with @samp{&} to make it asynchronous.  To
stop waiting, type @kbd{C-g} to quit; that terminates the shell
command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
normally generates in the shell.  Emacs then waits until the command
actually terminates.  If the shell command doesn't stop (because it
ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
the command a @code{SIGKILL} signal which is impossible to ignore.

  Asynchronous commands ending in @samp{&} feed their output into

  To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
@kbd{C-x @key{RET} c} immediately beforehand.  @xref{Communication Coding}.

@vindex shell-command-default-error-buffer
  Error output from these commands is normally intermixed with the
regular output.  But if the variable
@code{shell-command-default-error-buffer} has a string as value, and
it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output
before point in that buffer.

@node Interactive Shell
@subsection Interactive Inferior Shell

@findex shell

  To make multiple subshells, you can invoke @kbd{M-x shell} with a
prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
name and create (or reuse) a subshell in that buffer.  You can also
rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
Subshells in different buffers run independently and in parallel.

@vindex explicit-shell-file-name
@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable

@var{shellname} is the name of the file that the shell was loaded
from.  For example, if you use bash, the file sent to it is
@file{~/.emacs_bash}.

  To specify a coding system for the shell, you can use the command
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can
also change the coding system for a running subshell by typing
@kbd{C-x @key{RET} p} in the shell buffer.  @xref{Communication
Coding}.

@cindex @env{EMACS} environment variable
  Unless the environment variable @env{EMACS} is already defined,
Emacs defines it in the subshell, with value @code{t}.  A shell script
can check this variable to determine whether it has been run from an

@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
At end of buffer send line as input; otherwise, copy current line to
end of buffer and send it (@code{comint-send-input}).  Copying a line
in this way omits any prompt at the beginning of the line (text output
by programs preceding your input).  @xref{Shell Prompts}, for how
Shell mode recognizes prompts.

@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@findex comint-dynamic-complete
Complete the command name or file name before point in the shell buffer

@findex wordstar-mode
@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
key bindings.
@end table

@node Hyperlinking, Thumbnails, Emulation, Top
@section Hyperlinking and Navigation Features

@cindex hyperlinking
@cindex navigation
  Various modes documented elsewhere have hypertext features so that

@kindex C-S-Mouse-3 @r{(FFAP)}
Display a menu of files and URLs mentioned in current buffer, then
find the one you select (@code{ffap-menu}).
@end table

@node Thumbnails, Dissociated Press, Hyperlinking, Top
@section Viewing Images as Thumbnails
@cindex tumme mode
@cindex thumbnails

  Tumme is a facility for browsing image files.  It provides viewing
of the original file, either as a thumbnail or in full size, inside
Emacs or in an external viewer.

  To enter Tumme, type @kbd{M-x tumme}.  It prompts for a directory;
specify one that has images files.  This creates thumbnails for all
the images in that directory, and displays them all in the ``thumbnail
buffer''.  This takes a long time if the directory contains many image
files, and it won't operate if the number of image files exceeds
@code{tumme-show-all-from-dir-max-files}.

@kindex C-t d @r{(Tumme)}
@findex tumme-display-thumbs
  You can also enter Tumme through Dired.  Mark the image files you
want to look at, using @kbd{m} as usual, then type @kbd{C-t d}
(@code{tumme-display-thumbs}).  This too creates and switches to
a buffer containing thumbnails, corresponding to the marked files.

  With point in the thumbnail buffer, type @kbd{RET}
(@code{tumme-display-thumbnail-original-image}) to display a sized
version of it in another window.  This sizes the image to fit the
window.  Use the arrow keys to move around in the buffer.  For easy
browing, type @kbd{SPC} (@code{tumme-display-next-thumbnail-original})
to advance and display the next image.  Typing @kbd{DEL}
(@code{tumme-display-previous-thumbnail-original}) backs up to the
previous thumbnail and displays that instead.

@vindex tumme-external-viewer
  To view and the image in its original size, either provide a prefix
argument (@kbd{C-u}) before pressing @kbd{RET}, or type @kbd{C-@key{RET}}
(@code{tumme-thumbnail-display-external}) to display the image in an
external viewer.  You must first configure
@code{tumme-external-viewer}.

  You can delete images through Tumme also.  Type @kbd{d}
(@code{tumme-flag-thumb-original-file}) to flag the image file for
deletion in the Dired buffer.  You can also delete the thumbnail image
from the thumbnail buffer with @kbd{C-d} (@code{tumme-delete-char}).

  More advanced features include @dfn{image tags}, which are metadata
used to categorize image files.  The tags are stored in a plain text
file.
@c ??? What is the file name?

  To tag image files, mark them in the dired buffer and type @kbd{C-t
t} (@code{tumme-tag-files}).  You will be prompted for a tag.  To mark
files having a certain tag, type @kbd{C-t f}
(@code{tumme-mark-tagged-files}).  After marking image files with a
certain tag, you can use @kbd{C-t d} to view them.

@c ??? Remove what?  The tag?
  You can also tag a file from the thumbnail buffer by typing @kbd{t
t} and remove it by typing @kbd{t r}.  There is also a special ``tag''
called ``comment'' for each file (it is not a tag in the exact same
sense as the other tags, it is handled slightly different).  That is
used to enter a comment or description about the image.  You comment a
file from the thumbnail buffer by typing @kbd{c}.  You will be
prompted for a comment.  Type @kbd{C-t c} to add a comment from Dired
(@code{tumme-dired-comment-files}).

  Tumme also provides simple image manipulation.  In the thumbnail
buffer, type @kbd{L} to rotate the original image 90 degrees anti
clockwise, and @kbd{R} to rotate it 90 degrees clockwise.  This
rotation is lossless, and uses an external utility called JpegTRAN.

@node Dissociated Press, Amusements, Thumbnails, Top
@section Dissociated Press

@findex dissociated-press
  @kbd{M-x dissociated-press} is a command for scrambling a file of text
either word by word or character by character.  Starting from a buffer of

one run of consecutive words or characters and the start of the next.
That is, if it has just output `president' and then decides to jump
to a different point in the file, it might spot the `ent' in `pentagon'
and continue from there, producing `presidentagon'.@footnote{This
dissociword actually appeared during the Vietnam War, when it was very
appropriate.  Bush has made it appropriate again.}  Long sample texts
produce the best results.

@cindex againformation
  A positive argument to @kbd{M-x dissociated-press} tells it to operate
character by character, and specifies the number of overlap characters.  A
negative argument tells it to operate word by word, and specifies the number
of overlap words.  In this mode, whole words are treated as the elements to
be permuted, rather than characters.  No argument is equivalent to an
argument of two.  For your againformation, the output goes only into the
buffer @samp{*Dissociation*}.  The buffer you start with is not changed.

@cindex Markov chain
@cindex ignoriginal
@cindex techniquitous
  Dissociated Press produces results fairly like those of a Markov
chain based on a frequency table constructed from the sample text.  It
is, however, an independent, ignoriginal invention.  Dissociated Press
techniquitously copies several consecutive characters from the sample
between random choices, whereas a Markov chain would choose randomly
for each word or character.  This makes for more plausible sounding
results, and runs faster.

@cindex outragedy
@cindex buggestion
@cindex properbose
@cindex mustatement
@cindex developediment
@cindex userenced
  It is a mustatement that too much use of Dissociated Press can be a
developediment to your real work, sometimes to the point of outragedy.
And keep dissociwords out of your documentation, if you want it to be well
userenced and properbose.  Have fun.  Your buggestions are welcome.

@node Amusements, Customization, Dissociated Press, Top
@section Other Amusements

@findex blackbox
@findex mpuz
@findex 5x5
@cindex puzzles
  @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles.
@code{blackbox} challenges you to determine the location of objects
inside a box by tomography.  @code{mpuz} displays a multiplication
puzzle with letters standing for digits in a code that you must
guess---to guess a value, type a letter and then the digit you think it
stands for.  The aim of @code{5x5} is to fill in all the squares.