3306 lines
137 KiB
Plaintext
3306 lines
137 KiB
Plaintext
@c This is part of the Emacs manual.
|
||
@c Copyright (C) 1985--2024 Free Software Foundation, Inc.
|
||
@c See file emacs.texi for copying conditions.
|
||
@iftex
|
||
@chapter Miscellaneous Commands
|
||
|
||
This chapter contains several brief topics that do not fit anywhere
|
||
else: reading Usenet news, host and network security,
|
||
viewing PDFs and other such documents, web
|
||
browsing, running shell commands and shell subprocesses, using a
|
||
single shared Emacs for utilities that expect to run an editor as a
|
||
subprocess, printing, sorting text, editing binary files, saving an
|
||
Emacs session for later resumption, recursive editing level, following
|
||
hyperlinks, and various diversions and amusements.
|
||
|
||
@end iftex
|
||
|
||
@ifnottex
|
||
@raisesections
|
||
@end ifnottex
|
||
|
||
@node Gnus
|
||
@section Email and Usenet News with Gnus
|
||
@cindex Gnus
|
||
@cindex Usenet news
|
||
@cindex newsreader
|
||
|
||
Gnus is an Emacs package primarily designed for reading and posting
|
||
Usenet news. It can also be used to read and respond to messages from
|
||
a number of other sources---email, remote directories, digests, and so
|
||
on. Here we introduce Gnus and describe several basic features.
|
||
@ifnottex
|
||
For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
|
||
@end ifnottex
|
||
@iftex
|
||
For full details on Gnus, type @kbd{C-h i} and then select the Gnus
|
||
manual.
|
||
@end iftex
|
||
|
||
@menu
|
||
* Buffers of Gnus:: The group, summary, and article buffers.
|
||
* Gnus Startup:: What you should know about starting Gnus.
|
||
* Gnus Group Buffer:: A short description of Gnus group commands.
|
||
* Gnus Summary Buffer:: A short description of Gnus summary commands.
|
||
@end menu
|
||
|
||
@node Buffers of Gnus
|
||
@subsection Gnus Buffers
|
||
|
||
Gnus uses several buffers to display information and to receive
|
||
commands. The three most commonly-used Gnus buffers are the
|
||
@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article
|
||
buffer}.
|
||
|
||
The @dfn{group buffer} contains a list of article sources (e.g.,
|
||
newsgroups and email inboxes), which are collectively referred to as
|
||
@dfn{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. From this buffer, you can select a
|
||
group to read.
|
||
|
||
The @dfn{summary buffer} lists the articles in a single group,
|
||
showing one article per line. By default, it displays each article's
|
||
author, subject, and line
|
||
@iftex
|
||
number.
|
||
@end iftex
|
||
@ifnottex
|
||
number, but this is customizable; @xref{Summary Buffer Format,,, gnus,
|
||
The Gnus Manual}.
|
||
@end ifnottex
|
||
The summary buffer is created when you select a group in the group
|
||
buffer, and is killed when you exit the group.
|
||
|
||
From the summary buffer, you can choose an article to view. The
|
||
article is displayed in the @dfn{article buffer}. In normal Gnus
|
||
usage, you view this buffer but do not select it---all useful Gnus
|
||
commands can be invoked from the summary buffer. But you can select
|
||
the article buffer, and execute Gnus commands from it, if you wish.
|
||
|
||
@node Gnus Startup
|
||
@subsection When Gnus Starts Up
|
||
|
||
@findex gnus
|
||
@cindex @file{.newsrc} file
|
||
If your system has been set up for reading Usenet news, getting
|
||
started with Gnus is easy---just type @kbd{M-x gnus}.
|
||
|
||
On starting up, Gnus reads your @dfn{news initialization file}: a
|
||
file named @file{.newsrc} in your home directory which lists your
|
||
Usenet newsgroups and subscriptions (this file is not unique to Gnus;
|
||
it is used by many other newsreader programs). It then tries to
|
||
contact the system's default news server, which is typically specified
|
||
by the @env{NNTPSERVER} environment variable.
|
||
|
||
If your system does not have a default news server, or if you wish
|
||
to use Gnus for reading email, then before invoking @kbd{M-x gnus} you
|
||
need to tell Gnus where to get news and/or mail. To do this,
|
||
customize the variables @code{gnus-select-method} and/or
|
||
@code{gnus-secondary-select-methods}.
|
||
@iftex
|
||
See the Gnus manual for details.
|
||
@end iftex
|
||
@ifnottex
|
||
@xref{Finding the News,,, gnus, The Gnus Manual}.
|
||
@end ifnottex
|
||
|
||
Once Gnus has started up, it displays the group buffer. By default,
|
||
the group buffer shows only a small number of @dfn{subscribed groups}.
|
||
Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or
|
||
@dfn{zombie}---are hidden. The first time you start Gnus, any group
|
||
to which you are not subscribed is made into a killed group; any group
|
||
that subsequently appears on the news server becomes a zombie group.
|
||
|
||
To proceed, you must select a group in the group buffer to open the
|
||
summary buffer for that group; then, select an article in the summary
|
||
buffer to view its article buffer in a separate window. The following
|
||
sections explain how to use the group and summary buffers to do this.
|
||
|
||
To quit Gnus, type @kbd{q} in the group buffer. This automatically
|
||
records your group statuses in the files @file{.newsrc} and
|
||
@file{.newsrc.eld}, so that they take effect in subsequent Gnus
|
||
sessions.
|
||
|
||
@node Gnus Group Buffer
|
||
@subsection Using the Gnus Group Buffer
|
||
|
||
The following commands are available in the Gnus group buffer:
|
||
|
||
@table @kbd
|
||
@kindex SPC @r{(Gnus Group mode)}
|
||
@findex gnus-group-read-group
|
||
@item @key{SPC}
|
||
Switch to the summary buffer for the group on the current line
|
||
(@code{gnus-group-read-group}).
|
||
|
||
@kindex l @r{(Gnus Group mode)}
|
||
@kindex A s @r{(Gnus Group mode)}
|
||
@findex gnus-group-list-groups
|
||
@item l
|
||
@itemx A s
|
||
In the group buffer, list only the groups to which you subscribe and
|
||
which contain unread articles (@code{gnus-group-list-groups}; this is
|
||
the default listing).
|
||
|
||
@kindex L @r{(Gnus Group mode)}
|
||
@kindex A u @r{(Gnus Group mode)}
|
||
@findex gnus-group-list-all-groups
|
||
@item L
|
||
@itemx A u
|
||
List all subscribed and unsubscribed groups, but not killed or zombie
|
||
groups (@code{gnus-group-list-all-groups}).
|
||
|
||
@kindex A k @r{(Gnus Group mode)}
|
||
@findex gnus-group-list-killed
|
||
@item A k
|
||
List killed groups (@code{gnus-group-list-killed}).
|
||
|
||
@kindex A z @r{(Gnus Group mode)}
|
||
@findex gnus-group-list-zombies
|
||
@item A z
|
||
List zombie groups (@code{gnus-group-list-zombies}).
|
||
|
||
@kindex u @r{(Gnus Group mode)}
|
||
@findex gnus-group-toggle-subscription-at-point
|
||
@cindex subscribe groups
|
||
@cindex unsubscribe groups
|
||
@item u
|
||
Toggle the subscription status of the group
|
||
(@code{gnus-group-toggle-subscription-at-point}) on the current line.
|
||
Invoking this on a killed or zombie group turns it into an
|
||
unsubscribed group.
|
||
|
||
@kindex C-k @r{(Gnus Group mode)}
|
||
@findex gnus-group-kill-group
|
||
@item C-k
|
||
Kill the group on the current line (@code{gnus-group-kill-group}).
|
||
Killed groups are not recorded in the @file{.newsrc} file, and they
|
||
are not shown in the @kbd{l} or @kbd{L} listings.
|
||
|
||
@kindex DEL @r{(Gnus Group mode)}
|
||
@item @key{DEL}
|
||
Move point to the previous group containing unread articles
|
||
(@code{gnus-group-prev-unread-group}).
|
||
|
||
@kindex n @r{(Gnus Group mode)}
|
||
@findex gnus-group-next-unread-group
|
||
@item n
|
||
Move point to the next unread group
|
||
(@code{gnus-group-next-unread-group}).
|
||
|
||
@kindex p @r{(Gnus Group mode)}
|
||
@findex gnus-group-prev-unread-group
|
||
@item p
|
||
Move point to the previous unread group
|
||
(@code{gnus-group-prev-unread-group}).
|
||
|
||
@kindex q @r{(Gnus Group mode)}
|
||
@findex gnus-group-exit
|
||
@item q
|
||
Update your Gnus settings, and quit Gnus (@code{gnus-group-exit}).
|
||
@end table
|
||
|
||
@node Gnus Summary Buffer
|
||
@subsection Using the Gnus Summary Buffer
|
||
|
||
The following commands are available in the Gnus summary buffer:
|
||
|
||
@table @kbd
|
||
@kindex SPC @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-next-page
|
||
@item @key{SPC}
|
||
If there is no article selected, select the article on the current
|
||
line and display its article buffer. Otherwise, try scrolling the
|
||
selected article buffer in its window; on reaching the end of the
|
||
buffer, select the next unread article (@code{gnus-summary-next-page}).
|
||
|
||
Thus, you can read through all articles by repeatedly typing
|
||
@key{SPC}.
|
||
|
||
@kindex DEL @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-prev-page
|
||
@item @key{DEL}
|
||
Scroll the text of the article backwards
|
||
(@code{gnus-summary-prev-page}).
|
||
|
||
@kindex n @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-next-unread-article
|
||
@item n
|
||
Select the next unread article
|
||
(@code{gnus-summary-next-unread-article}).
|
||
|
||
@kindex p @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-prev-unread-article
|
||
@item p
|
||
Select the previous unread article
|
||
(@code{gnus-summary-prev-unread-article}).
|
||
|
||
@kindex s @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-isearch-article
|
||
@item s
|
||
Do an incremental search on the selected article buffer
|
||
(@code{gnus-summary-isearch-article}), as if you switched to the
|
||
buffer and typed @kbd{C-s} (@pxref{Incremental Search}).
|
||
|
||
@kindex M-s M-s @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-search-article-forward
|
||
@item M-s M-s @var{regexp} @key{RET}
|
||
Search forward for articles containing a match for @var{regexp}
|
||
(@code{gnus-summary-search-article-forward}).
|
||
|
||
@kindex M-s M-r @r{(Gnus Summary mode)}
|
||
@findex gnus-summary-search-article-backward
|
||
@item M-r @var{regexp} @key{RET}
|
||
Search back for articles containing a match for @var{regexp}
|
||
(@code{gnus-summary-search-article-backward}).
|
||
|
||
@kindex q @r{(Gnus Summary mode)}
|
||
@item q
|
||
Exit the summary buffer and return to the group buffer
|
||
(@code{gnus-summary-exit}).
|
||
@end table
|
||
|
||
@node Host Security
|
||
@section Host Security
|
||
@cindex security
|
||
|
||
Emacs runs inside an operating system such as GNU/Linux, and relies on
|
||
the operating system to check security constraints such as accesses to
|
||
files. The default settings for Emacs are designed for typical use;
|
||
they may require some tailoring in environments where security is more
|
||
of a concern, or less of a concern, than usual. For example,
|
||
file-local variables can be risky, and you can set the variable
|
||
@code{enable-local-variables} to @code{:safe} or (even more
|
||
conservatively) to @code{nil}; conversely, if your files can all be
|
||
trusted and the default checking for these variables is irritating,
|
||
you can set @code{enable-local-variables} to @code{:all}. @xref{Safe
|
||
File Variables}.
|
||
|
||
@xref{Security Considerations,,, elisp, The Emacs Lisp Reference
|
||
Manual}, for more information about security considerations when using
|
||
Emacs as part of a larger application.
|
||
|
||
@node Network Security
|
||
@section Network Security
|
||
@cindex network security manager
|
||
@cindex NSM
|
||
@cindex encryption
|
||
@cindex SSL
|
||
@cindex TLS
|
||
@cindex Transport Layer Security
|
||
@cindex STARTTLS
|
||
|
||
Whenever Emacs establishes any network connection, it passes the
|
||
established connection to the @dfn{Network Security Manager}
|
||
(@acronym{NSM}). @acronym{NSM} is responsible for enforcing the
|
||
network security under your control. Currently, this works by using
|
||
the Transport Layer Security (@acronym{TLS}) features.
|
||
|
||
@vindex network-security-level
|
||
The @code{network-security-level} variable determines the security
|
||
level that @acronym{NSM} enforces. If its value is @code{low}, no
|
||
security checks are performed. This is not recommended, and will
|
||
basically mean that your network connections can't be trusted.
|
||
However, the setting can be useful in limited circumstances, as when
|
||
testing network issues.
|
||
|
||
If this variable is @code{medium} (which is the default), a number of
|
||
checks will be performed. If as result @acronym{NSM} determines that
|
||
the network connection might not be trustworthy, it will make you
|
||
aware of that, and will ask you what to do about the network
|
||
connection.
|
||
|
||
You can decide to register a permanent security exception for an
|
||
unverified connection, a temporary exception, or refuse the connection
|
||
entirely.
|
||
|
||
@vindex network-security-protocol-checks
|
||
In addition to the basic certificate correctness checks, several
|
||
@acronym{TLS} algorithm checks are available. Some encryption
|
||
technologies that were previously thought to be secure have shown
|
||
themselves to be fragile, so Emacs (by default) warns you about some
|
||
of these problems.
|
||
|
||
The protocol network checks is controlled via the
|
||
@code{network-security-protocol-checks} variable.
|
||
|
||
It's an alist where the first element of each association is the name
|
||
of the check, and the second element is the security level where the
|
||
check should be used.
|
||
|
||
An element like @code{(rc4 medium)} will result in the function
|
||
@code{nsm-protocol-check--rc4} being called like thus:
|
||
@w{@code{(nsm-protocol-check--rc4 host port status settings)}}.
|
||
The function should return non-@code{nil} if the connection should
|
||
proceed and @code{nil} otherwise.
|
||
|
||
Below is a list of the checks done on the default @code{medium} level.
|
||
|
||
@table @asis
|
||
|
||
@item unable to verify a @acronym{TLS} certificate
|
||
If the connection is a @acronym{TLS}, @acronym{SSL} or
|
||
@acronym{STARTTLS} connection, @acronym{NSM} will check whether
|
||
the certificate used to establish the identity of the server we're
|
||
connecting to can be verified.
|
||
|
||
While an invalid certificate is often the cause for concern (there
|
||
could be a Man-in-the-Middle hijacking your network connection and
|
||
stealing your password), there may be valid reasons for going ahead
|
||
with the connection anyway. For instance, the server may be using a
|
||
self-signed certificate, or the certificate may have expired. It's up
|
||
to you to determine whether it's acceptable to continue with the
|
||
connection.
|
||
|
||
@item a self-signed certificate has changed
|
||
If you've previously accepted a self-signed certificate, but it has
|
||
now changed, that could mean that the server has just changed the
|
||
certificate, but it might also mean that the network connection has
|
||
been hijacked.
|
||
|
||
@item previously encrypted connection now unencrypted
|
||
If the connection is unencrypted, but it was encrypted in previous
|
||
sessions, this might mean that there is a proxy between you and the
|
||
server that strips away @acronym{STARTTLS} announcements, leaving the
|
||
connection unencrypted. This is usually very suspicious.
|
||
|
||
@item talking to an unencrypted service when sending a password
|
||
When connecting to an @acronym{IMAP} or @acronym{POP3} server, these
|
||
should usually be encrypted, because it's common to send passwords
|
||
over these connections. Similarly, if you're sending email via
|
||
@acronym{SMTP} that requires a password, you usually want that
|
||
connection to be encrypted. If the connection isn't encrypted,
|
||
@acronym{NSM} will warn you.
|
||
|
||
@item Diffie-Hellman low prime bits
|
||
When doing the public key exchange, the number of prime bits should be
|
||
high enough to ensure that the channel can't be eavesdropped on by third
|
||
parties. If this number is too low, Emacs will warn you. (This is the
|
||
@code{diffie-hellman-prime-bits} check in
|
||
@code{network-security-protocol-checks}).
|
||
|
||
@item @acronym{RC4} stream cipher
|
||
The @acronym{RC4} stream cipher is believed to be of low quality and
|
||
may allow eavesdropping by third parties. (This is the @code{rc4}
|
||
check in @code{network-security-protocol-checks}).
|
||
|
||
@item @acronym{SHA1} in the host certificate or in intermediate certificates
|
||
It is believed that if an intermediate certificate uses the
|
||
@acronym{SHA1} hashing algorithm, then third parties can issue
|
||
certificates pretending to be that issuing instance. These
|
||
connections are therefore vulnerable to man-in-the-middle attacks.
|
||
(These are the @code{signature-sha1} and @code{intermediate-sha1}
|
||
checks in @code{network-security-protocol-checks}).
|
||
|
||
@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3}
|
||
The protocols older than @acronym{TLS1.0} are believed to be
|
||
vulnerable to a variety of attacks, and you may want to avoid using
|
||
these if what you're doing requires higher security. (This is the
|
||
@code{ssl} check in @code{network-security-protocol-checks}).
|
||
|
||
@item Triple DES (or @acronym{3DES}) cipher
|
||
The @acronym{3DES} stream cipher provides at most 112 bits of
|
||
effective security, and a major security vulnerability in it was
|
||
disclosed in 2016 (CVE-2016-2183). It has been deprecated by NIST in
|
||
all applications from late 2023 onwards. (This is the
|
||
@code{3des-cipher} check in @code{network-security-protocol-checks}).
|
||
@end table
|
||
|
||
If @code{network-security-level} is @code{high}, the following checks
|
||
will be made, in addition to the above:
|
||
|
||
@table @asis
|
||
@item a validated certificate changes the public key
|
||
Servers change their keys occasionally, and that is normally nothing
|
||
to be concerned about. However, if you are worried that your network
|
||
connections are being hijacked by agencies who have access to pliable
|
||
Certificate Authorities which issue new certificates for third-party
|
||
services, you may want to keep track of these changes.
|
||
|
||
@end table
|
||
|
||
Finally, if @code{network-security-level} is @code{paranoid}, you will
|
||
also be notified the first time @acronym{NSM} sees any new
|
||
certificate. This will allow you to inspect all the certificates from
|
||
all the connections that Emacs makes.
|
||
|
||
The following additional variables can be used to control details of
|
||
@acronym{NSM} operation:
|
||
|
||
@table @code
|
||
@item nsm-settings-file
|
||
@vindex nsm-settings-file
|
||
This is the file where @acronym{NSM} stores details about connections.
|
||
It defaults to @file{~/.emacs.d/network-security.data}.
|
||
|
||
@item nsm-save-host-names
|
||
@vindex nsm-save-host-names
|
||
By default, host names will not be saved for non-@code{STARTTLS}
|
||
connections. Instead a host/port hash is used to identify connections.
|
||
This means that one can't casually read the settings file to see what
|
||
servers the user has connected to. If this variable is @code{t},
|
||
@acronym{NSM} will also save host names in the
|
||
@code{nsm-settings-file}.
|
||
|
||
@end table
|
||
|
||
|
||
@node Document View
|
||
@section Document Viewing
|
||
@cindex DVI file
|
||
@cindex PDF file
|
||
@cindex PS file
|
||
@cindex PostScript file
|
||
@cindex OpenDocument file
|
||
@cindex Microsoft Office file
|
||
@cindex EPUB file
|
||
@cindex CBZ file
|
||
@cindex FB2 file
|
||
@cindex XPS file
|
||
@cindex OXPS file
|
||
@cindex DocView mode
|
||
@cindex mode, DocView
|
||
@cindex document viewer (DocView)
|
||
@findex doc-view-mode
|
||
|
||
DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
|
||
OpenDocument, Microsoft Office, EPUB, CBZ, FB2, XPS and OXPS
|
||
documents. It provides features such as slicing, zooming, and
|
||
searching inside documents. It works by converting the document to a
|
||
set of images using the @command{gs} (GhostScript) or
|
||
@command{pdfdraw}/@command{mutool draw} (MuPDF) commands and other
|
||
external tools, and then displays those converted images.
|
||
|
||
@findex doc-view-toggle-display
|
||
@findex doc-view-minor-mode
|
||
When you visit a document file that can be displayed with DocView
|
||
mode, Emacs automatically uses that mode @footnote{The needed
|
||
external tools for the document type must be available, and Emacs must
|
||
be running in a graphical frame and have PNG image support. If these
|
||
requirements is not fulfilled, Emacs falls back to another major
|
||
mode.}. As an exception, when you visit a PostScript file, Emacs
|
||
switches to PS mode, a major mode for editing PostScript files as
|
||
text; however, it also enables DocView minor mode, so you can type
|
||
@kbd{C-c C-c} to view the document with DocView. In either DocView
|
||
mode or DocView minor mode, repeating @kbd{C-c C-c}
|
||
(@code{doc-view-toggle-display}) toggles between DocView and the
|
||
underlying file contents.
|
||
|
||
@findex doc-view-open-text
|
||
When you visit a file which would normally be handled by DocView
|
||
mode but some requirement is not met (e.g., you operate in a terminal
|
||
frame or Emacs has no PNG support), you are queried if you want to
|
||
view the document's contents as plain text. If you confirm, the
|
||
buffer is put in text mode and DocView minor mode is activated. Thus,
|
||
by typing @kbd{C-c C-c} you switch to the fallback mode. With another
|
||
@kbd{C-c C-c} you return to DocView mode. The plain text contents can
|
||
also be displayed from within DocView mode by typing @kbd{C-c C-t}
|
||
(@code{doc-view-open-text}).
|
||
|
||
You can explicitly enable DocView mode with the command @kbd{M-x
|
||
doc-view-mode}. You can toggle DocView minor mode with @kbd{M-x
|
||
doc-view-minor-mode}.
|
||
|
||
When DocView mode starts, it displays a welcome screen and begins
|
||
formatting the file, page by page. It displays the first page once
|
||
that has been formatted.
|
||
|
||
To kill the DocView buffer, type @kbd{k}
|
||
(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q}
|
||
(@code{quit-window}).
|
||
|
||
@menu
|
||
* Navigation: DocView Navigation. Navigating DocView buffers.
|
||
* Searching: DocView Searching. Searching inside documents.
|
||
* Slicing: DocView Slicing. Specifying which part of a page is displayed.
|
||
* Conversion: DocView Conversion. Influencing and triggering conversion.
|
||
@end menu
|
||
|
||
@node DocView Navigation
|
||
@subsection DocView Navigation
|
||
|
||
In DocView mode, you can scroll the current page using the usual
|
||
Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
|
||
the arrow keys.
|
||
|
||
@vindex doc-view-continuous
|
||
By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
|
||
scrolling at the beginning and end of the current page, respectively.
|
||
However, if you change the variable @code{doc-view-continuous} to a
|
||
non-@code{nil} value, then @kbd{C-p} displays the previous page if you
|
||
are already at the beginning of the current page, and @kbd{C-n}
|
||
displays the next page if you are at the end of the current page.
|
||
|
||
@findex doc-view-next-page
|
||
@findex doc-view-previous-page
|
||
@kindex n @r{(DocView mode)}
|
||
@kindex p @r{(DocView mode)}
|
||
@kindex PageDown @r{(DocView mode)}
|
||
@kindex PageUp @r{(DocView mode)}
|
||
@kindex next @r{(DocView mode)}
|
||
@kindex prior @r{(DocView mode)}
|
||
@kindex C-x ] @r{(DocView mode)}
|
||
@kindex C-x [ @r{(DocView mode)}
|
||
You can also display the next page by typing @kbd{n},
|
||
@key{PageDown}, @key{next} or @kbd{C-x ]} (@code{doc-view-next-page}).
|
||
To display the previous page, type @kbd{p}, @key{PageUp}, @key{prior}
|
||
or @kbd{C-x [} (@code{doc-view-previous-page}).
|
||
|
||
@findex doc-view-scroll-up-or-next-page
|
||
@findex doc-view-scroll-down-or-previous-page
|
||
@kindex SPC @r{(DocView mode)}
|
||
@kindex DEL @r{(DocView mode)}
|
||
@key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient
|
||
way to advance through the document. It scrolls within the current
|
||
page or advances to the next. @key{DEL} moves backwards in a similar
|
||
way (@code{doc-view-scroll-down-or-previous-page}).
|
||
|
||
@findex doc-view-first-page
|
||
@findex doc-view-last-page
|
||
@findex doc-view-goto-page
|
||
@kindex M-< @r{(DocView mode)}
|
||
@kindex M-> @r{(DocView mode)}
|
||
To go to the first page, type @kbd{M-<}
|
||
(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
|
||
(@code{doc-view-last-page}). To jump to a page by its number, type
|
||
@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
|
||
|
||
@findex doc-view-enlarge
|
||
@findex doc-view-shrink
|
||
@vindex doc-view-resolution
|
||
@vindex doc-view-scale-internally
|
||
@kindex + @r{(DocView mode)}
|
||
@kindex - @r{(DocView mode)}
|
||
You can enlarge or shrink the document with @kbd{+}
|
||
(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). By
|
||
default, these commands just rescale the already-rendered image. If
|
||
you instead want the image to be re-rendered at the new size, set
|
||
@code{doc-view-scale-internally} to @code{nil}. To specify the
|
||
default size for DocView, customize the variable
|
||
@code{doc-view-resolution}.
|
||
|
||
@vindex doc-view-imenu-enabled
|
||
@vindex doc-view-imenu-flatten
|
||
@vindex doc-view-imenu-format
|
||
When the @command{mutool} program is available, DocView will use it
|
||
to generate entries for an outline menu, making it accessible via the
|
||
@code{imenu} facility (@pxref{Imenu}). To disable this functionality
|
||
even when @command{mutool} can be found on your system, customize the
|
||
variable @code{doc-view-imenu-enabled} to the @code{nil} value. You
|
||
can further customize how @code{imenu} items are formatted and
|
||
displayed using the variables @code{doc-view-imenu-format} and
|
||
@code{doc-view-imenu-flatten}.
|
||
|
||
@node DocView Searching
|
||
@subsection DocView Searching
|
||
|
||
In DocView mode, you can search the file's text for a regular
|
||
expression (@pxref{Regexps}). The interface for searching is inspired
|
||
by @code{isearch} (@pxref{Incremental Search}).
|
||
|
||
@findex doc-view-search
|
||
@findex doc-view-search-backward
|
||
@findex doc-view-show-tooltip
|
||
To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
|
||
@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular
|
||
expression using a minibuffer, then echoes the number of matches found
|
||
within the document. You can move forward and back among the matches
|
||
by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show
|
||
the match inside the page image; instead, it displays a tooltip (at
|
||
the mouse position) listing all matching lines in the current page.
|
||
To force display of this tooltip, type @kbd{C-t}
|
||
(@code{doc-view-show-tooltip}).
|
||
|
||
To start a new search, use the search command with a prefix
|
||
argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
|
||
for a backward search.
|
||
|
||
@node DocView Slicing
|
||
@subsection DocView Slicing
|
||
|
||
Documents often have wide margins for printing. They are annoying
|
||
when reading the document on the screen, because they use up screen
|
||
space and can cause inconvenient scrolling.
|
||
|
||
@findex doc-view-set-slice
|
||
@findex doc-view-set-slice-using-mouse
|
||
With DocView you can hide these margins by selecting a @dfn{slice}
|
||
of pages to display. A slice is a rectangle within the page area;
|
||
once you specify a slice in DocView, it applies to whichever page you
|
||
look at.
|
||
|
||
To specify the slice numerically, type @kbd{c s}
|
||
(@code{doc-view-set-slice}); then enter the top left pixel position
|
||
and the slice's width and height.
|
||
@c ??? how does this work?
|
||
|
||
A more convenient graphical way to specify the slice is with @kbd{c
|
||
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
|
||
select the slice. Simply press and hold the left mouse button at the
|
||
upper-left corner of the region you want to have in the slice, then
|
||
move the mouse pointer to the lower-right corner and release the
|
||
button.
|
||
|
||
The most convenient way is to set the optimal slice by using
|
||
BoundingBox information automatically determined from the document by
|
||
typing @kbd{c b} (@code{doc-view-set-slice-from-bounding-box}).
|
||
|
||
@findex doc-view-reset-slice
|
||
To cancel the selected slice, type @kbd{c r}
|
||
(@code{doc-view-reset-slice}). Then DocView shows the entire page
|
||
including its entire margins.
|
||
|
||
@node DocView Conversion
|
||
@subsection DocView Conversion
|
||
|
||
@vindex doc-view-cache-directory
|
||
@findex doc-view-clear-cache
|
||
For efficiency, DocView caches the images produced by @command{gs}.
|
||
The name of the directory where it caches images is given by the variable
|
||
@code{doc-view-cache-directory}. You can clear the cache directory by
|
||
typing @kbd{M-x doc-view-clear-cache}.
|
||
|
||
@findex doc-view-kill-proc
|
||
@findex doc-view-kill-proc-and-buffer
|
||
To force reconversion of the currently viewed document, type @kbd{r}
|
||
or @kbd{g} (@code{revert-buffer}). To kill the converter process
|
||
associated with the current buffer, type @kbd{K}
|
||
(@code{doc-view-kill-proc}). The command @kbd{k}
|
||
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
|
||
the DocView buffer.
|
||
|
||
@node Shell
|
||
@section Running Shell Commands from Emacs
|
||
@cindex subshell
|
||
@cindex shell commands
|
||
|
||
Emacs has commands for passing single command lines to shell
|
||
subprocesses, and for running a shell interactively with input and
|
||
output to an Emacs buffer, and for running a shell in a terminal
|
||
emulator window.
|
||
|
||
@table @kbd
|
||
@item M-! @var{cmd} @key{RET}
|
||
Run the shell command @var{cmd} and display the output
|
||
(@code{shell-command}).
|
||
@item M-| @var{cmd} @key{RET}
|
||
Run the shell command @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 @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.
|
||
@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
|
||
|
||
@vindex exec-path
|
||
Whenever you specify a relative file name for an executable program
|
||
(either in the @var{cmd} argument to one of the above commands, or in
|
||
other contexts), Emacs searches for the program in the directories
|
||
specified by the variable @code{exec-path}. The value of this
|
||
variable must be a list of directories; the default value is
|
||
initialized from the environment variable @env{PATH} when Emacs is
|
||
started (@pxref{General Variables}).
|
||
|
||
@kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It
|
||
is documented in its own manual.
|
||
@ifnottex
|
||
@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
|
||
@end ifnottex
|
||
@iftex
|
||
See the Eshell Info manual, which is distributed with Emacs.
|
||
@end iftex
|
||
|
||
@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.
|
||
* Shell Prompts:: Two ways to recognize shell prompts.
|
||
* History: Shell History. Repeating previous commands in a shell buffer.
|
||
* Directory Tracking:: Keeping track when the subshell changes directory.
|
||
* Options: Shell Options. Options for customizing Shell mode.
|
||
* Terminal emulator:: An Emacs window as a terminal emulator.
|
||
* Term Mode:: Special Emacs commands used in Term mode.
|
||
* Remote Host:: Connecting to another computer.
|
||
* Serial Terminal:: Connecting to a serial port.
|
||
@end menu
|
||
|
||
@node Single Shell
|
||
@subsection Single Shell Commands
|
||
|
||
@kindex M-!
|
||
@findex shell-command
|
||
@vindex shell-command-buffer-name
|
||
@kbd{M-!} (@code{shell-command}) reads a line of text using the
|
||
minibuffer and executes it as a shell command, in a subshell made just
|
||
for that command. Standard input for the command comes from the null
|
||
device. If the shell command produces any output, the output appears
|
||
either in the echo area (if it is short), or in the @samp{"*Shell
|
||
Command Output*"} (@code{shell-command-buffer-name}) buffer (if the
|
||
output is long). The variables @code{resize-mini-windows} and
|
||
@code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when
|
||
Emacs should consider the output to be too long for the echo area.
|
||
Note that customizing @code{shell-command-dont-erase-buffer},
|
||
described below, can affect what is displayed in the echo area.
|
||
|
||
For instance, one way to decompress a file named @file{foo.gz} is to
|
||
type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally
|
||
creates the file @file{foo} and produces no terminal output.
|
||
|
||
A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!},
|
||
causes it to insert terminal output into the current buffer instead of
|
||
a separate buffer. By default, it puts point before the output, and
|
||
sets the mark after the output (but a non-default value of
|
||
@code{shell-command-dont-erase-buffer} can change that, see below).
|
||
For instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
|
||
uncompressed form of the file @file{foo.gz} into the current buffer.
|
||
|
||
Provided the specified shell command does not end with @samp{&}, it
|
||
runs @dfn{synchronously}, and you must wait for it to exit before
|
||
continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit;
|
||
this sends a @code{SIGINT} signal to terminate the shell command (this
|
||
is 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.
|
||
|
||
@kindex M-&
|
||
@findex async-shell-command
|
||
@vindex shell-command-buffer-name-async
|
||
A shell command that ends in @samp{&} is executed
|
||
@dfn{asynchronously}, and you can continue to use Emacs as it runs.
|
||
You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
|
||
shell command asynchronously; this is exactly like calling @kbd{M-!}
|
||
with a trailing @samp{&}, except that you do not need the @samp{&}.
|
||
The output from asynchronous shell commands, by default, goes into the
|
||
@samp{"*Async Shell Command*"} buffer
|
||
(@code{shell-command-buffer-name-async}). Emacs inserts the output
|
||
into this buffer as it comes in, whether or not the buffer is visible
|
||
in a window.
|
||
|
||
@vindex async-shell-command-buffer
|
||
If you want to run more than one asynchronous shell command at the
|
||
same time, they could end up competing for the output buffer. The
|
||
option @code{async-shell-command-buffer} specifies what to do about
|
||
this; e.g., whether to rename the pre-existing output buffer, or to
|
||
use a different buffer for the new command. Consult the variable's
|
||
documentation for more possibilities.
|
||
|
||
@vindex async-shell-command-display-buffer
|
||
If you want the output buffer for asynchronous shell commands to be
|
||
displayed only when the command generates output, set
|
||
@code{async-shell-command-display-buffer} to @code{nil}.
|
||
|
||
@vindex async-shell-command-width
|
||
The option @code{async-shell-command-width} defines the number of display
|
||
columns available for output of asynchronous shell commands.
|
||
A positive integer tells the shell to use that number of columns for
|
||
command output. The default value is @code{nil} that means to use
|
||
the same number of columns as provided by the shell.
|
||
|
||
@vindex shell-command-prompt-show-cwd
|
||
To make the above commands show the current directory in their
|
||
prompts, customize the variable @code{shell-command-prompt-show-cwd}
|
||
to a non-@code{nil} value.
|
||
|
||
@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, it deletes the
|
||
old region and replaces it with the output from the shell command.
|
||
|
||
For example, you can use @kbd{M-|} with the @command{gpg} program to
|
||
see what keys are in the buffer. If the buffer contains a GnuPG key,
|
||
type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
|
||
to @command{gpg}. This will output the list of keys to the
|
||
buffer whose name is the value of @code{shell-command-buffer-name}.
|
||
|
||
@vindex shell-file-name
|
||
@cindex @env{SHELL} environment variable
|
||
The above commands use the shell specified by the variable
|
||
@code{shell-file-name}. Its default value is determined by the
|
||
@env{SHELL} environment variable when Emacs is started. If the file
|
||
name is relative, Emacs searches the directories listed in
|
||
@code{exec-path} (@pxref{Shell}).
|
||
|
||
If the default directory is remote (@pxref{Remote Files}), the
|
||
default value is @file{/bin/sh}. This can be changed by declaring
|
||
@code{shell-file-name} connection-local (@pxref{Connection Variables}).
|
||
|
||
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
|
||
By default, error output is intermixed with the regular output in
|
||
the output buffer. But if you change the value of the variable
|
||
@code{shell-command-default-error-buffer} to a string, error output is
|
||
inserted into a buffer of that name.
|
||
|
||
@vindex shell-command-dont-erase-buffer
|
||
By default, the output buffer is erased between shell commands, except
|
||
when the output goes to the current buffer. If you change the value
|
||
of the option @code{shell-command-dont-erase-buffer} to @code{erase},
|
||
then the output buffer is always erased. Other non-@code{nil} values
|
||
prevent erasing of the output buffer, and---if the output buffer is
|
||
not the current buffer---also control where to put point after
|
||
inserting the output of the shell command:
|
||
|
||
@table @code
|
||
@item beg-last-out
|
||
Puts point at the beginning of the last shell-command output.
|
||
@item end-last-out
|
||
Puts point at the end of the last shell-command output, i.e.@: at the
|
||
end of the output buffer.
|
||
@item save-point
|
||
Restores the position of point as it was before inserting the
|
||
shell-command output.
|
||
@end table
|
||
|
||
Note that if this option is non-@code{nil}, the output shown in the
|
||
echo area could be from more than just the last command, since the
|
||
echo area just displays a portion of the output buffer.
|
||
|
||
In case the output buffer is not the current buffer, shell command
|
||
output is appended at the end of this buffer.
|
||
|
||
@node Interactive Shell
|
||
@subsection Interactive Subshell
|
||
|
||
@findex shell
|
||
To run a subshell interactively, type @kbd{M-x shell}. This creates
|
||
(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess
|
||
with input coming from and output going to that buffer. That is to
|
||
say, any terminal output from the subshell goes into the buffer,
|
||
advancing point, and any terminal input for the subshell comes from
|
||
text in the buffer. To give input to the subshell, go to the end of
|
||
the buffer and type the input, terminated by @key{RET}.
|
||
|
||
By default, when the subshell is invoked interactively, the
|
||
@file{*shell*} buffer is displayed in a new window, unless the current
|
||
window already shows the @file{*shell*} buffer. This behavior can
|
||
be customized via @code{display-buffer-alist} (@pxref{Window Choice}).
|
||
|
||
While the subshell is waiting or running a command, you can switch
|
||
windows or buffers and perform other editing in Emacs. Emacs inserts
|
||
the output from the subshell into the Shell buffer whenever it has
|
||
time to process it (e.g., while waiting for keyboard input).
|
||
|
||
@cindex @code{comint-highlight-input} face
|
||
@cindex @code{comint-highlight-prompt} face
|
||
In the Shell buffer, prompts are displayed with the face
|
||
@code{comint-highlight-prompt}, and submitted input lines are
|
||
displayed with the face @code{comint-highlight-input}. This makes it
|
||
easier to distinguish input lines from the shell output.
|
||
@xref{Faces}.
|
||
|
||
To make multiple subshells, invoke @kbd{M-x shell} with a prefix
|
||
argument (e.g., @kbd{C-u M-x shell}). Then the command will read a
|
||
buffer name, and create (or reuse) a subshell in that buffer. You can
|
||
also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
|
||
then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
|
||
Subshells in different buffers run independently and in parallel.
|
||
|
||
Emacs attempts to keep track of what the current directory is by
|
||
looking at the commands you enter, looking for @samp{cd} commands and
|
||
the like. This is an error-prone solution, since there are many ways
|
||
to change the current directory, so Emacs also looks for special
|
||
@acronym{OSC} (Operating System Commands) escape codes that are
|
||
designed to convey this information in a more reliable fashion. You
|
||
should arrange for your shell to print the appropriate escape sequence
|
||
at each prompt, for instance with the following command:
|
||
|
||
@example
|
||
printf "\e]7;file://%s%s\e\\" "$HOSTNAME" "$PWD"
|
||
@end example
|
||
|
||
@vindex explicit-shell-file-name
|
||
@cindex environment variables for subshells
|
||
@cindex @env{ESHELL} environment variable
|
||
To specify the shell file name used by @kbd{M-x shell}, customize
|
||
the variable @code{explicit-shell-file-name}. If this is @code{nil}
|
||
(the default), Emacs uses the environment variable @env{ESHELL} if it
|
||
exists. Otherwise, it usually uses the variable
|
||
@code{shell-file-name} (@pxref{Single Shell}); but if the default
|
||
directory is remote (@pxref{Remote Files}), it prompts you for the
|
||
shell file name. @xref{Minibuffer File}, for hints how to type remote
|
||
file names effectively.
|
||
|
||
Emacs sends the new shell the contents of the file
|
||
@file{~/.emacs_@var{shellname}} as input, if it exists, where
|
||
@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}. If this file is not found, Emacs tries with
|
||
@file{~/.emacs.d/init_@var{shellname}.sh}.
|
||
|
||
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{INSIDE_EMACS} environment variable
|
||
Emacs sets the environment variable @env{INSIDE_EMACS} in the
|
||
subshell to @samp{@var{version},comint}, where @var{version} is the
|
||
Emacs version (e.g., @samp{28.1}). Programs can check this variable
|
||
to determine whether they are running inside an Emacs subshell.
|
||
|
||
@node Shell Mode
|
||
@subsection Shell Mode
|
||
@cindex Shell mode
|
||
@cindex mode, Shell
|
||
|
||
The major mode for Shell buffers is Shell mode. Many of its special
|
||
commands are bound to the @kbd{C-c} prefix, and resemble the usual
|
||
editing and job control characters present in ordinary shells, except
|
||
that you must type @kbd{C-c} first. Here is a list of Shell mode
|
||
commands:
|
||
|
||
@table @kbd
|
||
@item @key{RET}
|
||
@kindex RET @r{(Shell mode)}
|
||
@findex comint-send-input
|
||
Send the current line as input to the subshell
|
||
(@code{comint-send-input}). Any shell prompt at the beginning of the
|
||
line is omitted (@pxref{Shell Prompts}). If point is at the end of
|
||
buffer, this is like submitting the command line in an ordinary
|
||
interactive shell. However, you can also invoke @key{RET} elsewhere
|
||
in the shell buffer to submit the current line as input.
|
||
|
||
@item @key{TAB}
|
||
@kindex TAB @r{(Shell mode)}
|
||
@findex completion-at-point@r{, in Shell Mode}
|
||
@cindex shell completion
|
||
Complete the command name or file name before point in the shell
|
||
buffer (@code{completion-at-point}). This uses the usual Emacs
|
||
completion rules (@pxref{Completion}), with the completion
|
||
alternatives being file names, environment variable names, the shell
|
||
command history, and history references (@pxref{History References}).
|
||
For options controlling the completion, @pxref{Shell Options}.
|
||
|
||
@item M-?
|
||
@kindex M-? @r{(Shell mode)}
|
||
@findex comint-dynamic-list-filename@dots{}
|
||
Display temporarily a list of the possible completions of the file
|
||
name before point (@code{comint-dynamic-list-filename-completions}).
|
||
|
||
@item C-d
|
||
@kindex C-d @r{(Shell mode)}
|
||
@findex comint-delchar-or-maybe-eof
|
||
Either delete a character or send @acronym{EOF}
|
||
(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
|
||
buffer, this sends @acronym{EOF} to the subshell. Typed at any other
|
||
position in the buffer, this deletes a character as usual.
|
||
|
||
@item C-c C-a
|
||
@kindex C-c C-a @r{(Shell mode)}
|
||
@findex comint-bol-or-process-mark
|
||
Move to the beginning of the line, but after the prompt if any
|
||
(@code{comint-bol-or-process-mark}). If you repeat this command twice
|
||
in a row, the second time it moves back to the process mark, which is
|
||
the beginning of the input that you have not yet sent to the subshell.
|
||
(Normally that is the same place---the end of the prompt on this
|
||
line---but after @kbd{C-c @key{SPC}} the process mark may be in a
|
||
previous line.)
|
||
|
||
@item C-c @key{SPC}
|
||
Accumulate multiple lines of input, then send them together
|
||
(@code{comint-accumulate}). This command inserts a newline before
|
||
point, but does not send the preceding text as input to the
|
||
subshell---at least, not yet. Both lines, the one before this newline
|
||
and the one after, will be sent together (along with the newline that
|
||
separates them), when you type @key{RET}.
|
||
|
||
@item C-c C-u
|
||
@kindex C-c C-u @r{(Shell mode)}
|
||
@findex comint-kill-input
|
||
Kill all text pending at end of buffer to be sent as input
|
||
(@code{comint-kill-input}). If point is not at end of buffer,
|
||
this only kills the part of this text that precedes point.
|
||
|
||
@item C-c C-w
|
||
@kindex C-c C-w @r{(Shell mode)}
|
||
Kill a word before point (@code{backward-kill-word}).
|
||
|
||
@item C-c C-c
|
||
@kindex C-c C-c @r{(Shell mode)}
|
||
@findex comint-interrupt-subjob
|
||
Interrupt the shell or its current subjob if any
|
||
(@code{comint-interrupt-subjob}). This command also kills
|
||
any shell input pending in the shell buffer and not yet sent.
|
||
|
||
@item C-c C-z
|
||
@kindex C-c C-z @r{(Shell mode)}
|
||
@findex comint-stop-subjob
|
||
Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
|
||
This command also kills any shell input pending in the shell buffer and
|
||
not yet sent.
|
||
|
||
@item C-c C-\
|
||
@findex comint-quit-subjob
|
||
@kindex C-c C-\ @r{(Shell mode)}
|
||
Send quit signal to the shell or its current subjob if any
|
||
(@code{comint-quit-subjob}). This command also kills any shell input
|
||
pending in the shell buffer and not yet sent.
|
||
|
||
@item C-c C-o
|
||
@kindex C-c C-o @r{(Shell mode)}
|
||
@findex comint-delete-output
|
||
Delete the last batch of output from a shell command
|
||
(@code{comint-delete-output}). This is useful if a shell command spews
|
||
out lots of output that just gets in the way. With a prefix argument,
|
||
this command saves the deleted text in the @code{kill-ring}
|
||
(@pxref{Kill Ring}), so that you could later yank it (@pxref{Yanking})
|
||
elsewhere.
|
||
|
||
@item C-c C-s
|
||
@kindex C-c C-s @r{(Shell mode)}
|
||
@findex comint-write-output
|
||
Write the last batch of output from a shell command to a file
|
||
(@code{comint-write-output}). With a prefix argument, the file is
|
||
appended to instead. Any prompt at the end of the output is not
|
||
written.
|
||
|
||
@item C-c C-r
|
||
@itemx C-M-l
|
||
@kindex C-c C-r @r{(Shell mode)}
|
||
@kindex C-M-l @r{(Shell mode)}
|
||
@findex comint-show-output
|
||
Scroll to display the beginning of the last batch of output at the top
|
||
of the window; also move the cursor there (@code{comint-show-output}).
|
||
|
||
@item C-c C-e
|
||
@kindex C-c C-e @r{(Shell mode)}
|
||
@findex comint-show-maximum-output
|
||
Scroll to put the last line of the buffer at the bottom of the window
|
||
(@code{comint-show-maximum-output}).
|
||
|
||
@item C-c C-f
|
||
@kindex C-c C-f @r{(Shell mode)}
|
||
@findex shell-forward-command
|
||
@vindex shell-command-regexp
|
||
Move forward across one shell command, but not beyond the current line
|
||
(@code{shell-forward-command}). The variable @code{shell-command-regexp}
|
||
specifies how to recognize the end of a command.
|
||
|
||
@item C-c C-b
|
||
@kindex C-c C-b @r{(Shell mode)}
|
||
@findex shell-backward-command
|
||
Move backward across one shell command, but not beyond the current line
|
||
(@code{shell-backward-command}).
|
||
|
||
@item M-x dirs
|
||
Ask the shell for its working directory, and update the Shell buffer's
|
||
default directory. @xref{Directory Tracking}.
|
||
|
||
@item M-x comint-send-invisible @key{RET} @var{text} @key{RET}
|
||
@findex comint-send-invisible
|
||
Send @var{text} as input to the shell, after reading it without
|
||
echoing. This is useful when a shell command runs a program that asks
|
||
for a password.
|
||
|
||
Please note that Emacs will not echo passwords by default. If you
|
||
really want them to be echoed, evaluate (@pxref{Lisp Eval}) the
|
||
following Lisp expression:
|
||
|
||
@example
|
||
(remove-hook 'comint-output-filter-functions
|
||
'comint-watch-for-password-prompt)
|
||
@end example
|
||
|
||
@item M-x comint-continue-subjob
|
||
@findex comint-continue-subjob
|
||
Continue the shell process. This is useful if you accidentally suspend
|
||
the shell process.@footnote{You should not suspend the shell process.
|
||
Suspending a subjob of the shell is a completely different matter---that
|
||
is normal practice, but you must use the shell to continue the subjob;
|
||
this command won't do it.}
|
||
|
||
@item M-x comint-strip-ctrl-m
|
||
@findex comint-strip-ctrl-m
|
||
Discard all control-M characters from the current group of shell output.
|
||
The most convenient way to use this command is to make it run
|
||
automatically when you get output from the subshell. To do that,
|
||
evaluate this Lisp expression:
|
||
|
||
@example
|
||
(add-hook 'comint-output-filter-functions
|
||
'comint-strip-ctrl-m)
|
||
@end example
|
||
|
||
@item M-x comint-truncate-buffer
|
||
@findex comint-truncate-buffer
|
||
This command truncates the shell buffer to a certain maximum number of
|
||
lines, specified by the variable @code{comint-buffer-maximum-size}.
|
||
Here's how to do this automatically each time you get output from the
|
||
subshell:
|
||
|
||
@example
|
||
(add-hook 'comint-output-filter-functions
|
||
'comint-truncate-buffer)
|
||
@end example
|
||
@end table
|
||
|
||
By default, Shell mode handles common @acronym{ANSI} escape codes (for
|
||
instance, for changing the color of text). Emacs also optionally
|
||
supports some extend escape codes, like some of the @acronym{OSC}
|
||
(Operating System Codes) if you put the following in your init file:
|
||
|
||
@lisp
|
||
(add-hook 'comint-output-filter-functions 'comint-osc-process-output)
|
||
@end lisp
|
||
|
||
With this enabled, the output from, for instance, @code{ls
|
||
--hyperlink} will be made into clickable buttons in the Shell mode
|
||
buffer.
|
||
|
||
@cindex Comint mode
|
||
@cindex mode, Comint
|
||
Shell mode is a derivative of Comint mode, a general-purpose mode for
|
||
communicating with interactive subprocesses. Most of the features of
|
||
Shell mode actually come from Comint mode, as you can see from the
|
||
command names listed above. The special features of Shell mode include
|
||
the directory tracking feature, and a few user commands.
|
||
|
||
Other Emacs features that use variants of Comint mode include GUD
|
||
(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
|
||
|
||
@findex comint-run
|
||
You can use @kbd{M-x comint-run} to execute any program of your choice
|
||
in a subprocess using unmodified Comint mode---without the
|
||
specializations of Shell mode. To pass arguments to the program, use
|
||
@kbd{C-u M-x comint-run}.
|
||
|
||
@node Shell Prompts
|
||
@subsection Shell Prompts
|
||
|
||
@cindex prompt, shell
|
||
A prompt is text output by a program to show that it is ready to
|
||
accept new user input. Normally, Comint mode (and thus Shell mode)
|
||
automatically figures out which part of the buffer is a prompt, based
|
||
on the output of the subprocess. (Specifically, it assumes that any
|
||
received output line which doesn't end with a newline is a prompt.)
|
||
|
||
Comint mode divides the buffer into two types of @dfn{fields}: input
|
||
fields (where user input is typed) and output fields (everywhere
|
||
else). Prompts are part of the output fields. Most Emacs motion
|
||
commands do not cross field boundaries, unless they move over multiple
|
||
lines. For instance, when point is in the input field on a shell
|
||
command line, @kbd{C-a} puts point at the beginning of the input
|
||
field, after the prompt. Internally, the fields are implemented using
|
||
the @code{field} text property (@pxref{Text Properties,,, elisp, the
|
||
Emacs Lisp Reference Manual}).
|
||
|
||
@vindex comint-use-prompt-regexp
|
||
@vindex shell-prompt-pattern
|
||
If you change the variable @code{comint-use-prompt-regexp} to a
|
||
non-@code{nil} value, then Comint mode will recognize prompts using a
|
||
regular expression (@pxref{Regexps}). In Shell mode, the regular
|
||
expression is specified by the variable @code{shell-prompt-pattern}.
|
||
The default value of @code{comint-use-prompt-regexp} is @code{nil},
|
||
because this method for recognizing prompts is unreliable, but you may
|
||
want to set it to a non-@code{nil} value in unusual circumstances. In
|
||
that case, Emacs does not divide the Comint buffer into fields, so the
|
||
general motion commands behave as they normally do in buffers without
|
||
special text properties. However, you can use the paragraph motion
|
||
commands to conveniently navigate the buffer (@pxref{Paragraphs}); in
|
||
Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph
|
||
boundaries.
|
||
|
||
@node Shell History
|
||
@subsection Shell Command History
|
||
|
||
Shell buffers support three ways of repeating earlier commands. You
|
||
can use keys like those used for the minibuffer history; these work
|
||
much as they do in the minibuffer, inserting text from prior commands
|
||
while point remains always at the end of the buffer. You can move
|
||
through the buffer to previous inputs in their original place, then
|
||
resubmit them or copy them to the end. Or you can use a
|
||
@samp{!}-style history reference.
|
||
|
||
@menu
|
||
* Ring: Shell Ring. Fetching commands from the history list.
|
||
* Copy: Shell History Copying. Moving to a command and then copying it.
|
||
* History References:: Expanding @samp{!}-style history references.
|
||
@end menu
|
||
|
||
@node Shell Ring
|
||
@subsubsection Shell History Ring
|
||
|
||
@table @kbd
|
||
@findex comint-previous-input
|
||
@kindex M-p @r{(Shell mode)}
|
||
@item M-p
|
||
@itemx C-@key{UP}
|
||
Fetch the next earlier old shell command
|
||
(@code{comint-previous-input}).
|
||
|
||
@kindex M-n @r{(Shell mode)}
|
||
@findex comint-next-input
|
||
@item M-n
|
||
@itemx C-@key{DOWN}
|
||
Fetch the next later old shell command (@code{comint-next-input}).
|
||
|
||
@kindex M-r @r{(Shell mode)}
|
||
@findex comint-history-isearch-backward-regexp
|
||
@item M-r
|
||
Begin an incremental regexp search of old shell commands
|
||
(@code{comint-history-isearch-backward-regexp}).
|
||
|
||
@item C-c C-x
|
||
@kindex C-c C-x @r{(Shell mode)}
|
||
@findex comint-get-next-from-history
|
||
Fetch the next subsequent command from the history
|
||
(@code{comint-get-next-from-history}).
|
||
|
||
@item C-c .
|
||
@kindex C-c . @r{(Shell mode)}
|
||
@findex comint-insert-previous-argument
|
||
Fetch one argument from an old shell command
|
||
(@code{comint-input-previous-argument}).
|
||
|
||
@item C-c C-l
|
||
@kindex C-c C-l @r{(Shell mode)}
|
||
@findex comint-dynamic-list-input-ring
|
||
Display the buffer's history of shell commands in another window
|
||
(@code{comint-dynamic-list-input-ring}).
|
||
@end table
|
||
|
||
Shell buffers provide a history of previously entered shell
|
||
commands. To reuse shell commands from the history, use the editing
|
||
commands @kbd{M-p}, @kbd{M-n}, and @kbd{M-r}. These work
|
||
similar to the minibuffer history commands (@pxref{Minibuffer
|
||
History}), except that they operate within the Shell buffer rather
|
||
than the minibuffer, and @code{M-r} in a Shell buffer invokes
|
||
incremental search through shell command history.
|
||
|
||
@kbd{M-p} fetches an earlier shell command to the end of the shell
|
||
buffer. Successive use of @kbd{M-p} fetches successively earlier
|
||
shell commands, each replacing any text that was already present as
|
||
potential shell input. @kbd{M-n} does likewise except that it finds
|
||
successively more recent shell commands from the buffer.
|
||
@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
|
||
@kbd{M-n}.
|
||
|
||
The history search command @kbd{M-r} begins an incremental regular
|
||
expression search of previous shell commands. After typing @kbd{M-r},
|
||
start typing the desired string or regular expression; the last
|
||
matching shell command will be displayed in the current line.
|
||
Incremental search commands have their usual effects---for instance,
|
||
@kbd{C-s} and @kbd{C-r} search forward and backward for the next match
|
||
(@pxref{Incremental Search}). When you find the desired input, type
|
||
@key{RET} to terminate the search. This puts the input in the command
|
||
line. Any partial input you were composing before navigating the
|
||
history list is restored when you go to the beginning or end of the
|
||
history ring.
|
||
|
||
Often it is useful to reexecute several successive shell commands that
|
||
were previously executed in sequence. To do this, first find and
|
||
reexecute the first command of the sequence. Then type @kbd{C-c C-x};
|
||
that will fetch the following command---the one that follows the command
|
||
you just repeated. Then type @key{RET} to reexecute this command. You
|
||
can reexecute several successive commands by typing @kbd{C-c C-x
|
||
@key{RET}} over and over.
|
||
|
||
The command @kbd{C-c .}@: (@code{comint-insert-previous-argument})
|
||
copies an individual argument from a previous command, like
|
||
@kbd{@key{ESC} .}@: in Bash and @command{zsh}. The simplest use
|
||
copies the last argument from the previous shell command. With a
|
||
prefix argument @var{n}, it copies the @var{n}th argument instead.
|
||
Repeating @kbd{C-c .} copies from an earlier shell commands, always
|
||
using the same value of @var{n} (don't give a prefix argument when
|
||
you repeat the @kbd{C-c .} command).
|
||
|
||
@vindex comint-insert-previous-argument-from-end
|
||
If you set @code{comint-insert-previous-argument-from-end} to a
|
||
non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th
|
||
argument counting from the last one; this emulates @kbd{@key{ESC} .}@:
|
||
in @command{zsh}.
|
||
|
||
These commands get the text of previous shell commands from a special
|
||
history list, not from the shell buffer itself. Thus, editing the shell
|
||
buffer, or even killing large parts of it, does not affect the history
|
||
that these commands access.
|
||
|
||
@vindex comint-input-ring-file-name
|
||
Some shells store their command histories in files so that you can
|
||
refer to commands from previous shell sessions. Emacs reads
|
||
the command history file for your chosen shell, to initialize its own
|
||
command history. The file name is @file{~/.bash_history} for bash,
|
||
@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
|
||
|
||
@vindex tramp-histfile-override
|
||
If you run the shell on a remote host, this setting might be
|
||
overwritten by the variable @code{tramp-histfile-override}. It is
|
||
recommended to set this variable to @code{nil}.
|
||
|
||
@node Shell History Copying
|
||
@subsubsection Shell History Copying
|
||
|
||
@table @kbd
|
||
@kindex C-c C-p @r{(Shell mode)}
|
||
@findex comint-previous-prompt
|
||
@item C-c C-p
|
||
Move point to the previous prompt (@code{comint-previous-prompt}).
|
||
|
||
@kindex C-c C-n @r{(Shell mode)}
|
||
@findex comint-next-prompt
|
||
@item C-c C-n
|
||
Move point to the following prompt (@code{comint-next-prompt}).
|
||
|
||
@kindex C-c RET @r{(Shell mode)}
|
||
@findex comint-copy-old-input
|
||
@item C-c @key{RET}
|
||
Copy the input command at point, inserting the copy at the end of the
|
||
buffer (@code{comint-copy-old-input}). This is useful if you move
|
||
point back to a previous command. After you copy the command, you can
|
||
submit the copy as input with @key{RET}. If you wish, you can edit
|
||
the copy before resubmitting it. If you use this command on an output
|
||
line, it copies that line to the end of the buffer.
|
||
|
||
@item mouse-2
|
||
If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
|
||
the old input command that you click on, inserting the copy at the end
|
||
of the buffer (@code{comint-insert-input}). If
|
||
@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
|
||
not over old input, just yank as usual.
|
||
@end table
|
||
|
||
Moving to a previous input and then copying it with @kbd{C-c
|
||
@key{RET}} or @kbd{mouse-2} produces the same results---the same
|
||
buffer contents---that you would get by using @kbd{M-p} enough times
|
||
to fetch that previous input from the history list. However, @kbd{C-c
|
||
@key{RET}} copies the text from the buffer, which can be different
|
||
from what is in the history list if you edit the input text in the
|
||
buffer after it has been sent.
|
||
|
||
@node History References
|
||
@subsubsection Shell History References
|
||
@cindex history reference
|
||
|
||
Various shells, including csh and bash, support @dfn{history
|
||
references} that begin with @samp{!} and @samp{^}. Shell mode
|
||
recognizes these constructs, and can perform the history substitution
|
||
for you.
|
||
|
||
If you insert a history reference and type @key{TAB}, this searches
|
||
the input history for a matching command, performs substitution if
|
||
necessary, and places the result in the buffer in place of the history
|
||
reference. For example, you can fetch the most recent command
|
||
beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the
|
||
command if you wish, and then resubmit the command to the shell by
|
||
typing @key{RET}.
|
||
|
||
@vindex comint-input-autoexpand
|
||
@findex comint-magic-space
|
||
Shell mode can optionally expand history references in the buffer
|
||
when you send them to the shell. To request this, set the variable
|
||
@code{comint-input-autoexpand} to @code{input}. You can make
|
||
@key{SPC} perform history expansion by binding @key{SPC} to the
|
||
command @code{comint-magic-space}. @xref{Rebinding}.
|
||
|
||
Shell mode recognizes history references when they follow a prompt.
|
||
@xref{Shell Prompts}, for how Shell mode recognizes prompts.
|
||
|
||
@node Directory Tracking
|
||
@subsection Directory Tracking
|
||
@cindex directory tracking
|
||
|
||
@vindex shell-pushd-regexp
|
||
@vindex shell-popd-regexp
|
||
@vindex shell-cd-regexp
|
||
Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
|
||
commands given to the subshell, in order to keep the Shell buffer's
|
||
default directory (@pxref{File Names}) the same as the shell's working
|
||
directory. It recognizes these commands by examining lines of input
|
||
that you send.
|
||
|
||
If you use aliases for these commands, you can tell Emacs to
|
||
recognize them also, by setting the variables
|
||
@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and
|
||
@code{shell-cd-regexp} to the appropriate regular expressions
|
||
(@pxref{Regexps}). For example, if @code{shell-pushd-regexp} matches
|
||
the beginning of a shell command line, that line is regarded as a
|
||
@code{pushd} command. These commands are recognized only at the
|
||
beginning of a shell command line.
|
||
|
||
@findex dirs
|
||
If Emacs gets confused about changes in the working directory of the
|
||
subshell, type @kbd{M-x dirs}. This command asks the shell for its
|
||
working directory and updates the default directory accordingly. It
|
||
works for shells that support the most common command syntax, but may
|
||
not work for unusual shells.
|
||
|
||
@findex dirtrack-mode
|
||
@cindex Dirtrack mode
|
||
@cindex mode, Dirtrack
|
||
@vindex dirtrack-list
|
||
You can also use Dirtrack mode, a buffer-local minor mode that
|
||
implements an alternative method of tracking the shell's working
|
||
directory. To use this method, your shell prompt must contain the
|
||
working directory at all times, and you must supply a regular
|
||
expression for recognizing which part of the prompt contains the
|
||
working directory; see the documentation of the variable
|
||
@code{dirtrack-list} for details. To use Dirtrack mode, type @kbd{M-x
|
||
dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to
|
||
@code{shell-mode-hook} (@pxref{Hooks}).
|
||
|
||
@node Shell Options
|
||
@subsection Shell Mode Options
|
||
|
||
@vindex comint-scroll-to-bottom-on-input
|
||
If the variable @code{comint-scroll-to-bottom-on-input} is
|
||
non-@code{nil}, insertion and yank commands scroll the selected window
|
||
to the bottom before inserting. The default is @code{nil}.
|
||
|
||
@vindex comint-scroll-show-maximum-output
|
||
If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
|
||
arrival of output when point is at the end tries to scroll the last
|
||
line of text to the bottom line of the window, showing as much useful
|
||
text as possible. (This mimics the scrolling behavior of most
|
||
terminals.) The default is @code{t}.
|
||
|
||
@vindex comint-move-point-for-output
|
||
By setting @code{comint-move-point-for-output}, you can opt for
|
||
having point jump to the end of the buffer whenever output arrives---no
|
||
matter where in the buffer point was before. If the value is
|
||
@code{this}, point jumps in the selected window. If the value is
|
||
@code{all}, point jumps in each window that shows the Comint buffer. If
|
||
the value is @code{other}, point jumps in all nonselected windows that
|
||
show the current buffer. The default value is @code{nil}, which means
|
||
point does not jump to the end.
|
||
|
||
@vindex comint-prompt-read-only
|
||
If you set @code{comint-prompt-read-only}, the prompts in the Comint
|
||
buffer are read-only.
|
||
|
||
@vindex comint-input-ignoredups
|
||
The variable @code{comint-input-ignoredups} controls whether successive
|
||
identical inputs are stored in the input history. A non-@code{nil}
|
||
value means to omit an input that is the same as the previous input.
|
||
The default is @code{nil}, which means to store each input even if it is
|
||
equal to the previous input.
|
||
|
||
@vindex comint-completion-addsuffix
|
||
@vindex comint-completion-recexact
|
||
@vindex comint-completion-autolist
|
||
Three variables customize file name completion. The variable
|
||
@code{comint-completion-addsuffix} controls whether completion inserts a
|
||
space or a slash to indicate a fully completed file or directory name
|
||
(non-@code{nil} means do insert a space or slash).
|
||
@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
|
||
to choose the shortest possible completion if the usual Emacs completion
|
||
algorithm cannot add even a single character.
|
||
@code{comint-completion-autolist}, if non-@code{nil}, says to list all
|
||
the possible completions whenever completion is not exact.
|
||
|
||
@vindex shell-completion-execonly
|
||
Command completion normally considers only executable files.
|
||
If you set @code{shell-completion-execonly} to @code{nil},
|
||
it considers nonexecutable files as well.
|
||
|
||
@vindex shell-completion-fignore
|
||
@vindex comint-completion-fignore
|
||
The variable @code{shell-completion-fignore} specifies a list of file
|
||
name extensions to ignore in Shell mode completion. The default
|
||
setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
|
||
ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other
|
||
related Comint modes use the variable @code{comint-completion-fignore}
|
||
instead.
|
||
|
||
@findex shell-dynamic-complete-command
|
||
Some implementation details of the shell command completion may also be found
|
||
in the lisp documentation of the @code{shell-dynamic-complete-command}
|
||
function.
|
||
|
||
@findex shell-pushd-tohome
|
||
@findex shell-pushd-dextract
|
||
@findex shell-pushd-dunique
|
||
You can configure the behavior of @samp{pushd}. Variables control
|
||
whether @samp{pushd} behaves like @samp{cd} if no argument is given
|
||
(@code{shell-pushd-tohome}), pop rather than rotate with a numeric
|
||
argument (@code{shell-pushd-dextract}), and only add directories to the
|
||
directory stack if they are not already on it
|
||
(@code{shell-pushd-dunique}). The values you choose should match the
|
||
underlying shell, of course.
|
||
|
||
@vindex comint-terminfo-terminal
|
||
@vindex system-uses-terminfo
|
||
@vindex TERM@r{, environment variable, in sub-shell}
|
||
Comint mode sets the @env{TERM} environment variable to a safe default
|
||
value, but this value disables some useful features. For example,
|
||
color is disabled in applications that use @env{TERM} to determine if
|
||
color is supported. Therefore, Emacs provides an option
|
||
@code{comint-terminfo-terminal} to let you choose a terminal with more
|
||
advanced features, as defined in your system's terminfo database.
|
||
Emacs will use this option as the value for @env{TERM} so long as
|
||
@code{system-uses-terminfo} is non-@code{nil}.
|
||
|
||
Both @code{comint-terminfo-terminal} and @code{system-uses-terminfo}
|
||
can be declared as connection-local variables to adjust these options
|
||
to match what a remote system expects (@pxref{Connection Variables}).
|
||
|
||
@node Terminal emulator
|
||
@subsection Emacs Terminal Emulator
|
||
@findex term
|
||
|
||
To run a subshell in a text terminal emulator, use @kbd{M-x term}.
|
||
This creates (or reuses) a buffer named @file{*terminal*}, and runs a
|
||
subshell with input coming from your keyboard, and output going to
|
||
that buffer.
|
||
|
||
@cindex line mode @r{(terminal emulator)}
|
||
@cindex char mode @r{(terminal emulator)}
|
||
The terminal emulator uses Term mode, which has two input modes. In
|
||
@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell
|
||
Mode}). In @dfn{char mode}, each character is sent directly to the
|
||
subshell, as terminal input; the sole exception is the terminal escape
|
||
character, which by default is @kbd{C-c} (@pxref{Term Mode}). Any
|
||
echoing of your input is the responsibility of the subshell; any
|
||
terminal output from the subshell goes into the buffer, advancing
|
||
point.
|
||
|
||
Some programs (such as Emacs itself) need to control the appearance
|
||
of the terminal screen in detail. They do this by emitting special
|
||
control codes. Term mode recognizes and handles ANSI-standard
|
||
VT100-style escape sequences, which are accepted by most modern
|
||
terminals, including @command{xterm}. (Hence, you can actually run
|
||
Emacs inside an Emacs Term window.)
|
||
|
||
The @code{term} face specifies the default appearance of text
|
||
in the terminal emulator (the default is the same appearance as the
|
||
@code{default} face). When terminal control codes are used to change
|
||
the appearance of text, these are represented in the terminal emulator
|
||
by the faces @code{term-color-black}, @code{term-color-red},
|
||
@code{term-color-green}, @code{term-color-yellow}
|
||
@code{term-color-blue}, @code{term-color-magenta},
|
||
@code{term-color-cyan}, @code{term-color-white},
|
||
@code{term-color-underline}, and @code{term-color-bold}.
|
||
@xref{Faces}.
|
||
|
||
You can also use Term mode to communicate with a device connected to
|
||
a serial port. @xref{Serial Terminal}.
|
||
|
||
The file name used to load the subshell is determined the same way
|
||
as for Shell mode. To make multiple terminal emulators, rename the
|
||
buffer @file{*terminal*} to something different using @kbd{M-x
|
||
rename-uniquely}, just as with Shell mode.
|
||
|
||
Unlike Shell mode, Term mode does not track the current directory by
|
||
examining your input. But some shells can tell Term what the current
|
||
directory is. This is done automatically by @code{bash} version 1.15
|
||
and later.
|
||
|
||
@node Term Mode
|
||
@subsection Term Mode
|
||
@cindex Term mode
|
||
@cindex mode, Term
|
||
|
||
To switch between line and char mode in Term mode, use these
|
||
commands:
|
||
|
||
@table @kbd
|
||
@kindex C-c C-j @r{(Term mode)}
|
||
@findex term-line-mode
|
||
@item C-c C-j
|
||
Switch to line mode (@code{term-line-mode}). Do nothing if already in
|
||
line mode.
|
||
|
||
@kindex C-c C-k @r{(Term mode)}
|
||
@findex term-char-mode
|
||
@item C-c C-k
|
||
Switch to char mode (@code{term-char-mode}). Do nothing if already in
|
||
char mode.
|
||
@end table
|
||
|
||
The following commands are only available in char mode:
|
||
|
||
@table @kbd
|
||
@item C-c C-c
|
||
Send a literal @kbd{C-c} to the sub-shell
|
||
(@code{term-interrupt-subjob}).
|
||
|
||
@item C-c @var{char}
|
||
This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For
|
||
example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
|
||
is normally @samp{other-window}.
|
||
@end table
|
||
|
||
@cindex paging in Term mode
|
||
Term mode has a page-at-a-time feature. When enabled, it makes
|
||
output pause at the end of each screenful:
|
||
|
||
@table @kbd
|
||
@kindex C-c C-q @r{(Term mode)}
|
||
@findex term-pager-toggle
|
||
@item C-c C-q
|
||
Toggle the page-at-a-time feature (@code{term-pager-toggle}). This
|
||
command works in both line and char modes. When the feature is
|
||
enabled, the mode-line displays the word @samp{page}, and each time
|
||
Term receives more than a screenful of output, it pauses and displays
|
||
@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
|
||
screenful of output, or @kbd{?} to see your other options. The
|
||
interface is similar to the @code{more} program.
|
||
@end table
|
||
|
||
@node Remote Host
|
||
@subsection Remote Host Shell
|
||
@cindex remote host
|
||
@cindex connecting to remote host
|
||
@cindex Telnet
|
||
@cindex SSH
|
||
|
||
You can login to a remote computer, using whatever commands you
|
||
would from a regular terminal (e.g., the @command{ssh} command), from
|
||
a Term window.
|
||
|
||
A program that asks you for a password will normally suppress
|
||
echoing of the password, so the password will not show up in the
|
||
buffer. This will happen just as if you were using a real terminal,
|
||
if the buffer is in char mode. If it is in line mode, the password is
|
||
temporarily visible, but will be erased when you hit return. (This
|
||
happens automatically; there is no special password processing.)
|
||
|
||
When you log in to a different machine, you need to specify the type
|
||
of terminal you're using, by setting the @env{TERM} environment
|
||
variable in the environment for the remote login command. (If you use
|
||
bash, you do that by writing the variable assignment before the remote
|
||
login command, without a separating comma.) Terminal types
|
||
@samp{ansi} or @samp{vt100} will work on most systems.
|
||
|
||
@node Serial Terminal
|
||
@subsection Serial Terminal
|
||
@cindex terminal, serial
|
||
@findex serial-term
|
||
|
||
If you have a device connected to a serial port of your computer,
|
||
you can communicate with it by typing @kbd{M-x serial-term}. This
|
||
command asks for a serial port name and speed, and switches to a new
|
||
Term mode buffer. Emacs communicates with the serial device through
|
||
this buffer just like it does with a terminal in ordinary Term mode.
|
||
|
||
The speed of the serial port is measured in bits per second. The
|
||
most common speed is 9600 bits per second. You can change the speed
|
||
interactively by clicking on the mode line.
|
||
|
||
A serial port can be configured even more by clicking on @samp{8N1} in
|
||
the mode line. By default, a serial port is configured as @samp{8N1},
|
||
which means that each byte consists of 8 data bits, No parity check
|
||
bit, and 1 stopbit.
|
||
|
||
If the speed or the configuration is wrong, you cannot communicate
|
||
with your device and will probably only see garbage output in the
|
||
window.
|
||
|
||
@node Emacs Server
|
||
@section Using Emacs as a Server
|
||
@pindex emacsclient
|
||
@cindex Emacs as a server
|
||
@cindex server, using Emacs as
|
||
@cindex @env{EDITOR} environment variable
|
||
|
||
Various programs can invoke your choice of editor to edit a
|
||
particular piece of text. For instance, version control programs
|
||
invoke an editor to enter version control logs (@pxref{Version
|
||
Control}), and the Unix @command{mail} utility invokes an editor to
|
||
enter a message to send. By convention, your choice of editor is
|
||
specified by the environment variable @env{EDITOR}. If you set
|
||
@env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an
|
||
inconvenient way---by starting a new Emacs process. This is
|
||
inconvenient because the new Emacs process doesn't share buffers, a
|
||
command history, or other kinds of information with any existing Emacs
|
||
process.
|
||
|
||
You can solve this problem by setting up Emacs as an @dfn{edit
|
||
server}, so that it ``listens'' for external edit requests and acts
|
||
accordingly. There are various ways to start an Emacs server:
|
||
|
||
@itemize
|
||
@findex server-start
|
||
@item
|
||
Run the command @code{server-start} in an existing Emacs process:
|
||
either type @kbd{M-x server-start}, or put the expression
|
||
@code{(server-start)} in your init file (@pxref{Init File}). The
|
||
existing Emacs process is the server; when you exit Emacs, the server
|
||
dies with the Emacs process.
|
||
|
||
@cindex daemon, Emacs
|
||
@item
|
||
Run Emacs as a @dfn{daemon}, using one of the @samp{--daemon} command-line
|
||
options. @xref{Initial Options}. When Emacs is started this way, it
|
||
calls @code{server-start} after initialization and does not open an
|
||
initial frame. It then waits for edit requests from clients.
|
||
|
||
@item
|
||
Run the command @code{emacsclient} with the @samp{--alternate-editor=""}
|
||
command-line option. This starts an Emacs daemon only if no Emacs daemon
|
||
is already running.
|
||
|
||
@cindex systemd unit file
|
||
@item
|
||
If your operating system uses @command{systemd} to manage startup,
|
||
you can automatically start Emacs in daemon mode when you login
|
||
using the supplied @dfn{systemd unit file}. To activate this:
|
||
@example
|
||
systemctl --user enable emacs
|
||
@end example
|
||
(If your Emacs was installed into a non-standard location, you may
|
||
need to copy the @file{emacs.service} file to a standard directory
|
||
such as @file{~/.config/systemd/user/}.)
|
||
|
||
@cindex socket activation, systemd, Emacs
|
||
@item
|
||
An external process can invoke the Emacs server when a connection
|
||
event occurs upon a specified socket and pass the socket to the new
|
||
Emacs server process. An instance of this is the socket functionality
|
||
of @command{systemd}: the @command{systemd} service creates a socket and
|
||
listens for connections on it; when @command{emacsclient} connects to
|
||
it for the first time, @command{systemd} can launch the Emacs server
|
||
and hand over the socket to it for servicing @command{emacsclient}
|
||
connections. A setup to use this functionality could be:
|
||
|
||
@file{~/.config/systemd/user/emacs.socket}:
|
||
@example
|
||
[Socket]
|
||
ListenStream=/path/to/.emacs.socket
|
||
DirectoryMode=0700
|
||
|
||
[Install]
|
||
WantedBy=sockets.target
|
||
@end example
|
||
|
||
(The @file{emacs.service} file described above must also be installed.)
|
||
|
||
The @code{ListenStream} path will be the path that Emacs listens for
|
||
connections from @command{emacsclient}; this is a file of your choice.
|
||
@end itemize
|
||
|
||
@cindex @env{TEXEDIT} environment variable
|
||
Once an Emacs server is started, you can use a shell
|
||
command called @command{emacsclient} to connect to the Emacs process
|
||
and tell it to visit a file. You can then set the @env{EDITOR}
|
||
environment variable to @samp{emacsclient}, so that external programs
|
||
will use the existing Emacs process for editing.@footnote{Some
|
||
programs use a different environment variable; for example, to make
|
||
@TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment
|
||
variable to @samp{emacsclient +%d %s}.}
|
||
|
||
@vindex server-name
|
||
You can run multiple Emacs servers on the same machine by giving
|
||
each one a unique @dfn{server name}, using the variable
|
||
@code{server-name}. For example, @kbd{M-x set-variable @key{RET}
|
||
server-name @key{RET} "foo" @key{RET}} sets the server name to
|
||
@samp{foo}. The @code{emacsclient} program can specify a server by
|
||
name, using the @samp{-s} or the @samp{-f} option (@pxref{emacsclient
|
||
Options}), depending on whether or not the server uses a TCP socket
|
||
(@pxref{TCP Emacs server}).
|
||
|
||
If you want to run multiple Emacs daemons (@pxref{Initial Options}),
|
||
you can give each daemon its own server name like this:
|
||
|
||
@example
|
||
emacs --daemon=foo
|
||
@end example
|
||
|
||
@vindex server-stop-automatically
|
||
The Emacs server can optionally be stopped automatically when
|
||
certain conditions are met. To do this, set the option
|
||
@code{server-stop-automatically} to one of the following values:
|
||
|
||
@table @code
|
||
@item empty
|
||
This value causes the server to be stopped when it has no clients, no
|
||
unsaved file-visiting buffers and no running processes anymore.
|
||
|
||
@item delete-frame
|
||
This value means that when the last client frame is being closed, you
|
||
are asked whether each unsaved file-visiting buffer must be saved and
|
||
each unfinished process can be stopped, and if so, the server is
|
||
stopped.
|
||
|
||
@item kill-terminal
|
||
This value means that when the last client frame is being closed with
|
||
@kbd{C-x C-c} (@code{save-buffers-kill-terminal}), you are asked
|
||
whether each unsaved file-visiting buffer must be saved and each
|
||
unfinished process can be stopped, and if so, the server is stopped.
|
||
@end table
|
||
|
||
@findex server-eval-at
|
||
If you have defined a server by a unique server name, it is possible
|
||
to connect to the server from another Emacs instance and evaluate Lisp
|
||
expressions on the server, using the @code{server-eval-at} function.
|
||
For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the
|
||
expression @code{(+ 1 2)} on the @samp{foo} server, and returns
|
||
@code{3}. (If there is no server with that name, an error is
|
||
signaled.) Currently, this feature is mainly useful for developers.
|
||
|
||
If your operating system’s desktop environment is
|
||
@url{https://www.freedesktop.org/wiki/Specifications/,,freedesktop.org-compatible}
|
||
(which is true of most GNU/Linux and other recent Unix-like GUIs), you
|
||
may use the @samp{Emacs (Client)} menu entry to connect to an Emacs
|
||
server with @command{emacsclient}. The daemon starts if not
|
||
already running.
|
||
|
||
@menu
|
||
* TCP Emacs server:: Listening to a TCP socket.
|
||
* Invoking emacsclient:: Connecting to the Emacs server.
|
||
* emacsclient Options:: Emacs client startup options.
|
||
@end menu
|
||
|
||
@node TCP Emacs server
|
||
@subsection TCP Emacs server
|
||
@cindex TCP Emacs server
|
||
|
||
@vindex server-use-tcp
|
||
An Emacs server usually listens to connections on a local Unix
|
||
domain socket. Some operating systems, such as MS-Windows, do not
|
||
support local sockets; in that case, the server uses TCP sockets
|
||
instead. In some cases it is useful to have the server listen on a
|
||
TCP socket even if local sockets are supported, e.g., if you need to
|
||
contact the Emacs server from a remote machine. You can set
|
||
@code{server-use-tcp} to non-@code{nil} to have Emacs listen on a TCP
|
||
socket instead of a local socket. This is the default if your OS does
|
||
not support local sockets.
|
||
|
||
@vindex server-host
|
||
@vindex server-port
|
||
If the Emacs server is set to use TCP, it will by default listen on
|
||
a random port on the localhost interface. This can be changed to
|
||
another interface and/or a fixed port using the variables
|
||
@code{server-host} and @code{server-port}.
|
||
|
||
@vindex server-auth-key
|
||
A TCP socket is not subject to file system permissions. To retain
|
||
some control over which users can talk to an Emacs server over TCP
|
||
sockets, the @command{emacsclient} program must send an authorization
|
||
key to the server. This key is normally randomly generated by the
|
||
Emacs server. This is the recommended mode of operation.
|
||
|
||
@findex server-generate-key
|
||
If needed, you can set the authorization key to a static value by
|
||
setting the @code{server-auth-key} variable. The key must consist of
|
||
64 ASCII printable characters except for space (this means characters
|
||
from @samp{!} to @samp{~}, or from decimal code 33 to 126). You can
|
||
use @kbd{M-x server-generate-key} to get a random key.
|
||
|
||
@vindex server-auth-dir
|
||
@cindex server file
|
||
When you start a TCP Emacs server, Emacs creates a @dfn{server file}
|
||
containing the TCP information to be used by @command{emacsclient} to
|
||
connect to the server. The variable @code{server-auth-dir} specifies
|
||
the default directory containing the server file; by default, this is
|
||
@file{~/.emacs.d/server/}. In the absence of a local socket with file
|
||
permissions, the permissions of this directory determine which users
|
||
can have their @command{emacsclient} processes talk to the Emacs
|
||
server. If @code{server-name} is an absolute file name, the server
|
||
file is created where specified by that file name.
|
||
|
||
@vindex EMACS_SERVER_FILE@r{, environment variable}
|
||
To tell @command{emacsclient} to connect to the server over TCP with
|
||
a specific server file, use the @samp{-f} or @samp{--server-file}
|
||
option, or set the @env{EMACS_SERVER_FILE} environment variable
|
||
(@pxref{emacsclient Options}). If @code{server-auth-dir} is set to a
|
||
non-standard value, or if @code{server-name} is set to an absolute
|
||
file name, @command{emacsclient} needs an absolute file name to the
|
||
server file, as the default @code{server-auth-dir} is hard-coded in
|
||
@command{emacsclient} to be used as the directory for resolving
|
||
relative filenames.
|
||
|
||
@node Invoking emacsclient
|
||
@subsection Invoking @code{emacsclient}
|
||
@cindex @code{emacsclient} invocation
|
||
|
||
The simplest way to use the @command{emacsclient} program is to run
|
||
the shell command @samp{emacsclient @var{file}}, where @var{file} is a
|
||
file name. This connects to an Emacs server, and tells that Emacs
|
||
process to visit @var{file} in one of its existing frames---either a
|
||
graphical frame, or one in a text terminal (@pxref{Frames}). You
|
||
can then select that frame to begin editing.
|
||
|
||
If there is no Emacs server, the @command{emacsclient} program halts
|
||
with an error message (you can prevent this from happening by using
|
||
the @samp{--alternate-editor=""} option to @command{emacsclient},
|
||
@pxref{emacsclient Options}). If the Emacs process has no existing
|
||
frame---which can happen if it was started as a daemon (@pxref{Emacs
|
||
Server})---then Emacs opens a frame on the terminal in which you
|
||
called @command{emacsclient}.
|
||
|
||
You can also force @command{emacsclient} to open a new frame on a
|
||
graphical display using the @samp{-c} option, or on a text terminal
|
||
using the @samp{-t} option. @xref{emacsclient Options}.
|
||
|
||
If you are running on a single text terminal, you can switch between
|
||
@command{emacsclient}'s shell and the Emacs server using one of two
|
||
methods: (i) run the Emacs server and @command{emacsclient} on
|
||
different virtual terminals, and switch to the Emacs server's virtual
|
||
terminal after calling @command{emacsclient}; or (ii) call
|
||
@command{emacsclient} from within the Emacs server itself, using Shell
|
||
mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode});
|
||
@command{emacsclient} blocks only the subshell under Emacs, and you can
|
||
still use Emacs to edit the file.
|
||
|
||
@kindex C-x #
|
||
@findex server-edit
|
||
When you finish editing @var{file} in the Emacs server, type
|
||
@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file
|
||
and sends a message back to the @command{emacsclient} program, telling
|
||
it to exit. Programs that use @env{EDITOR} usually wait for the
|
||
editor---in this case @command{emacsclient}---to exit before doing
|
||
something else.
|
||
|
||
@findex server-edit-abort
|
||
If you want to abandon the edit instead, use the @w{@kbd{M-x
|
||
server-edit-abort}} command. This sends a message back to the
|
||
@command{emacsclient} program, telling it to exit with abnormal exit
|
||
status, and doesn't save any buffers.
|
||
|
||
You can also call @command{emacsclient} with multiple file name
|
||
arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
|
||
Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs
|
||
selects the buffer visiting @var{file1}, and buries the other buffers
|
||
at the bottom of the buffer list (@pxref{Buffers}). The
|
||
@command{emacsclient} program exits once all the specified files are
|
||
finished (i.e., once you have typed @kbd{C-x #} in each server
|
||
buffer).
|
||
|
||
@vindex server-kill-new-buffers
|
||
@vindex server-temp-file-regexp
|
||
Finishing with a server buffer also kills the buffer, unless it
|
||
already existed in the Emacs session before the server was asked to
|
||
create it. However, if you set @code{server-kill-new-buffers} to
|
||
@code{nil}, then a different criterion is used: finishing with a
|
||
server buffer kills it if the file name matches the regular expression
|
||
@code{server-temp-file-regexp}. This is set up to distinguish certain
|
||
temporary files.
|
||
|
||
Each @kbd{C-x #} checks for other pending external requests to edit
|
||
various files, and selects the next such file. You can switch to a
|
||
server buffer manually if you wish; you don't have to arrive at it
|
||
with @kbd{C-x #}. But @kbd{C-x #} is the way to tell
|
||
@command{emacsclient} that you are finished.
|
||
|
||
@vindex server-window
|
||
If you set the value of the variable @code{server-window} to a
|
||
window or a frame, @kbd{C-x #} always displays the next server buffer
|
||
in that window or in that frame.
|
||
|
||
@vindex server-client-instructions
|
||
When @command{emacsclient} connects, the server will normally output
|
||
a message that says how to exit the client frame. If
|
||
@code{server-client-instructions} is set to @code{nil}, this message
|
||
is inhibited.
|
||
|
||
@node emacsclient Options
|
||
@subsection @code{emacsclient} Options
|
||
@cindex @code{emacsclient} options
|
||
|
||
You can pass some optional arguments to the @command{emacsclient}
|
||
program, such as:
|
||
|
||
@example
|
||
emacsclient -c +12 @var{file1} +4:3 @var{file2}
|
||
@end example
|
||
|
||
@noindent
|
||
The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments
|
||
specify line numbers, or line and column numbers, for the next file
|
||
argument. These behave like the command line arguments for Emacs
|
||
itself. @xref{Action Arguments}.
|
||
|
||
The other optional arguments recognized by @command{emacsclient} are
|
||
listed below:
|
||
|
||
@table @samp
|
||
@item -a @var{command}
|
||
@itemx --alternate-editor=@var{command}
|
||
Specify a shell command to run if @command{emacsclient} fails to
|
||
contact Emacs. This is useful when running @code{emacsclient} in a
|
||
script. The command may include arguments, which may be quoted "like
|
||
this". Currently, escaping of quotes is not supported.
|
||
|
||
As a special exception, if @var{command} is the empty string, then
|
||
@command{emacsclient} starts Emacs in daemon mode (as @samp{emacs
|
||
--daemon}) and then tries connecting again.
|
||
|
||
@cindex @env{ALTERNATE_EDITOR} environment variable
|
||
The environment variable @env{ALTERNATE_EDITOR} has the same effect as
|
||
the @samp{-a} option. If both are present, the latter takes
|
||
precedence.
|
||
|
||
@cindex client frame
|
||
@item -c
|
||
@itemx --create-frame
|
||
Create a new graphical @dfn{client frame}, instead of using an
|
||
existing Emacs frame. See below for the special behavior of @kbd{C-x
|
||
C-c} in a client frame. If Emacs cannot create a new graphical frame
|
||
(e.g., if it cannot connect to the X server), it tries to create a
|
||
text terminal client frame, as though you had supplied the @samp{-t}
|
||
option instead.
|
||
|
||
On MS-Windows, a single Emacs session cannot display frames on both
|
||
graphical and text terminals, nor on multiple text terminals. Thus,
|
||
if the Emacs server is running on a text terminal, the @samp{-c}
|
||
option, like the @samp{-t} option, creates a new frame in the server's
|
||
current text terminal. @xref{Windows Startup}.
|
||
|
||
If you omit a filename argument while supplying the @samp{-c} option,
|
||
the new frame displays the @file{*scratch*} buffer by default. You
|
||
can customize this behavior with the variable @code{initial-buffer-choice}
|
||
(@pxref{Entering Emacs}).
|
||
|
||
@item -r
|
||
@itemx --reuse-frame
|
||
Create a new graphical client frame if none exists, otherwise use an
|
||
existing Emacs frame.
|
||
|
||
@item -F @var{alist}
|
||
@itemx --frame-parameters=@var{alist}
|
||
Set the parameters for a newly-created graphical frame
|
||
(@pxref{Frame Parameters}).
|
||
|
||
@item -d @var{display}
|
||
@itemx --display=@var{display}
|
||
Tell Emacs to open the given files on the X display @var{display}
|
||
(assuming there is more than one X display available).
|
||
|
||
@item -e
|
||
@itemx --eval
|
||
Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
|
||
files. When this option is given, the arguments to
|
||
@command{emacsclient} are interpreted as a list of expressions to
|
||
evaluate, @emph{not} as a list of files to visit.
|
||
|
||
@vindex server-eval-args-left
|
||
Passing complex Lisp expression via the @option{--eval} command-line
|
||
option sometimes requires elaborate escaping of characters special to
|
||
the shell. To avoid this, you can pass arguments to Lisp functions in
|
||
your expression as additional separate arguments to
|
||
@command{emacsclient}, and use @var{server-eval-args-left} in the
|
||
expression to access those arguments. Be careful to have your
|
||
expression remove the processed arguments from
|
||
@var{server-eval-args-left} regardless of whether your code succeeds,
|
||
for example by using @code{pop}, otherwise Emacs will attempt to
|
||
evaluate those arguments as separate Lisp expressions.
|
||
|
||
@item -f @var{server-file}
|
||
@itemx --server-file=@var{server-file}
|
||
Specify a server file (@pxref{TCP Emacs server}) for connecting to an
|
||
Emacs server via TCP@. Alternatively, you can set the
|
||
@env{EMACS_SERVER_FILE} environment variable to point to the server
|
||
file. (The command-line option overrides the environment variable.)
|
||
|
||
An Emacs server usually uses a local socket to listen for connections,
|
||
but also supports connections over TCP@. To connect to a TCP Emacs
|
||
server, @command{emacsclient} needs to read a @dfn{server file}
|
||
containing the connection details of the Emacs server. The name of
|
||
this file is specified with this option, either as a file name
|
||
relative to @file{~/.emacs.d/server} or as an absolute file name.
|
||
@xref{TCP Emacs server}.
|
||
|
||
@item -n
|
||
@itemx --no-wait
|
||
Let @command{emacsclient} exit immediately, instead of waiting until
|
||
all server buffers are finished. You can take as long as you like to
|
||
edit the server buffers within Emacs, and they are @emph{not} killed
|
||
when you type @kbd{C-x #} in them.
|
||
|
||
@item -w
|
||
@itemx --timeout=@var{N}
|
||
Wait for a response from Emacs for @var{N} seconds before giving up.
|
||
If there is no response within that time, @command{emacsclient} will
|
||
display a warning and exit. The default is @samp{0}, which means to
|
||
wait forever.
|
||
|
||
@item --parent-id=@var{id}
|
||
Open an @command{emacsclient} frame as a client frame in the parent X
|
||
window with id @var{id}, via the XEmbed protocol. Currently, this
|
||
option is mainly useful for developers.
|
||
|
||
@item -q
|
||
@itemx --quiet
|
||
Do not let @command{emacsclient} display messages about waiting for
|
||
Emacs or connecting to remote server sockets.
|
||
|
||
@item -u
|
||
@itemx --suppress-output
|
||
Do not let @command{emacsclient} display results returned from the
|
||
server. Mostly useful in combination with @samp{-e} when the
|
||
evaluation performed is for side-effect rather than result.
|
||
|
||
@item -s @var{server-name}
|
||
@itemx --socket-name=@var{server-name}
|
||
Connect to the Emacs server named @var{server-name}. (This option is
|
||
not supported on MS-Windows.) The server name is given by the
|
||
variable @code{server-name} on the Emacs server. If this option is
|
||
omitted, @command{emacsclient} connects to the default socket.
|
||
If you set @code{server-name} of the Emacs server to an absolute file
|
||
name, give the same absolute file name as @var{server-name} to this
|
||
option to instruct @command{emacsclient} to connect to that server.
|
||
You need to use this option if you started Emacs as daemon
|
||
(@pxref{Initial Options}) and specified the name for the server
|
||
started by the daemon.
|
||
|
||
Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment
|
||
variable to point to the server socket. (The command-line option
|
||
overrides the environment variable.)
|
||
|
||
@item -t
|
||
@itemx --tty
|
||
@itemx -nw
|
||
Create a new client frame on the current text terminal, instead of
|
||
using an existing Emacs frame. This behaves just like the @samp{-c}
|
||
option, described above, except that it creates a text terminal frame
|
||
(@pxref{Text Terminals}).
|
||
|
||
On MS-Windows, @samp{-t} behaves just like @samp{-c} if the Emacs
|
||
server is using the graphical display, but if the Emacs server is
|
||
running on a text terminal, it creates a new frame in the current text
|
||
terminal.
|
||
|
||
@item -T @var{tramp-prefix}
|
||
@itemx --tramp=@var{tramp-prefix}
|
||
Set the prefix to add to filenames for Emacs to locate files on remote
|
||
machines (@pxref{Remote Files}) using TRAMP (@pxref{Top, The Tramp
|
||
Manual,, tramp, The Tramp Manual}). This is mostly useful in
|
||
combination with using the Emacs server from a remote host. By
|
||
ssh-forwarding the listening socket, or ssh-forwarding the listening
|
||
port @pxref{TCP Emacs server} and making the
|
||
@var{server-file} available on a remote machine, programs on the
|
||
remote machine can use @command{emacsclient} as the value for the
|
||
@env{EDITOR} and similar environment variables, but instead of talking
|
||
to an Emacs server on the remote machine, the files will be visited in
|
||
the local Emacs session using TRAMP.
|
||
|
||
@vindex EMACSCLIENT_TRAMP@r{, environment variable}
|
||
Setting the environment variable @env{EMACSCLIENT_TRAMP} has the same
|
||
effect as using the @samp{-T} option. If both are specified, the
|
||
command-line option takes precedence.
|
||
|
||
For example, assume two hosts, @samp{local} and @samp{remote}.
|
||
|
||
@example
|
||
local$ ssh -R "/home/%r/.emacs.socket":"$@{XDG_RUNTIME_DIR:-$@{TMPDIR:-/tmp@}/emacs%i@}$@{XDG_RUNTIME_DIR:+/emacs@}/server" remote
|
||
remote$ export EMACS_SOCKET_NAME=$HOME/.emacs.socket
|
||
remote$ export EMACSCLIENT_TRAMP=/ssh:remote:
|
||
remote$ export EDITOR=emacsclient
|
||
remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
|
||
@end example
|
||
|
||
If you are using a platform where @command{emacsclient} does not use
|
||
Unix domain sockets (i.e., MS-Windows), or your SSH implementation is
|
||
not able to forward them (e.g., OpenSSH before version 6.7), you can
|
||
forward a TCP port instead. In this example, assume that the local
|
||
Emacs listens on tcp port 12345. Assume further that
|
||
@file{/home} is on a shared file system, so that the server file
|
||
@file{~/.emacs.d/server/server} is readable on both hosts.
|
||
|
||
@example
|
||
local$ ssh -R12345:localhost:12345 remote
|
||
remote$ export EMACS_SERVER_FILE=server
|
||
remote$ export EMACSCLIENT_TRAMP=/ssh:remote:
|
||
remote$ export EDITOR=emacsclient
|
||
remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
|
||
@end example
|
||
|
||
@end table
|
||
|
||
The new graphical or text terminal frames created by the @samp{-c}
|
||
or @samp{-t} options are considered @dfn{client frames}. Any new
|
||
frame that you create from a client frame is also considered a client
|
||
frame. If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal})
|
||
in a client frame, that command does not kill the Emacs session as it
|
||
normally does (@pxref{Exiting}). Instead, Emacs deletes the client
|
||
frame; furthermore, if the client frame has an @command{emacsclient}
|
||
waiting to regain control (i.e., if you did not supply the @samp{-n}
|
||
option), Emacs deletes all other frames of the same client, and marks
|
||
the client's server buffers as finished, as though you had typed
|
||
@kbd{C-x #} in all of them. If it so happens that there are no
|
||
remaining frames after the client frame(s) are deleted, the Emacs
|
||
session exits.
|
||
|
||
As an exception, when Emacs is started as a daemon, all frames are
|
||
considered client frames, and @kbd{C-x C-c} never kills Emacs. To
|
||
kill a daemon session, type @kbd{M-x kill-emacs}.
|
||
|
||
Note that the @samp{-t} and @samp{-n} options are contradictory:
|
||
@samp{-t} says to take control of the current text terminal to create
|
||
a new client frame, while @samp{-n} says not to take control of the
|
||
text terminal. If you supply both options, Emacs visits the specified
|
||
files(s) in an existing frame rather than a new client frame, negating
|
||
the effect of @samp{-t}.
|
||
|
||
@node Printing
|
||
@section Printing Hard Copies
|
||
@cindex hardcopy
|
||
@cindex printing
|
||
|
||
Emacs provides commands for printing hardcopies of either an entire
|
||
buffer or part of one. You can invoke the printing commands directly,
|
||
as detailed below, or using the @samp{File} menu on the menu bar.
|
||
|
||
@findex htmlfontify-buffer
|
||
Aside from the commands described in this section, you can also
|
||
print hardcopies from Dired (@pxref{Operating on Files}) and the diary
|
||
(@pxref{Displaying the Diary}). You can also ``print'' an Emacs
|
||
buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which
|
||
converts the current buffer to a HTML file, replacing Emacs faces with
|
||
CSS-based markup. Furthermore, Org mode allows you to print Org
|
||
files to a variety of formats, such as PDF (@pxref{Org Mode}).
|
||
|
||
@table @kbd
|
||
@item M-x print-buffer
|
||
Print hardcopy of current buffer with page headings containing the
|
||
file name and page number.
|
||
@item M-x lpr-buffer
|
||
Print hardcopy of current buffer without page headings.
|
||
@item M-x print-region
|
||
Like @code{print-buffer} but print only the current region.
|
||
@item M-x lpr-region
|
||
Like @code{lpr-buffer} but print only the current region.
|
||
@end table
|
||
|
||
@findex print-buffer
|
||
@findex print-region
|
||
@findex lpr-buffer
|
||
@findex lpr-region
|
||
@vindex lpr-switches
|
||
@vindex lpr-commands
|
||
On most operating systems, the above hardcopy commands submit files
|
||
for printing by calling the @command{lpr} program. To change the
|
||
printer program, customize the variable @code{lpr-command}. To
|
||
specify extra switches to give the printer program, customize the list
|
||
variable @code{lpr-switches}. Its value should be a list of option
|
||
strings, each of which should start with @samp{-} (e.g., the option
|
||
string @code{"-w80"} specifies a line width of 80 columns). The
|
||
default is the empty list, @code{nil}.
|
||
|
||
@vindex printer-name
|
||
@vindex lpr-printer-switch
|
||
To specify the printer to use, set the variable @code{printer-name}.
|
||
The default, @code{nil}, specifies the default printer. If you set it
|
||
to a printer name (a string), that name is passed to @command{lpr}
|
||
with the @samp{-P} switch; if you are not using @command{lpr}, you
|
||
should specify the switch with @code{lpr-printer-switch}.
|
||
|
||
@vindex lpr-headers-switches
|
||
@vindex lpr-add-switches
|
||
The variable @code{lpr-headers-switches} similarly specifies the
|
||
extra switches to use to make page headers. The variable
|
||
@code{lpr-add-switches} controls whether to supply @samp{-T} and
|
||
@samp{-J} options (suitable for @command{lpr}) to the printer program:
|
||
@code{nil} means don't add them (this should be the value if your
|
||
printer program is not compatible with @command{lpr}).
|
||
|
||
@menu
|
||
* PostScript:: Printing buffers or regions as PostScript.
|
||
* PostScript Variables:: Customizing the PostScript printing commands.
|
||
* Printing Package:: An optional advanced printing interface.
|
||
@end menu
|
||
|
||
@node PostScript
|
||
@subsection PostScript Hardcopy
|
||
|
||
These commands convert buffer contents to PostScript,
|
||
either printing it or leaving it in another Emacs buffer.
|
||
|
||
@table @kbd
|
||
@item M-x ps-print-buffer
|
||
Print hardcopy of the current buffer in PostScript form.
|
||
@item M-x ps-print-region
|
||
Print hardcopy of the current region in PostScript form.
|
||
@item M-x ps-print-buffer-with-faces
|
||
Print hardcopy of the current buffer in PostScript form, showing the
|
||
faces used in the text by means of PostScript features.
|
||
@item M-x ps-print-region-with-faces
|
||
Print hardcopy of the current region in PostScript form, showing the
|
||
faces used in the text.
|
||
@item M-x ps-spool-buffer
|
||
Generate and spool a PostScript image for the current buffer text.
|
||
@item M-x ps-spool-region
|
||
Generate and spool a PostScript image for the current region.
|
||
@item M-x ps-spool-buffer-with-faces
|
||
Generate and spool a PostScript image for the current buffer, showing the faces used.
|
||
@item M-x ps-spool-region-with-faces
|
||
Generate and spool a PostScript image for the current region, showing the faces used.
|
||
@item M-x ps-despool
|
||
Send the spooled PostScript to the printer.
|
||
@item M-x handwrite
|
||
Generate/print PostScript for the current buffer as if handwritten.
|
||
@end table
|
||
|
||
@findex ps-print-region
|
||
@findex ps-print-buffer
|
||
@findex ps-print-region-with-faces
|
||
@findex ps-print-buffer-with-faces
|
||
The @code{ps-print-buffer} and @code{ps-print-region} commands print
|
||
buffer contents in PostScript form. One command prints the entire
|
||
buffer; the other, just the region. The commands
|
||
@code{ps-print-buffer-with-faces} and
|
||
@code{ps-print-region-with-faces} behave similarly, but use PostScript
|
||
features to show the faces (fonts and colors) of the buffer text.
|
||
|
||
Interactively, when you use a prefix argument (@kbd{C-u}), these commands
|
||
prompt the user for a file name, and save the PostScript image in that file
|
||
instead of sending it to the printer.
|
||
|
||
@findex ps-spool-region
|
||
@findex ps-spool-buffer
|
||
@findex ps-spool-region-with-faces
|
||
@findex ps-spool-buffer-with-faces
|
||
The commands whose names have @samp{spool} instead of @samp{print},
|
||
generate the PostScript output in an Emacs buffer instead of sending
|
||
it to the printer.
|
||
|
||
@findex ps-despool
|
||
Use the command @code{ps-despool} to send the spooled images to the
|
||
printer. This command sends the PostScript generated by
|
||
@samp{-spool-} commands (see commands above) to the printer. With a
|
||
prefix argument (@kbd{C-u}), it prompts for a file name, and saves the
|
||
spooled PostScript image in that file instead of sending it to the
|
||
printer.
|
||
|
||
@findex handwrite
|
||
@cindex handwriting
|
||
@kbd{M-x handwrite} is more frivolous. It generates a PostScript
|
||
rendition of the current buffer as a cursive handwritten document. It
|
||
can be customized in group @code{handwrite}. This function only
|
||
supports ISO 8859-1 characters.
|
||
|
||
@node PostScript Variables
|
||
@subsection Variables for PostScript Hardcopy
|
||
|
||
@vindex ps-lpr-command
|
||
@vindex ps-lpr-switches
|
||
@vindex ps-printer-name
|
||
All the PostScript hardcopy commands use the variables
|
||
@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
|
||
the output. @code{ps-lpr-command} specifies the command name to run,
|
||
@code{ps-lpr-switches} specifies command line options to use, and
|
||
@code{ps-printer-name} specifies the printer. If you don't set the
|
||
first two variables yourself, they take their initial values from
|
||
@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name}
|
||
is @code{nil}, @code{printer-name} is used.
|
||
|
||
@vindex ps-print-header
|
||
The variable @code{ps-print-header} controls whether these commands
|
||
add header lines to each page---set it to @code{nil} to turn headers
|
||
off.
|
||
|
||
@cindex color emulation on black-and-white printers
|
||
@vindex ps-print-color-p
|
||
If your printer doesn't support colors, you should turn off color
|
||
processing by setting @code{ps-print-color-p} to @code{nil}. By
|
||
default, if the display supports colors, Emacs produces hardcopy
|
||
output with color information; on black-and-white printers, colors are
|
||
emulated with shades of gray. This might produce barely-readable or
|
||
even illegible output, even if your screen colors only use shades of
|
||
gray.
|
||
|
||
@vindex ps-black-white-faces
|
||
Alternatively, you can set @code{ps-print-color-p} to @code{black-white}
|
||
to have colors display better on black/white printers. This works by
|
||
using information in @code{ps-black-white-faces} to express colors by
|
||
customizable list of shades of gray, augmented by bold and italic
|
||
face attributes.
|
||
|
||
@vindex ps-use-face-background
|
||
By default, PostScript printing ignores the background colors of the
|
||
faces, unless the variable @code{ps-use-face-background} is
|
||
non-@code{nil}. This is to avoid unwanted interference with the zebra
|
||
stripes and background image/text.
|
||
|
||
@vindex ps-paper-type
|
||
@vindex ps-page-dimensions-database
|
||
The variable @code{ps-paper-type} specifies which size of paper to
|
||
format for; legitimate values include @code{a4}, @code{a3},
|
||
@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger},
|
||
@code{legal}, @code{letter}, @code{letter-small}, @code{statement},
|
||
@code{tabloid}. The default is @code{letter}. You can define
|
||
additional paper sizes by changing the variable
|
||
@code{ps-page-dimensions-database}.
|
||
|
||
@vindex ps-landscape-mode
|
||
The variable @code{ps-landscape-mode} specifies the orientation of
|
||
printing on the page. The default is @code{nil}, which stands for
|
||
portrait mode. Any non-@code{nil} value specifies landscape
|
||
mode.
|
||
|
||
@vindex ps-number-of-columns
|
||
The variable @code{ps-number-of-columns} specifies the number of
|
||
columns; it takes effect in both landscape and portrait mode. The
|
||
default is 1.
|
||
|
||
@vindex ps-font-family
|
||
@vindex ps-font-size
|
||
@vindex ps-font-info-database
|
||
The variable @code{ps-font-family} specifies which font family to use
|
||
for printing ordinary text. Legitimate values include @code{Courier},
|
||
@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
|
||
@code{Times}. The variable @code{ps-font-size} specifies the size of
|
||
the font for ordinary text and defaults to 8.5 points. The value of
|
||
@code{ps-font-size} can also be a cons of 2 floats: one for landscape
|
||
mode, the other for portrait mode.
|
||
|
||
@vindex ps-multibyte-buffer
|
||
@cindex Intlfonts for PostScript printing
|
||
@cindex fonts for PostScript printing
|
||
Emacs supports more scripts and characters than a typical PostScript
|
||
printer. Thus, some of the characters in your buffer might not be
|
||
printable using the fonts built into your printer. You can augment
|
||
the fonts supplied with the printer with those from the GNU Intlfonts
|
||
package, or you can instruct Emacs to use Intlfonts exclusively. The
|
||
variable @code{ps-multibyte-buffer} controls this: the default value,
|
||
@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1
|
||
characters; a value of @code{non-latin-printer} is for printers which
|
||
have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean
|
||
characters built into them. A value of @code{bdf-font} arranges for
|
||
the BDF fonts from the Intlfonts package to be used for @emph{all}
|
||
characters. Finally, a value of @code{bdf-font-except-latin}
|
||
instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1
|
||
characters, and Intlfonts BDF fonts for the rest.
|
||
|
||
@vindex bdf-directory-list
|
||
To be able to use the BDF fonts, Emacs needs to know where to find
|
||
them. The variable @code{bdf-directory-list} holds the list of
|
||
directories where Emacs should look for the fonts; the default value
|
||
includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
|
||
|
||
Many other customization variables for these commands are defined and
|
||
described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
|
||
|
||
@node Printing Package
|
||
@subsection Printing Package
|
||
@cindex Printing package
|
||
|
||
The basic Emacs facilities for printing hardcopy can be extended
|
||
using the Printing package. This provides an easy-to-use interface
|
||
for choosing what to print, previewing PostScript files before
|
||
printing, and setting various printing options such as print headers,
|
||
landscape or portrait modes, duplex modes, and so forth. On GNU/Linux
|
||
or Unix systems, the Printing package relies on the @file{gs} and
|
||
@file{gv} utilities, which are distributed as part of the GhostScript
|
||
program. On MS-Windows, the @file{gstools} port of Ghostscript can be
|
||
used.
|
||
|
||
@findex pr-interface
|
||
To use the Printing package, add @code{(require 'printing)} to your
|
||
init file (@pxref{Init File}), followed by @code{(pr-update-menus)}.
|
||
This function replaces the usual printing commands in the menu bar
|
||
with a @samp{Printing} submenu that contains various printing options.
|
||
You can also type @kbd{M-x pr-interface @key{RET}}; this creates a
|
||
@file{*Printing Interface*} buffer, similar to a customization buffer,
|
||
where you can set the printing options. After selecting what and how
|
||
to print, you start the print job using the @samp{Print} button (click
|
||
@kbd{mouse-2} on it, or move point over it and type @key{RET}). For
|
||
further information on the various options, use the @samp{Interface
|
||
Help} button.
|
||
|
||
@node Sorting
|
||
@section Sorting Text
|
||
@cindex sorting
|
||
|
||
Emacs provides several commands for sorting text in the buffer. All
|
||
operate on the contents of the region.
|
||
They divide the text of the region into many @dfn{sort records},
|
||
identify a @dfn{sort key} for each record, and then reorder the records
|
||
into the order determined by the sort keys. The records are ordered so
|
||
that their keys are in alphabetical order, or, for numeric sorting, in
|
||
numeric order. In alphabetic sorting, all upper-case letters @samp{A}
|
||
through @samp{Z} come before lower-case @samp{a}, in accordance with the
|
||
@acronym{ASCII} character sequence (but @code{sort-fold-case},
|
||
described below, can change that).
|
||
|
||
The various sort commands differ in how they divide the text into sort
|
||
records and in which part of each record is used as the sort key. Most of
|
||
the commands make each line a separate sort record, but some commands use
|
||
paragraphs or pages as sort records. Most of the sort commands use each
|
||
entire sort record as its own sort key, but some use only a portion of the
|
||
record as the sort key.
|
||
|
||
@findex sort-lines
|
||
@findex sort-paragraphs
|
||
@findex sort-pages
|
||
@findex sort-fields
|
||
@findex sort-numeric-fields
|
||
@vindex sort-numeric-base
|
||
@table @kbd
|
||
@item M-x sort-lines
|
||
Divide the region into lines, and sort by comparing the entire
|
||
text of a line. A numeric argument means sort into descending order.
|
||
|
||
@item M-x sort-paragraphs
|
||
Divide the region into paragraphs, and sort by comparing the entire
|
||
text of a paragraph (except for leading blank lines). A numeric
|
||
argument means sort into descending order.
|
||
|
||
@item M-x sort-pages
|
||
Divide the region into pages, and sort by comparing the entire
|
||
text of a page (except for leading blank lines). A numeric
|
||
argument means sort into descending order.
|
||
|
||
@item M-x sort-fields
|
||
Divide the region into lines, and sort by comparing the contents of
|
||
one field in each line. Fields are defined as separated by
|
||
whitespace, so the first run of consecutive non-whitespace characters
|
||
in a line constitutes field 1, the second such run constitutes field
|
||
2, etc.
|
||
|
||
Specify which field to sort by with a numeric argument: 1 to sort by
|
||
field 1, etc.; the default is 1. A negative argument means count
|
||
fields from the right instead of from the left; thus, minus 1 means
|
||
sort by the last field. If several lines have identical contents in
|
||
the field being sorted, they keep the same relative order that they
|
||
had in the original buffer.
|
||
|
||
@item M-x sort-numeric-fields
|
||
Like @kbd{M-x sort-fields} except the specified field is converted
|
||
to an integer for each line, and the numbers are compared. @samp{10}
|
||
comes before @samp{2} when considered as text, but after it when
|
||
considered as a number. By default, numbers are interpreted according
|
||
to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or
|
||
@samp{0} are interpreted as hexadecimal and octal, respectively.
|
||
|
||
@item M-x sort-columns
|
||
Like @kbd{M-x sort-fields} except that the text within each line
|
||
used for comparison comes from a fixed range of columns. With a
|
||
prefix argument, sort in reverse order. See below for more details
|
||
on this command.
|
||
|
||
@findex reverse-region
|
||
@item M-x reverse-region
|
||
Reverse the order of the lines in the region. This is useful for
|
||
sorting into descending order by fields, since those sort
|
||
commands do not have a feature for doing that.
|
||
@end table
|
||
|
||
For example, if the buffer contains this:
|
||
|
||
@smallexample
|
||
On systems where clash detection (locking of files being edited) is
|
||
implemented, Emacs also checks the first time you modify a buffer
|
||
whether the file has changed on disk since it was last visited or
|
||
saved. If it has, you are asked to confirm that you want to change
|
||
the buffer.
|
||
@end smallexample
|
||
|
||
@noindent
|
||
applying @kbd{M-x sort-lines} to the entire buffer produces this:
|
||
|
||
@smallexample
|
||
On systems where clash detection (locking of files being edited) is
|
||
implemented, Emacs also checks the first time you modify a buffer
|
||
saved. If it has, you are asked to confirm that you want to change
|
||
the buffer.
|
||
whether the file has changed on disk since it was last visited or
|
||
@end smallexample
|
||
|
||
@noindent
|
||
where the upper-case @samp{O} sorts before all lower-case letters. If
|
||
you use @kbd{C-u 2 M-x sort-fields} instead, you get this:
|
||
|
||
@smallexample
|
||
implemented, Emacs also checks the first time you modify a buffer
|
||
saved. If it has, you are asked to confirm that you want to change
|
||
the buffer.
|
||
On systems where clash detection (locking of files being edited) is
|
||
whether the file has changed on disk since it was last visited or
|
||
@end smallexample
|
||
|
||
@noindent
|
||
where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
|
||
@samp{systems} and @samp{the}.
|
||
|
||
@findex sort-columns
|
||
@kbd{M-x sort-columns} requires more explanation. You specify the
|
||
columns by putting point at one of the columns and the mark at the other
|
||
column. Because this means you cannot put point or the mark at the
|
||
beginning of the first line of the text you want to sort, this command
|
||
uses an unusual definition of ``region'': all of the line point is in is
|
||
considered part of the region, and so is all of the line the mark is in,
|
||
as well as all the lines in between.
|
||
|
||
For example, to sort a table by information found in columns 10 to 15,
|
||
you could put the mark on column 10 in the first line of the table, and
|
||
point on column 15 in the last line of the table, and then run
|
||
@code{sort-columns}. Equivalently, you could run it with the mark on
|
||
column 15 in the first line and point on column 10 in the last line.
|
||
|
||
This can be thought of as sorting the rectangle specified by point and
|
||
the mark, except that the text on each line to the left or right of the
|
||
rectangle moves along with the text inside the rectangle.
|
||
@xref{Rectangles}.
|
||
|
||
@vindex sort-fold-case
|
||
Many of the sort commands ignore case differences when comparing, if
|
||
@code{sort-fold-case} is non-@code{nil}.
|
||
|
||
@c Picture Mode documentation
|
||
@ifnottex
|
||
@include picture-xtra.texi
|
||
@end ifnottex
|
||
|
||
|
||
@node Editing Binary Files
|
||
@section Editing Binary Files
|
||
|
||
@cindex Hexl mode
|
||
@cindex mode, Hexl
|
||
@cindex editing binary files
|
||
@cindex hex editing
|
||
There is a special major mode for editing binary files: Hexl mode. To
|
||
use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
|
||
the file. This command converts the file's contents to hexadecimal and
|
||
lets you edit the translation. When you save the file, it is converted
|
||
automatically back to binary.
|
||
|
||
You can also use @kbd{M-x hexl-mode} to translate an existing buffer
|
||
into hex. This is useful if you visit a file normally and then discover
|
||
it is a binary file.
|
||
|
||
Inserting text always overwrites in Hexl mode. This is to reduce
|
||
the risk of accidentally spoiling the alignment of data in the file.
|
||
Ordinary text characters insert themselves (i.e., overwrite with
|
||
themselves). There are commands for insertion of special characters
|
||
by their code. Most cursor motion keys, as well as @kbd{C-x C-s}, are
|
||
bound in Hexl mode to commands that produce the same effect. Here is
|
||
a list of other important commands special to Hexl mode:
|
||
|
||
@c I don't think individual index entries for these commands are useful--RMS.
|
||
@table @kbd
|
||
@item C-M-d
|
||
Insert a byte with a code typed in decimal.
|
||
|
||
@item C-M-o
|
||
Insert a byte with a code typed in octal.
|
||
|
||
@item C-M-x
|
||
Insert a byte with a code typed in hex.
|
||
|
||
@item C-M-a
|
||
Move to the beginning of a 512-byte page.
|
||
|
||
@item C-M-e
|
||
Move to the end of a 512-byte page.
|
||
|
||
@item C-x [
|
||
Move to the beginning of a 1k-byte page.
|
||
|
||
@item C-x ]
|
||
Move to the end of a 1k-byte page.
|
||
|
||
@item M-g
|
||
Move to an address specified in hex.
|
||
|
||
@item M-j
|
||
Move to an address specified in decimal.
|
||
|
||
@item C-c C-c
|
||
Leave Hexl mode, going back to the major mode this buffer had before you
|
||
invoked @code{hexl-mode}.
|
||
@end table
|
||
|
||
@noindent
|
||
Other Hexl commands let you insert strings (sequences) of binary
|
||
bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a
|
||
hexl- @key{TAB}} for details.
|
||
|
||
Hexl mode can also be used for editing text files. This could come
|
||
in handy if the text file includes unusual characters or uses unusual
|
||
encoding (@pxref{Coding Systems}). For this purpose, Hexl commands
|
||
that insert bytes can also insert @acronym{ASCII} and
|
||
non-@acronym{ASCII} characters, including multibyte characters. To
|
||
edit a text file with Hexl, visit the file as usual, and then type
|
||
@w{@kbd{M-x hexl-mode @key{RET}}} to switch to Hexl mode. You can now
|
||
insert text characters by typing them. However, inserting multibyte
|
||
characters requires special care, to avoid the danger of creating
|
||
invalid multibyte sequences: you should start typing such characters
|
||
when point is on the first byte of a multibyte sequence in the file.
|
||
|
||
@node Saving Emacs Sessions
|
||
@section Saving Emacs Sessions
|
||
@cindex saving sessions
|
||
@cindex restore session
|
||
@cindex remember editing session
|
||
@cindex reload files
|
||
|
||
@cindex desktop configuration
|
||
You can use the desktop library to save the state of Emacs from one
|
||
session to another. The saved Emacs @dfn{desktop configuration}
|
||
includes the buffers, their file names, major modes, buffer positions,
|
||
window and frame configuration, and some important global variables.
|
||
|
||
@vindex desktop-save-mode
|
||
@findex desktop-save-mode
|
||
To enable this feature, use the Customization buffer (@pxref{Easy
|
||
Customization}) to set @code{desktop-save-mode} to @code{t} for future
|
||
sessions, or add this line in your init file (@pxref{Init File}):
|
||
|
||
@example
|
||
(desktop-save-mode 1)
|
||
@end example
|
||
|
||
@vindex desktop-path
|
||
@vindex desktop-auto-save-timeout
|
||
If you turn on @code{desktop-save-mode} in your init file, then when
|
||
Emacs starts, it looks for a saved desktop in @code{desktop-path}
|
||
(which defaults to @code{user-emacs-directory} and then your home
|
||
directory) and uses the first desktop it finds. While Emacs runs with
|
||
@code{desktop-save-mode} turned on, it by default auto-saves the
|
||
desktop whenever any of the desktop configuration changes. The
|
||
variable @code{desktop-auto-save-timeout} determines how frequently
|
||
Emacs checks for modifications to your desktop. The desktop is also
|
||
saved when you exit Emacs.
|
||
|
||
@cindex disable restoring of desktop configuration
|
||
Specify the option @samp{--no-desktop} on the Emacs command line
|
||
when you don't want it to reload any saved desktop configurations.
|
||
This turns off @code{desktop-save-mode} for the current session.
|
||
Starting Emacs with the @samp{--no-init-file} option also disables
|
||
desktop reloading, since it bypasses the init file, where
|
||
@code{desktop-save-mode} is usually turned on.
|
||
|
||
@findex desktop-change-dir
|
||
@findex desktop-revert
|
||
You can have separate saved desktop configurations in different
|
||
directories; starting Emacs from a directory where you have a saved
|
||
desktop configuration will restore that configuration, provided that
|
||
you customize @code{desktop-path} to prepend @file{.} (the current
|
||
directory) to the other directories there. You can save the current
|
||
desktop and reload the one saved in another directory by typing
|
||
@kbd{M-x desktop-change-dir}. Typing @kbd{M-x desktop-revert} reverts
|
||
to the previously reloaded desktop.
|
||
|
||
@vindex desktop-load-locked-desktop
|
||
The file in which Emacs saves the desktop is locked while the
|
||
session runs, to avoid inadvertently overwriting it from another Emacs
|
||
session. That lock is normally removed when Emacs exits, but if Emacs
|
||
or your system crashes, the lock stays, and when you restart Emacs, it
|
||
will by default ask you whether to use the locked desktop file. You
|
||
can avoid the question by customizing the variable
|
||
@code{desktop-load-locked-desktop} to either @code{nil}, which means
|
||
never load the desktop in this case, or @code{t}, which means load the
|
||
desktop without asking. You can also customize the variable to the
|
||
special value @code{check-pid}, which means to load the file if the
|
||
Emacs process that has locked the desktop is not running on the local
|
||
machine. This should not be used in circumstances where the locking
|
||
Emacs might still be running on another machine, which could be the
|
||
case in multi-user environments where your home directory is mounted
|
||
remotely using NFS or similar.
|
||
|
||
@cindex desktop restore in daemon mode
|
||
When Emacs starts in daemon mode, it cannot ask you any questions,
|
||
so if it finds the desktop file locked, it will not load it, unless
|
||
@code{desktop-load-locked-desktop} is @code{t}. Note that restoring
|
||
the desktop in daemon mode is somewhat problematic for other reasons:
|
||
e.g., the daemon cannot use GUI features, so parameters such as frame
|
||
position, size, and decorations cannot be restored. For that reason,
|
||
you may wish to delay restoring the desktop in daemon mode until the
|
||
first client connects, by calling @code{desktop-read} (see below) in a
|
||
hook function that you add to @code{server-after-make-frame-hook}
|
||
(@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}).
|
||
|
||
@findex desktop-save
|
||
@findex desktop-read
|
||
Whenever you want, you can use the command @kbd{M-x desktop-save} to
|
||
force immediate saving of the current desktop. This is useful either
|
||
if you do not want to use the automatic desktop restoration, and thus
|
||
don't turn on @code{desktop-save-mode}, or when you have made
|
||
significant changes to the desktop, and want to make sure the
|
||
configuration doesn't get lost if Emacs or your system crashes. You
|
||
can use @kbd{M-x desktop-read} to restore a previously-saved desktop
|
||
if the current Emacs session didn't load any desktop yet.
|
||
|
||
@vindex desktop-restore-frames
|
||
By default, the desktop tries to save and restore the frame and
|
||
window configuration. To disable this, set
|
||
@code{desktop-restore-frames} to @code{nil}. (See that variable's
|
||
documentation for some related options that you can customize to
|
||
fine-tune this behavior.)
|
||
|
||
@vindex frameset-filter-alist
|
||
When the desktop restores the frame and window configuration, it
|
||
uses the recorded values of frame parameters, disregarding any
|
||
settings for those parameters you have in your init file (@pxref{Init
|
||
File}). This means that frame parameters such as fonts and faces for
|
||
the restored frames will come from the desktop file, where they were
|
||
saved when you exited your previous Emacs session; any settings for
|
||
those parameters in your init file will be ignored. To disable this,
|
||
customize the value of @code{frameset-filter-alist} to filter out the
|
||
frame parameters you don't want to be restored; they will then be set
|
||
according to your customizations in the init file.
|
||
|
||
@vindex desktop-files-not-to-save
|
||
@vindex remote-file-name-access-timeout
|
||
Information about buffers visiting remote files is not saved by
|
||
default. Customize the variable @code{desktop-files-not-to-save} to
|
||
change this. In this case, you might also consider customizing
|
||
@code{remote-file-name-access-timeout}, which is the number of
|
||
seconds after which buffer restoration of a remote file is
|
||
stopped. This prevents Emacs being blocked.
|
||
|
||
@vindex desktop-restore-eager
|
||
By default, all the buffers in the desktop are restored in one go.
|
||
However, this may be slow if there are a lot of buffers in the
|
||
desktop. You can specify the maximum number of buffers to restore
|
||
immediately with the variable @code{desktop-restore-eager}; the
|
||
remaining buffers are restored lazily, when Emacs is idle.
|
||
|
||
@findex desktop-clear
|
||
@vindex desktop-globals-to-clear
|
||
@vindex desktop-clear-preserve-buffers-regexp
|
||
Type @kbd{M-x desktop-clear} to empty the Emacs desktop; this can be
|
||
useful, for example, if you want to switch to another desktop by
|
||
invoking @kbd{M-x desktop-read} next. The @code{desktop-clear}
|
||
command kills all buffers except for internal ones, and clears the
|
||
global variables listed in @code{desktop-globals-to-clear}. If you
|
||
want it to preserve certain buffers, customize the variable
|
||
@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
|
||
expression matching the names of buffers not to kill.
|
||
|
||
@vindex desktop-globals-to-save
|
||
If you want to save minibuffer history from one session to
|
||
another, use the @code{savehist} library. You can also save selected
|
||
minibuffer-history variables as part of @code{desktop-save-mode} if
|
||
you add those variables to the value of @code{desktop-globals-to-save}.
|
||
|
||
@node Recursive Edit
|
||
@section Recursive Editing Levels
|
||
@cindex recursive editing level
|
||
@cindex editing level, recursive
|
||
|
||
A @dfn{recursive edit} is a situation in which you are using Emacs
|
||
commands to perform arbitrary editing while in the middle of another
|
||
Emacs command. For example, when you type @kbd{C-r} inside of a
|
||
@code{query-replace}, you enter a recursive edit in which you can change
|
||
the current buffer. On exiting from the recursive edit, you go back to
|
||
the @code{query-replace}. @xref{Query Replace}.
|
||
|
||
@kindex C-M-c
|
||
@findex exit-recursive-edit
|
||
@cindex exiting recursive edit
|
||
@dfn{Exiting} the recursive edit means returning to the unfinished
|
||
command, which continues execution. The command to exit is @kbd{C-M-c}
|
||
(@code{exit-recursive-edit}).
|
||
|
||
You can also @dfn{abort} the recursive edit. This is like exiting,
|
||
but also quits the unfinished command immediately. Use the command
|
||
@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}.
|
||
|
||
The mode line shows you when you are in a recursive edit by displaying
|
||
square brackets around the parentheses that always surround the major and
|
||
minor mode names. Every window's mode line shows this in the same way,
|
||
since being in a recursive edit is true of Emacs as a whole rather than
|
||
any particular window or buffer.
|
||
|
||
It is possible to be in recursive edits within recursive edits. For
|
||
example, after typing @kbd{C-r} in a @code{query-replace}, you may type a
|
||
command that enters the debugger. This begins a recursive editing level
|
||
for the debugger, within the recursive editing level for @kbd{C-r}.
|
||
Mode lines display a pair of square brackets for each recursive editing
|
||
level currently in progress.
|
||
|
||
Exiting the inner recursive edit (such as with the debugger @kbd{c}
|
||
command) resumes the command running in the next level up. When that
|
||
command finishes, you can then use @kbd{C-M-c} to exit another recursive
|
||
editing level, and so on. Exiting applies to the innermost level only.
|
||
Aborting also gets out of only one level of recursive edit; it returns
|
||
immediately to the command level of the previous recursive edit. If you
|
||
wish, you can then abort the next recursive editing level.
|
||
|
||
Alternatively, the command @kbd{M-x top-level} aborts all levels of
|
||
recursive edits, returning immediately to the top-level command
|
||
reader. It also exits the minibuffer, if it is active.
|
||
|
||
The text being edited inside the recursive edit need not be the same text
|
||
that you were editing at top level. It depends on what the recursive edit
|
||
is for. If the command that invokes the recursive edit selects a different
|
||
buffer first, that is the buffer you will edit recursively. In any case,
|
||
you can switch buffers within the recursive edit in the normal manner (as
|
||
long as the buffer-switching keys have not been rebound). You could
|
||
probably do all the rest of your editing inside the recursive edit,
|
||
visiting files and all. But this could have surprising effects (such as
|
||
stack overflow) from time to time. So remember to exit or abort the
|
||
recursive edit when you no longer need it.
|
||
|
||
In general, we try to minimize the use of recursive editing levels in
|
||
GNU Emacs. This is because they constrain you to go back in a
|
||
particular order---from the innermost level toward the top level. When
|
||
possible, we present different activities in separate buffers so that
|
||
you can switch between them as you please. Some commands switch to a
|
||
new major mode which provides a command to switch back. These
|
||
approaches give you more flexibility to go back to unfinished tasks in
|
||
the order you choose.
|
||
|
||
|
||
@node Hyperlinking
|
||
@section Hyperlinking and Web Navigation Features
|
||
|
||
The following subsections describe convenience features for handling
|
||
URLs and other types of links occurring in Emacs buffer text.
|
||
|
||
@menu
|
||
* EWW:: A web browser in Emacs.
|
||
* Embedded WebKit Widgets:: Embedding browser widgets in Emacs buffers.
|
||
* Browse-URL:: Following URLs.
|
||
* Goto Address mode:: Activating URLs.
|
||
* FFAP:: Finding files etc. at point.
|
||
@end menu
|
||
|
||
@node EWW
|
||
@subsection Web Browsing with EWW
|
||
|
||
@findex eww
|
||
@findex eww-open-file
|
||
@dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs.
|
||
It allows browsing URLs within an Emacs buffer. The command @kbd{M-x
|
||
eww} will open a URL or search the web. You can open a file
|
||
using the command @kbd{M-x eww-open-file}. You can use EWW as the
|
||
web browser for @code{browse-url}, @pxref{Browse-URL}. For full
|
||
details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
|
||
|
||
@node Embedded WebKit Widgets
|
||
@subsection Embedded WebKit Widgets
|
||
@cindex xwidget
|
||
@cindex webkit widgets
|
||
@cindex embedded widgets
|
||
|
||
@findex xwidget-webkit-browse-url
|
||
@findex xwidget-webkit-mode
|
||
@cindex Xwidget-WebKit mode
|
||
If Emacs was compiled with the appropriate support packages, it is
|
||
able to show browser widgets in its buffers. The command @kbd{M-x
|
||
xwidget-webkit-browse-url} asks for a URL to display in the browser
|
||
widget. The URL normally defaults to the URL at or before point, but
|
||
if there is an active region (@pxref{Mark}), the default URL comes
|
||
from the region instead, after removing any whitespace from it. The
|
||
command then creates a new buffer with the embedded browser showing
|
||
the specified URL@. The buffer is put in the Xwidget-WebKit mode
|
||
(similar to Image mode, @pxref{Image Mode}), which provides
|
||
one-key commands for scrolling the widget, changing its size, and
|
||
reloading it. Type @w{@kbd{C-h b}} in that buffer to see the key
|
||
bindings.
|
||
|
||
@findex xwidget-webkit-edit-mode
|
||
@cindex xwidget-webkit-edit-mode
|
||
By default, typing a self-inserting character inside an xwidget
|
||
webkit buffer will do nothing, or trigger some special action. To
|
||
make those characters and other common editing keys insert themselves
|
||
when pressed, you can enable @code{xwidget-webkit-edit-mode}, which
|
||
redefines them to be passed through to the WebKit xwidget.
|
||
|
||
You can also enable @code{xwidget-webkit-edit-mode} by typing @kbd{e}
|
||
inside the xwidget webkit buffer.
|
||
|
||
@findex xwidget-webkit-isearch-mode
|
||
@cindex searching in webkit buffers
|
||
@code{xwidget-webkit-isearch-mode} is a minor mode that behaves
|
||
similarly to incremental search (@pxref{Incremental Search}), but
|
||
operates on the contents of a WebKit widget instead of the current
|
||
buffer. It is bound to @kbd{C-s} and @kbd{C-r} inside xwidget-webkit
|
||
buffers. When it is invoked by @kbd{C-r}, the initial search will be
|
||
performed in reverse direction.
|
||
|
||
Typing any self-inserting character will cause the character to be
|
||
inserted into the current search query. Typing @kbd{C-s} will cause
|
||
the WebKit widget to display the next search result, while typing
|
||
@kbd{C-r} will cause it to display the previous one.
|
||
|
||
To leave incremental search, you can type @kbd{C-g}.
|
||
|
||
@findex xwidget-webkit-browse-history
|
||
@cindex history of webkit buffers
|
||
The command @code{xwidget-webkit-browse-history} displays a buffer
|
||
containing a list of pages previously loaded by the current WebKit
|
||
buffer, and lets you navigate to those pages by hitting @kbd{RET}.
|
||
|
||
It is bound to @kbd{H}.
|
||
|
||
@vindex xwidget-webkit-disable-javascript
|
||
@cindex disabling javascript in webkit buffers
|
||
JavaScript is enabled by default inside WebKit buffers, which could be
|
||
undesirable, as Web sites often use it to track your online activity.
|
||
You can disable JavaScript in WebKit buffers by customizing the variable
|
||
@code{xwidget-webkit-disable-javascript} to a non-@code{nil} value.
|
||
You must kill all WebKit buffers for this setting to take effect, after
|
||
it is changed.
|
||
|
||
@node Browse-URL
|
||
@subsection Following URLs
|
||
@cindex World Wide Web
|
||
@cindex Web
|
||
@findex browse-url
|
||
@findex browse-url-at-point
|
||
@findex browse-url-at-mouse
|
||
@cindex Browse-URL
|
||
@cindex URLs
|
||
|
||
@table @kbd
|
||
@item M-x browse-url @key{RET} @var{url} @key{RET}
|
||
Load a URL into a Web browser.
|
||
@end table
|
||
|
||
The Browse-URL package allows you to easily follow URLs from within
|
||
Emacs. Most URLs are followed by invoking a web browser;
|
||
@samp{mailto:} URLs are followed by invoking the @code{compose-mail}
|
||
Emacs command to send mail to the specified address (@pxref{Sending
|
||
Mail}).
|
||
|
||
The command @kbd{M-x browse-url} prompts for a URL, and follows it.
|
||
If point is located near a plausible URL, that URL is offered as the
|
||
default. The Browse-URL package also provides other commands which
|
||
you might like to bind to keys, such as @code{browse-url-at-point} and
|
||
@code{browse-url-at-mouse}.
|
||
|
||
@vindex browse-url-mailto-function
|
||
@vindex browse-url-browser-function
|
||
You can customize Browse-URL's behavior via various options in the
|
||
@code{browse-url} Customize group. In particular, the option
|
||
@code{browse-url-mailto-function} lets you define how to follow
|
||
@samp{mailto:} URLs, while @code{browse-url-browser-function}
|
||
specifies your default browser.
|
||
|
||
@vindex browse-url-handlers
|
||
You can define that certain URLs are browsed with other functions by
|
||
customizing @code{browse-url-handlers}, an alist of regular
|
||
expressions or predicates paired with functions to browse matching
|
||
URLs.
|
||
|
||
For more information, view the package commentary by typing @kbd{C-h P
|
||
browse-url @key{RET}}.
|
||
|
||
@findex url-handler-mode
|
||
Emacs also has a minor mode that has some support for handling
|
||
@acronym{URL}s as if they were files. @code{url-handler-mode} is a
|
||
global minor mode that affects most of the Emacs commands and
|
||
primitives that deal with file names. After switching on this mode,
|
||
you can say, for instance, @kbd{C-x C-f https://www.gnu.org/ RET} to
|
||
see the @acronym{HTML} for that web page, and you can then edit it and
|
||
save it to a local file, for instance.
|
||
|
||
@node Goto Address mode
|
||
@subsection Activating URLs
|
||
@findex goto-address-mode
|
||
@cindex mode, Goto Address
|
||
@cindex Goto Address mode
|
||
@cindex URLs, activating
|
||
|
||
@table @kbd
|
||
@item M-x goto-address-mode
|
||
Activate URLs and e-mail addresses in the current buffer.
|
||
|
||
@item M-x global-goto-address-mode
|
||
Activate @code{goto-address-mode} in all buffers.
|
||
@end table
|
||
|
||
@kindex C-c RET @r{(Goto Address mode)}
|
||
@findex goto-address-at-point
|
||
You can make Emacs mark out URLs specially in the current buffer, by
|
||
typing @kbd{M-x goto-address-mode}. When this buffer-local minor mode
|
||
is enabled, it finds all the URLs in the buffer, highlights them, and
|
||
turns them into clickable buttons. You can follow the URL by typing
|
||
@kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on
|
||
its text; or by clicking with @kbd{mouse-2}, or by clicking
|
||
@kbd{mouse-1} quickly (@pxref{Mouse References}). Following a URL is
|
||
done by calling @code{browse-url} as a subroutine
|
||
(@pxref{Browse-URL}).
|
||
|
||
It can be useful to add @code{goto-address-mode} to mode hooks and
|
||
hooks for displaying an incoming message
|
||
(e.g., @code{rmail-show-message-hook} for Rmail). This is not needed
|
||
for Gnus or MH-E, which have similar features of their own.
|
||
|
||
@node FFAP
|
||
@subsection Finding Files and URLs at Point
|
||
@findex find-file-at-point
|
||
@findex ffap
|
||
@findex dired-at-point
|
||
@findex ffap-next
|
||
@findex ffap-menu
|
||
@cindex finding file at point
|
||
|
||
The FFAP package replaces certain key bindings for finding files,
|
||
such as @kbd{C-x C-f}, with commands that provide more sensible
|
||
defaults. These commands behave like the ordinary ones when given a
|
||
prefix argument. Otherwise, they get the default file name or URL
|
||
from the text around point. If what is found in the buffer has the
|
||
form of a URL rather than a file name, the commands use
|
||
@code{browse-url} to view it (@pxref{Browse-URL}).
|
||
|
||
This feature is useful for following references in mail or news
|
||
buffers, @file{README} files, @file{MANIFEST} files, and so on. For
|
||
more information, view the package commentary by typing @kbd{C-h P
|
||
ffap @key{RET}}.
|
||
|
||
@cindex FFAP minor mode
|
||
@findex ffap-mode
|
||
To enable FFAP, type @kbd{M-x ffap-bindings}. This makes the
|
||
following key bindings, and also installs hooks for additional FFAP
|
||
functionality in Rmail, Gnus and VM article buffers.
|
||
|
||
@table @kbd
|
||
@item C-x C-f @var{filename} @key{RET}
|
||
@kindex C-x C-f @r{(FFAP)}
|
||
Find @var{filename}, guessing a default from text around point
|
||
(@code{find-file-at-point}).
|
||
@item C-x C-r @var{filename} @key{RET}
|
||
@kindex C-x C-r @r{(FFAP)}
|
||
@code{ffap-read-only}, analogous to @code{find-file-read-only}.
|
||
@item C-x C-v @var{filename} @key{RET}
|
||
@kindex C-x C-v @r{(FFAP)}
|
||
@code{ffap-alternate-file}, analogous to @code{find-alternate-file}.
|
||
@item C-x d @var{directory} @key{RET}
|
||
@kindex C-x d @r{(FFAP)}
|
||
Start Dired on @var{directory}, defaulting to the directory at
|
||
point (@code{dired-at-point}).
|
||
@item C-x C-d @var{directory} @key{RET}
|
||
@code{ffap-list-directory}, analogous to @code{list-directory}.
|
||
@item C-x 4 f @var{filename} @key{RET}
|
||
@kindex C-x 4 f @r{(FFAP)}
|
||
@code{ffap-other-window}, analogous to @code{find-file-other-window}.
|
||
@item C-x 4 r @var{filename} @key{RET}
|
||
@code{ffap-read-only-other-window}, analogous to
|
||
@code{find-file-read-only-other-window}.
|
||
@item C-x 4 d @var{directory} @key{RET}
|
||
@code{ffap-dired-other-window}, like @code{dired-other-window}.
|
||
@item C-x 5 f @var{filename} @key{RET}
|
||
@kindex C-x 5 f @r{(FFAP)}
|
||
@code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
|
||
@item C-x 5 r @var{filename} @key{RET}
|
||
@code{ffap-read-only-other-frame}, analogous to
|
||
@code{find-file-read-only-other-frame}.
|
||
@item C-x 5 d @var{directory} @key{RET}
|
||
@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}.
|
||
@kindex C-x t C-f @r{(FFAP)}
|
||
@item C-x t C-f @var{filename} @key{return}
|
||
@code{ffap-other-tab}, analogous to @code{find-file-other-tab}.
|
||
@item C-x t C-r @var{filename} @key{return}
|
||
@code{ffap-read-only-other-tab}, analogous to @code{find-file-read-only-other-tab}.
|
||
@item M-x ffap-next
|
||
Search buffer for next file name or URL, then find that file or URL.
|
||
@item S-mouse-3
|
||
@kindex S-mouse-3 @r{(FFAP)}
|
||
@code{ffap-at-mouse} finds the file guessed from text around the position
|
||
of a mouse click.
|
||
@item C-S-mouse-3
|
||
@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 Amusements
|
||
@section Games and Other Amusements
|
||
@cindex boredom
|
||
@cindex games
|
||
|
||
@findex animate-birthday-present
|
||
@cindex animate
|
||
The @code{animate} package makes text dance (e.g., @kbd{M-x
|
||
animate-birthday-present}).
|
||
|
||
@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.
|
||
|
||
@findex bubbles
|
||
@cindex bubbles
|
||
@kbd{M-x bubbles} is a game in which the object is to remove as many
|
||
bubbles as you can in the smallest number of moves.
|
||
|
||
@findex decipher
|
||
@cindex ciphers
|
||
@cindex cryptanalysis
|
||
@kbd{M-x decipher} helps you to cryptanalyze a buffer which is
|
||
encrypted in a simple monoalphabetic substitution cipher.
|
||
|
||
@findex dissociated-press
|
||
@kbd{M-x dissociated-press} scrambles the text in the current Emacs
|
||
buffer, word by word or character by character, writing its output to
|
||
a buffer named @file{*Dissociation*}. A positive argument 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. Dissociated Press produces
|
||
results fairly like those of a Markov chain, but is however, an
|
||
independent, ignoriginal invention; it techniquitously copies several
|
||
consecutive characters from the sample text between random jumps,
|
||
unlike a Markov chain which would jump randomly after each word or
|
||
character. Keep dissociwords out of your documentation, if you want
|
||
it to be well userenced and properbose.
|
||
|
||
@findex dunnet
|
||
@cindex dunnet
|
||
@kbd{M-x dunnet} runs a text-based adventure game.
|
||
|
||
@findex gomoku
|
||
@cindex Go Moku
|
||
If you want a little more personal involvement, try @kbd{M-x gomoku},
|
||
which plays the game Go Moku with you.
|
||
|
||
@cindex tower of Hanoi
|
||
@findex hanoi
|
||
If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
|
||
considerably bored, give it a numeric argument. If you are very, very
|
||
bored, try an argument of 9. Sit back and watch.
|
||
|
||
@findex life
|
||
@cindex Life
|
||
@kbd{M-x life} runs Conway's Game of Life cellular automaton.
|
||
|
||
@findex morse-region
|
||
@findex unmorse-region
|
||
@findex nato-region
|
||
@cindex Morse code
|
||
@cindex --/---/.-./.../.
|
||
@kbd{M-x morse-region} converts the text in the region to Morse
|
||
code; @kbd{M-x unmorse-region} converts it back. @kbd{M-x
|
||
nato-region} converts the text in the region to NATO phonetic
|
||
alphabet; @kbd{M-x denato-region} converts it back.
|
||
|
||
@findex pong
|
||
@cindex Pong game
|
||
@findex tetris
|
||
@cindex Tetris
|
||
@findex snake
|
||
@cindex Snake
|
||
@kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are
|
||
implementations of the well-known Pong, Snake and Tetris games.
|
||
|
||
@findex solitaire
|
||
@cindex solitaire
|
||
@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
|
||
across other pegs.
|
||
|
||
@findex zone
|
||
@cindex zone
|
||
The command @kbd{M-x zone} plays games with the display when Emacs
|
||
is idle.
|
||
|
||
@findex butterfly
|
||
@cindex butterfly
|
||
``Real Programmers'' deploy @kbd{M-x butterfly}, which uses butterflies
|
||
to flip a bit on the drive platter, see @uref{https://xkcd.com/378}.
|
||
|
||
@findex doctor
|
||
@cindex Eliza
|
||
Finally, if you find yourself frustrated, try describing your
|
||
problems to the famous psychotherapist Eliza. Just do @kbd{M-x
|
||
doctor}. End each input by typing @key{RET} twice.
|
||
|
||
@ifnottex
|
||
@lowersections
|
||
@end ifnottex
|