@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
+@c 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 netnews, running shell commands and shell subprocesses,
-using a single shared Emacs for utilities that expect to run an editor
-as a subprocess, printing hardcopy, sorting text, narrowing display to
-part of the buffer, editing double-column files and binary files,
-saving an Emacs session for later resumption, following hyperlinks,
-browsing images, emulating other editors, and various diversions and
-amusements.
+else: viewing ``document files'', reading Usenet news, running shell
+commands and shell subprocesses, using a single shared Emacs for
+utilities that expect to run an editor as a subprocess, printing
+hardcopy, sorting text, narrowing display to part of the buffer,
+editing binary files, saving an Emacs session for later resumption,
+following hyperlinks, browsing images, emulating other editors, and
+various diversions and amusements.
@end iftex
@raisesections
@end ifnottex
-@node Gnus, Shell, Calendar/Diary, Top
+@node Gnus
@section Gnus
@cindex Gnus
-@cindex reading netnews
+@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---mail, remote directories, digests, and so on.
-
-Here we introduce Gnus and describe several basic features.
+ 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{M-x info} and then select the Gnus
+For full details on Gnus, type @kbd{C-h i} and then select the Gnus
manual.
@end iftex
-@findex gnus
-To start Gnus, type @kbd{M-x gnus @key{RET}}.
-
@menu
-* Buffers of Gnus:: The group, summary, and article buffers.
-* Gnus Startup:: What you should know about starting Gnus.
-* Summary of Gnus:: A short description of the basic Gnus commands.
+* 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
-Unlike most Emacs packages, Gnus uses several buffers to display
-information and to receive commands. The three Gnus buffers users use
-most are the @dfn{group buffer}, the @dfn{summary buffer} and the
-@dfn{article buffer}.
-
-The @dfn{group buffer} contains a list of newsgroups. This is the
-first buffer Gnus displays when it starts up. It normally displays
-only the groups to which you subscribe and that contain unread
-articles. Use this buffer to select a specific group.
-
-The @dfn{summary buffer} lists one line for each article in a single
-group. By default, the author, the subject and the line number are
-displayed for each article, but this is customizable, like most aspects
-of Gnus display. The summary buffer is created when you select a group
-in the group buffer, and is killed when you exit the group. Use this
-buffer to select an article.
-
-The @dfn{article buffer} displays the article. In normal Gnus usage,
-you see this buffer but you don't select it---all useful
-article-oriented commands work in the summary buffer. But you can
-select the article buffer, and execute all Gnus commands from that
-buffer, if you want to.
+ 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
-At startup, Gnus reads your @file{.newsrc} news initialization file
-and attempts to communicate with the local news server, which is a
-repository of news articles. The news server need not be the same
-computer you are logged in on.
-
-If you start Gnus and connect to the server, but do not see any
-newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get
-a listing of all the groups. Then type @kbd{u} to toggle
-subscription to groups.
-
-The first time you start Gnus, Gnus subscribes you to a few selected
-groups. All other groups start out as @dfn{killed groups} for you; you
-can list them with @kbd{A k}. All new groups that subsequently come to
-exist at the news server become @dfn{zombie groups} for you; type @kbd{A
-z} to list them. You can subscribe to a group shown in these lists
-using the @kbd{u} command.
-
-When you quit Gnus with @kbd{q}, it automatically records in your
-@file{.newsrc} and @file{.newsrc.eld} initialization files the
-subscribed or unsubscribed status of all groups. You should normally
-not edit these files manually, but you may if you know how.
+@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 @samp{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
-@node Summary of Gnus
-@subsection Summary of Gnus Commands
+ 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.
-Reading news is a two-step process:
+ 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.
-@enumerate
-@item
-Choose a group in the group buffer.
+ 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.
-@item
-Select articles from the summary buffer. Each article selected is
-displayed in the article buffer in a large window, below the summary
-buffer in its small window.
-@end enumerate
+@node Gnus Group Buffer
+@subsection Using the Gnus Group Buffer
- Each Gnus buffer has its own special commands; the meanings of any
-given key in the various Gnus buffers are usually analogous, even if
-not identical. Here are commands for the group and summary buffers:
+ The following commands are available in the Gnus group buffer:
@table @kbd
-@kindex q @r{(Gnus Group mode)}
-@findex gnus-group-exit
-@item q
-In the group buffer, update your @file{.newsrc} initialization file
-and quit Gnus.
+@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.
-In the summary buffer, exit the current group and return to the
-group buffer. Thus, typing @kbd{q} twice quits Gnus.
+@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 (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
-In the group buffer, list all the groups available on your news
-server (except those you have killed). This may be a long list!
+@itemx A u
+List all subscribed and unsubscribed groups, but not killed or zombie
+groups.
-@kindex l @r{(Gnus Group mode)}
-@findex gnus-group-list-groups
-@item l
-In the group buffer, list only the groups to which you subscribe and
-which contain unread articles.
+@kindex A k @r{(Gnus Group mode)}
+@findex gnus-group-list-all-groups
+@item A k
+List killed groups.
+
+@kindex A z @r{(Gnus Group mode)}
+@findex gnus-group-list-all-groups
+@item A z
+List zombie groups.
@kindex u @r{(Gnus Group mode)}
@findex gnus-group-unsubscribe-current-group
@cindex subscribe groups
@cindex unsubscribe groups
@item u
-In the group buffer, unsubscribe from (or subscribe to) the group listed
-in the line that point is on. When you quit Gnus by typing @kbd{q},
-Gnus lists in your @file{.newsrc} file which groups you have subscribed
-to. The next time you start Gnus, you won't see this group,
-because Gnus normally displays only subscribed-to groups.
+Toggle the subscription status of the group on the current line
+(i.e.@: turn a subscribed group into an unsubscribed group, or vice
+versa). Invoking this on a killed or zombie group turns it into an
+unsubscribed group.
-@kindex C-k @r{(Gnus)}
+@kindex C-k @r{(Gnus Group mode)}
@findex gnus-group-kill-group
@item C-k
-In the group buffer, ``kill'' the current line's group---don't
-even list it in @file{.newsrc} from now on. This affects future
-Gnus sessions as well as the present session.
+Kill the group on the current line. Killed groups are not recorded in
+the @file{.newsrc} file, and they are not shown in the @kbd{l} or
+@kbd{L} listings.
-When you quit Gnus by typing @kbd{q}, Gnus writes information
-in the file @file{.newsrc} describing all newsgroups except those you
-have ``killed.''
+@kindex DEL @r{(Gnus Group mode)}
+@item @key{DEL}
+Move point to the previous group containing unread articles.
-@kindex SPC @r{(Gnus)}
-@findex gnus-group-read-group
-@item @key{SPC}
-In the group buffer, select the group on the line under the cursor
-and display the first unread article in that group.
+@kindex n @r{(Gnus Group mode)}
+@findex gnus-group-next-unread-group
+@findex gnus-summary-next-unread-article
+@item n
+Move point to the next unread group.
-@need 1000
-In the summary buffer,
+@kindex p @r{(Gnus Group mode)}
+@findex gnus-group-prev-unread-group
+@findex gnus-summary-prev-unread-article
+@item p
+Move point to the previous unread group.
-@itemize @bullet
-@item
-Select the article on the line under the cursor if none is selected.
+@kindex q @r{(Gnus Group mode)}
+@findex gnus-group-exit
+@item q
+Update your Gnus settings, and quit Gnus.
+@end table
-@item
-Scroll the text of the selected article (if there is one).
+@node Gnus Summary Buffer
+@subsection Using the Gnus Summary Buffer
-@item
-Select the next unread article if at the end of the current article.
-@end itemize
+ The following commands are available in the Gnus summary buffer:
-Thus, you can move through all the articles by repeatedly typing @key{SPC}.
+@table @kbd
+@kindex SPC @r{(Gnus Summary mode)}
+@findex gnus-group-read-group
+@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.
-@kindex DEL @r{(Gnus)}
-@item @key{DEL}
-In the group buffer, move point to the previous group containing
-unread articles.
+Thus, you can read through all articles by repeatedly typing
+@key{SPC}.
+@kindex DEL @r{(Gnus Summary mode)}
@findex gnus-summary-prev-page
-In the summary buffer, scroll the text of the article backwards.
+@item @key{DEL}
+Scroll the text of the article backwards.
-@kindex n @r{(Gnus)}
+@kindex n @r{(Gnus Summary mode)}
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
-Move point to the next unread group, or select the next unread article.
+Select the next unread article.
-@kindex p @r{(Gnus)}
+@kindex p @r{(Gnus Summary mode)}
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
-Move point to the previous unread group, or select the previous
-unread article.
-
-@kindex C-n @r{(Gnus Group mode)}
-@findex gnus-group-next-group
-@kindex C-p @r{(Gnus Group mode)}
-@findex gnus-group-prev-group
-@kindex C-n @r{(Gnus Summary mode)}
-@findex gnus-summary-next-subject
-@kindex C-p @r{(Gnus Summary mode)}
-@findex gnus-summary-prev-subject
-@item C-n
-@itemx C-p
-Move point to the next or previous item, even if it is marked as read.
-This does not select the article or group on that line.
+Select the previous unread article.
@kindex s @r{(Gnus Summary mode)}
@findex gnus-summary-isearch-article
@item s
-In the summary buffer, do an incremental search of the current text in
-the article buffer, just as if you switched to the article buffer and
-typed @kbd{C-s}.
+Do an incremental search on the selected article buffer, as if you
+switched to the buffer and typed @kbd{C-s} (@pxref{Incremental
+Search}).
@kindex M-s @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-forward
@item M-s @var{regexp} @key{RET}
-In the summary buffer, search forward for articles containing a match
-for @var{regexp}.
+Search forward for articles containing a match for @var{regexp}.
+@kindex q @r{(Gnus Summary mode)}
+@item q
+Exit the summary buffer and return to the group buffer.
@end table
-@ignore
-@node Where to Look
-@subsection Where to Look Further
-
-@c Too many references to the name of the manual if done with xref in TeX!
-Gnus is powerful and customizable. Here are references to a few
-@ifnottex
-additional topics:
-
-@end ifnottex
-@iftex
-additional topics in @cite{The Gnus Manual}:
-
-@itemize @bullet
-@item
-Follow discussions on specific topics.@*
-See section ``Threading.''
-
-@item
-Read digests. See section ``Document Groups.''
-
-@item
-Refer to and jump to the parent of the current article.@*
-See section ``Finding the Parent.''
-
-@item
-Refer to articles by using Message-IDs included in the messages.@*
-See section ``Article Keymap.''
-
-@item
-Save articles. See section ``Saving Articles.''
-
-@item
-Have Gnus score articles according to various criteria, like author
-name, subject, or string in the body of the articles.@*
-See section ``Scoring.''
-
-@item
-Send an article to a newsgroup.@*
-See section ``Composing Messages.''
-@end itemize
-@end iftex
-@ifnottex
-@itemize @bullet
-@item
-Follow discussions on specific topics.@*
-@xref{Threading, , Reading Based on Conversation Threads,
-gnus, The Gnus Manual}.
-
-@item
-Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}.
-
-@item
-Refer to and jump to the parent of the current article.@*
-@xref{Finding the Parent, , , gnus, The Gnus Manual}.
-
-@item
-Refer to articles by using Message-IDs included in the messages.@*
-@xref{Article Keymap, , , gnus, The Gnus Manual}.
-
-@item
-Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}.
-
-@item
-Have Gnus score articles according to various criteria, like author
-name, subject, or string in the body of the articles.@*
-@xref{Scoring, , , gnus, The Gnus Manual}.
+@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 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, and Microsoft Office 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) command and other external tools @footnote{@code{gs} is
+a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} is
+needed. For OpenDocument and Microsoft Office documents, the
+@code{unoconv} tool is needed.}, and displaying those images.
+
+@findex doc-view-toggle-display
+@findex doc-view-toggle-display
+@cindex doc-view-minor-mode
+ When you visit a document file that can be displayed with DocView
+mode, Emacs automatically uses DocView 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 any of
+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.
+
+ You can explicitly enable DocView mode with the command @code{M-x
+doc-view-mode}. You can toggle DocView minor mode with @code{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}).
-@item
-Send an article to a newsgroup.@*
-@xref{Composing Messages, , , gnus, The Gnus Manual}.
-@end itemize
-@end ifnottex
-@end ignore
+@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 Shell, Emacs Server, Gnus, Top
+@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 C-x ] @r{(DocView mode)}
+@kindex C-x [ @r{(DocView mode)}
+ You can also display the next page by typing @kbd{n}, @key{next} or
+@kbd{C-x ]} (@code{doc-view-next-page}). To display the previous
+page, type @kbd{p}, @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
+@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}). These
+commands work by reconverting the document at the new size. To
+specify the default size for DocView, customize the variable
+@code{doc-view-resolution}.
+
+@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{s 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{s
+m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
+select the slice.
+@c ??? How does this work?
+
+@findex doc-view-reset-slice
+ To cancel the selected slice, type @kbd{s 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 this directory is given by the variable
+@code{doc-view-cache-directory}. You can clear the cache directory by
+typing @code{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 inferior shell
-processes; it can also run a shell interactively with input and output
-to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
+ 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 line @var{cmd} and display the output
+Run the shell command @var{cmd} and display the output
(@code{shell-command}).
@item M-| @var{cmd} @key{RET}
-Run the shell command line @var{cmd} with region contents as input;
+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.
+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.
+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 directory names; 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 a separate manual. @xref{Top,Eshell,Eshell, eshell,
-Eshell: The Emacs Shell}.
+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.
* 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.
-* Paging in Term:: Paging in the terminal emulator.
* Remote Host:: Connecting to another computer.
+* Serial Terminal:: Connecting to a serial port.
@end menu
@node Single Shell
@kindex M-!
@findex shell-command
@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
+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 an Emacs buffer named
-@samp{*Shell Command Output*}, which is displayed in another window
-but not selected (if the output is long).
-
- For instance, one way to decompress a file @file{foo.gz} from Emacs
-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, as in @kbd{M-1 M-!}, says to insert terminal
-output into the current buffer instead of a separate buffer. It puts
-point before the output, and sets the mark after the output. For
-instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
-uncompressed equivalent of @file{foo.gz} into the current buffer.
-
- If the shell command line ends in @samp{&}, it runs asynchronously.
-For a synchronous shell command, @code{shell-command} returns the
-command's exit status (0 means success), when it is called from a Lisp
-program. You do not get any status information for an asynchronous
-command, since it hasn't finished yet when @code{shell-command} returns.
+@samp{*Shell Command Output*}, displayed in another window (if the
+output is long).
+
+ 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. It puts point before the output, and sets the mark
+after the output. 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
+ 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 buffer for asynchronous shell commands is named
+@samp{*Async Shell Command*}. Emacs inserts the output into this
+buffer as it comes in, whether or not the buffer is visible in a
+window.
@kindex M-|
@findex shell-command-on-region
- @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
+ @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
passes the contents of the region as the standard input to the shell
-command, instead of no input. With a numeric argument, meaning insert
-the output in the current buffer, it deletes the old region and the
-output replaces it as the contents of the region. It returns the
-command's exit status, like @kbd{M-!}.
-
- One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
-the buffer. For instance, if the buffer contains a GPG key, type
-@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to
-the @code{gpg} program. That program will ignore everything except
-the encoded keys, and will output a list of the keys the buffer
-contains.
+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
+@samp{*Shell Command Output*} buffer.
@vindex shell-file-name
- Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify
-the shell to use. This variable is initialized based on your
+ 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 in the list
-@code{exec-path}; this list is initialized based on the environment
-variable @env{PATH} when Emacs is started. Your @file{.emacs} file
-can override either or both of these default initializations.
-
- Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
-unless you end the command with @samp{&} to make it asynchronous. To
-stop waiting, type @kbd{C-g} to quit; that terminates the shell
-command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
-normally generates in the shell. Emacs then waits until the command
-actually terminates. If the shell command doesn't stop (because it
-ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
-the command a @code{SIGKILL} signal which is impossible to ignore.
-
- Asynchronous commands ending in @samp{&} feed their output into
-the buffer @samp{*Async Shell Command*}. Output arrives in that
-buffer regardless of whether it is visible in a window.
+name is relative, Emacs searches the directories listed in
+@code{exec-path} (@pxref{Shell}).
To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}.
@vindex shell-command-default-error-buffer
- Error output from these commands is normally intermixed with the
-regular output. But if the variable
-@code{shell-command-default-error-buffer} has a string as value, and
-it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output
-before point in that buffer.
+ 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.
@node Interactive Shell
-@subsection Interactive Inferior Shell
+@subsection Interactive Subshell
@findex shell
- To run a subshell interactively, putting its typescript in an Emacs
-buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
-@samp{*shell*} and runs a subshell 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}.
-
- Emacs does not wait for the subshell to do anything. You can switch
-windows or buffers and edit them while the shell is waiting, or while it is
-running a command. Output from the subshell waits until Emacs has time to
-process it; this happens whenever Emacs is waiting for keyboard input or
-for time to elapse.
+ To run a subshell interactively, type @kbd{M-x shell}. This creates
+(or reuses) a buffer named @samp{*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}.
+
+ 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
- Input lines, once you submit them, are displayed using the face
-@code{comint-highlight-input}, and prompts are displayed using the
-face @code{comint-highlight-prompt}. This makes it easier to see
-previous input lines in the buffer. @xref{Faces}.
-
- To make multiple subshells, you can invoke @kbd{M-x shell} with a
-prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
-name and create (or reuse) a subshell in that buffer. You can also
-rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
-create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
+ 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 @samp{*shell*} buffer using @kbd{M-x rename-uniquely},
+then create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
Subshells in different buffers run independently and in parallel.
@vindex explicit-shell-file-name
@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
- The file name used to load the subshell is the value of the variable
-@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise,
-the environment variable @env{ESHELL} is used, or the environment
-variable @env{SHELL} if there is no @env{ESHELL}. If the file name
-specified is relative, the directories in the list @code{exec-path} are
-searched; this list is initialized based on the environment variable
-@env{PATH} when Emacs is started. Your @file{.emacs} file can override
-either or both of these default initializations.
+ 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.
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 to fallback
-on @file{~/.emacs.d/init_@var{shellname}.sh}.
+@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
Coding}.
@cindex @env{INSIDE_EMACS} environment variable
- Emacs sets the environment variable @env{INSIDE_EMACS} in the
-subshell to a comma-separated list including the Emacs version.
-Programs can check this variable to determine whether they are running
-inside an Emacs subshell.
-
@cindex @env{EMACS} environment variable
- Emacs also sets the @env{EMACS} environment variable (to @code{t}) if
-it is not already defined. @strong{Warning:} This environment
-variable is deprecated. Programs that check this variable should be
-changed to check @env{INSIDE_EMACS} instead.
+ 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{24.1}). Programs can check this variable
+to determine whether they are running inside an Emacs subshell. (It
+also sets the @env{EMACS} environment variable to @code{t}, if that
+environment variable is not already defined. However, this
+environment variable is deprecated; programs that use it should switch
+to using @env{INSIDE_EMACS} instead.)
@node Shell Mode
@subsection Shell Mode
@cindex Shell mode
@cindex mode, Shell
- Shell buffers use Shell mode, which defines several special keys
-attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
-editing and job control characters present in shells that are not under
-Emacs, except that you must type @kbd{C-c} first. Here is a complete list
-of the special key bindings of Shell mode:
+ 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
-At end of buffer send line as input; otherwise, copy current line to
-end of buffer and send it (@code{comint-send-input}). Copying a line
-in this way omits any prompt at the beginning of the line (text output
-by programs preceding your input). @xref{Shell Prompts}, for how
-Shell mode recognizes prompts.
+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 comint-dynamic-complete
-Complete the command name or file name before point in the shell buffer
-(@code{comint-dynamic-complete}). @key{TAB} also completes history
-references (@pxref{History References}) and environment variable names.
+@findex completion-at-point
+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}).
@vindex shell-completion-fignore
@vindex comint-completion-fignore
@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 in the shell buffer
-(@code{comint-dynamic-list-filename-completions}).
+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, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other
-position in the buffer, @kbd{C-d} deletes a character as usual.
+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-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. This command used to be
-called @code{comint-kill-output}.
+out lots of output that just gets in the way.
@item C-c C-s
@kindex C-c C-s @r{(Shell mode)}
(@code{shell-backward-command}).
@item M-x dirs
-Ask the shell what its current directory is, so that Emacs can agree
-with the shell.
+Ask the shell for its working directory, and update the Shell buffer's
+default directory. @xref{Directory Tracking}.
@item M-x send-invisible @key{RET} @var{text} @key{RET}
@findex send-invisible
@node Shell Prompts
@subsection Shell Prompts
-@vindex shell-prompt-pattern
-@vindex comint-prompt-regexp
-@vindex comint-use-prompt-regexp
@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)
-considers the prompt to be any text output by a program at the
-beginning of an input line. However, if the variable
-@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode
-uses a regular expression to recognize prompts. In Shell mode,
-@code{shell-prompt-pattern} specifies the regular expression.
-
- The value of @code{comint-use-prompt-regexp} also affects many
-motion and paragraph commands. If the value is non-@code{nil}, the
-general Emacs motion commands behave as they normally do in buffers
-without special text properties. However, if the value is @code{nil},
-the default, then Comint mode divides the buffer into two types of
-``fields'' (ranges of consecutive characters having the same
-@code{field} text property): input and output. Prompts are part of
-the output. Most Emacs motion commands do not cross field boundaries,
-unless they move over multiple lines. For instance, when point is in
-input on the same line as a prompt, @kbd{C-a} puts point at the
-beginning of the input if @code{comint-use-prompt-regexp} is
-@code{nil} and at the beginning of the line otherwise.
-
- In Shell mode, only shell prompts start new paragraphs. Thus, a
-paragraph consists of a prompt and the input and output that follow
-it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the
-default, most paragraph commands do not cross field boundaries. This
-means that prompts, ranges of input, and ranges of non-prompt output
-behave mostly like separate paragraphs; with this setting, numeric
-arguments to most paragraph commands yield essentially undefined
-behavior. For the purpose of finding paragraph boundaries, Shell mode
-uses @code{shell-prompt-pattern}, regardless of
-@code{comint-use-prompt-regexp}.
+automatically figures out 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 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
Fetch the next later old shell command.
@kindex M-r @r{(Shell mode)}
-@kindex M-s @r{(Shell mode)}
-@findex comint-previous-matching-input
-@findex comint-next-matching-input
-@item M-r @var{regexp} @key{RET}
-@itemx M-s @var{regexp} @key{RET}
-Search backwards or forwards for old shell commands that match @var{regexp}.
+@findex comint-history-isearch-backward-regexp
+@item M-r
+Begin an incremental regexp search of old shell commands.
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
(@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}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer
-history commands except that they operate on the text at the end of the
-shell buffer, where you would normally insert text to send to the shell.
+ 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}, @kbd{M-r} and @kbd{M-s}. These work
+just like the minibuffer history commands (@pxref{Minibuffer
+History}), except that they operate within the Shell buffer rather
+than the minibuffer.
@kbd{M-p} fetches an earlier shell command to the end of the shell
buffer. Successive use of @kbd{M-p} fetches successively earlier
@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
@kbd{M-n}.
- The history search commands @kbd{M-r} and @kbd{M-s} read a regular
-expression and search through the history for a matching command. Aside
-from the choice of which command to fetch, they work just like @kbd{M-p}
-and @kbd{M-n}. If you enter an empty regexp, these commands reuse the
-same regexp used last time.
-
- When you find the previous input you want, you can resubmit it by
-typing @key{RET}, or you can edit it first and then resubmit it if you
-wish. Any partial input you were composing before navigating the
+ 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.
@kindex C-c RET @r{(Shell mode)}
@findex comint-copy-old-input
@item C-c @key{RET}
-Copy the input command which point is in, 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.
+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
@vindex shell-popd-regexp
@vindex shell-cd-regexp
Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
-commands given to the inferior shell, so it can keep the
-@samp{*shell*} buffer's default directory the same as the shell's
-working directory. It recognizes these commands syntactically, by
-examining lines of input that are sent.
+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. For example, if the value of the variable
-@code{shell-pushd-regexp} matches the beginning of a shell command
-line, that line is regarded as a @code{pushd} command. Change this
-variable when you add aliases for @samp{pushd}. Likewise,
-@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to
-recognize commands with the meaning of @samp{popd} and @samp{cd}.
-These commands are recognized only at the beginning of a shell command
-line.
-
-@ignore @c This seems to have been deleted long ago.
-@vindex shell-set-directory-error-hook
- If Emacs gets an error while trying to handle what it believes is a
-@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
-@code{shell-set-directory-error-hook} (@pxref{Hooks}).
-@end ignore
+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 current directory of the
-subshell, use the command @kbd{M-x dirs} to ask the shell what its
-current directory is. This command works for shells that support the
-most common command syntax; it may not work for unusual shells.
+ 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
- You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
-alternative method of tracking changes in the current directory. This
-method relies on your shell prompt containing the full current working
-directory at all times.
+@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
(@code{shell-pushd-dunique}). The values you choose should match the
underlying shell, of course.
- If you want Shell mode to handle color output from shell commands,
-you can enable ANSI Color mode. Here is how to do this:
-
-@example
-(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
-@end example
-
@node Terminal emulator
@subsection Emacs Terminal Emulator
@findex term
- To run a subshell in a terminal emulator, putting its typescript in
-an Emacs buffer, use @kbd{M-x term}. This creates (or reuses) a
-buffer named @samp{*terminal*}, and runs a subshell with input coming
-from your keyboard, and output going to that buffer.
+ To run a subshell in a terminal emulator, use @kbd{M-x term}. This
+creates (or reuses) a buffer named @samp{*terminal*}, and runs a
+subshell with input coming from your keyboard, and output going to
+that buffer.
The terminal emulator uses Term mode, which has two input modes. In
-line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
+line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
- In char mode, each character is sent directly to the inferior
-subshell, as ``terminal input.'' Any ``echoing'' of your input is the
+ In char mode, each character is sent directly to the subshell, as
+``terminal input.'' Any ``echoing'' of your input is the
responsibility of the subshell. The sole exception is the terminal
escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
Any ``terminal output'' from the subshell goes into the buffer,
appearance of the window matches what it would be on a real terminal.
You can actually run Emacs inside an Emacs Term window.
- The file name used to load the subshell is determined the same way
+ You can also 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 @samp{*terminal*} to something different using @kbd{M-x
rename-uniquely}, just as with Shell mode.
@cindex mode, Term
The terminal emulator uses Term mode, which has two input modes. In
-line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
-In char mode, each character is sent directly to the inferior
-subshell, except for the Term escape character, normally @kbd{C-c}.
+line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
+In char mode, each character is sent directly to the subshell, except
+for the Term escape character, normally @kbd{C-c}.
To switch between line and char mode, use these commands:
@table @kbd
@kindex C-c C-j @r{(Term mode)}
-@findex term-char-mode
+@findex term-line-mode
@item C-c C-j
-Switch to line mode. Do nothing if already in line mode.
+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-line-mode
+@findex term-char-mode
@item C-c C-k
-Switch to char mode. Do nothing if already in char mode.
+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:
is normally @samp{other-window}.
@end table
-@node Paging in Term
-@subsection Page-At-A-Time Output
-@cindex page-at-a-time
-
- Term mode has a page-at-a-time feature. When enabled it makes
-output pause at the end of each screenful.
+@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. This command works in both line
-and char modes. When page-at-a-time is enabled, the mode-line
-displays the word @samp{page}.
+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
- With page-at-a-time enabled, whenever Term receives more than a
-screenful of output since your last input, it pauses, displaying
-@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
-screenful of output. Type @kbd{?} to see your other options. The
-interface is similar to the @code{more} program.
-
@node Remote Host
@subsection Remote Host Shell
@cindex remote host
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 separating comma.) Terminal types @samp{ansi}
-or @samp{vt100} will work on most systems.
-
-@c If you are talking to a Bourne-compatible
-@c shell, and your system understands the @env{TERMCAP} variable,
-@c you can use the command @kbd{M-x shell-send-termcap}, which
-@c sends a string specifying the terminal type and size.
-@c (This command is also useful after the window has changed size.)
-
-@c You can of course run @samp{gdb} on that remote computer. One useful
-@c trick: If you invoke gdb with the @code{--fullname} option,
-@c it will send special commands to Emacs that will cause Emacs to
-@c pop up the source files you're debugging. This will work
-@c whether or not gdb is running on a different computer than Emacs,
-@c as long as Emacs can access the source files specified by gdb.
-
-@ignore
- You cannot log in to a remote computer using the Shell mode.
-@c (This will change when Shell is re-written to use Term.)
-Instead, Emacs provides two commands for logging in to another computer
-and communicating with it through an Emacs buffer using Comint mode:
+login command, without a separating comma.) Terminal types
+@samp{ansi} or @samp{vt100} will work on most systems.
-@table @kbd
-@item M-x telnet @key{RET} @var{hostname} @key{RET}
-Set up a Telnet connection to the computer named @var{hostname}.
-@item M-x rlogin @key{RET} @var{hostname} @key{RET}
-Set up an Rlogin connection to the computer named @var{hostname}.
-@end table
+@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.
-@findex telnet
- Use @kbd{M-x telnet} to set up a Telnet connection to another
-computer. (Telnet is the standard Internet protocol for remote login.)
-It reads the host name of the other computer as an argument with the
-minibuffer. Once the connection is established, talking to the other
-computer works like talking to a subshell: you can edit input with the
-usual Emacs commands, and send it a line at a time by typing @key{RET}.
-The output is inserted in the Telnet buffer interspersed with the input.
-
-@findex rlogin
-@vindex rlogin-explicit-args
- Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is
-another remote login communication protocol, essentially much like the
-Telnet protocol but incompatible with it, and supported only by certain
-systems. Rlogin's advantages are that you can arrange not to have to
-give your user name and password when communicating between two machines
-you frequently use, and that you can make an 8-bit-clean connection.
-(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")}
-before you run Rlogin.)
-
- @kbd{M-x rlogin} sets up the default file directory of the Emacs
-buffer to access the remote host via FTP (@pxref{File Names}), and it
-tracks the shell commands that change the current directory, just like
-Shell mode.
-
-@findex rlogin-directory-tracking-mode
- There are two ways of doing directory tracking in an Rlogin
-buffer---either with remote directory names
-@file{/@var{host}:@var{dir}/} or with local names (that works if the
-``remote'' machine shares file systems with your machine of origin).
-You can use the command @code{rlogin-directory-tracking-mode} to switch
-modes. No argument means use remote directory names, a positive
-argument means use local names, and a negative argument means turn
-off directory tracking.
-
-@end ignore
+ A serial port can be configured even more by clicking on ``8N1'' in
+the mode line. By default, a serial port is configured as ``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, Printing, Shell, Top
@section Using Emacs as a Server
@cindex server, using Emacs as
@cindex @env{EDITOR} environment variable
- Various programs such as @code{mail} can invoke your choice of editor
-to edit a particular piece of text, such as a message that you are
-sending. By convention, most of these programs use the environment
-variable @env{EDITOR} to specify which editor to run. If you set
-@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
-inconvenient fashion, by starting a new, separate Emacs process. This
-is inconvenient because it takes time and because the new Emacs process
-doesn't share the buffers with any existing Emacs process.
-
- You can arrange to use your existing Emacs process as the editor for
-programs like @code{mail} by using the Emacs client program and the
-server that is part of Emacs. Here is how.
-
-@cindex @env{TEXEDIT} 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 two ways to start an Emacs server:
+
+@itemize
@findex server-start
- First, the preparations. Within Emacs, call the function
-@code{server-start}. (Your @file{.emacs} init file can do this
-automatically if you add the expression @code{(server-start)} to it,
-see @ref{Init File}.) Then, outside Emacs, set the @env{EDITOR}
-environment variable to @samp{emacsclient}. (Note that some programs
-use a different environment variable; for example, to make @TeX{} use
-@samp{emacsclient}, you should set the @env{TEXEDIT} environment
-variable to @samp{emacsclient +%d %s}.)
-
-@pindex emacs.bash
-@cindex Bash command to use Emacs server
- As an alternative to using @code{emacsclient}, the file
-@file{etc/emacs.bash} defines a Bash command @code{edit} which will
-communicate with a running Emacs session, or start one if none exist.
-
-@kindex C-x #
-@findex server-edit
- Now, whenever any program invokes your specified @env{EDITOR}
-program, the effect is to send a message to your principal Emacs telling
-it to visit a file. (That's what the program @code{emacsclient} does.)
-Emacs displays the buffer immediately and you can immediately begin
-editing it in the already running Emacs session.
-
- When you've finished editing that buffer, type @kbd{C-x #}
-(@code{server-edit}). This saves the file and sends a message back to
-the @code{emacsclient} program telling it to exit. The programs that
-use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
-to exit. @kbd{C-x #} also 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
-say that you are finished with one.
+@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.
-@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 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.
+@cindex daemon, Emacs
+@item
+Run Emacs as a @dfn{daemon}, using the @samp{--daemon} command-line
+option. @xref{Initial Options}. When Emacs is started this way, it
+calls @code{server-start} after initialization, and returns control to
+the calling terminal instead of opening an initial frame; it then
+waits in the background, listening for edit requests.
+@end itemize
-@vindex server-window
- If you set the variable @code{server-window} to a window or a frame,
-@kbd{C-x #} displays the server buffer in that window or in that frame.
+@cindex @env{TEXEDIT} environment variable
+ Either way, 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
@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} option. @xref{Invoking emacsclient}.
-
- While @code{mail} or another application is waiting for
-@code{emacsclient} to finish, @code{emacsclient} does not read terminal
-input. So the terminal that @code{mail} was using is effectively
-blocked for the duration. In order to edit with your principal Emacs,
-you need to be able to use it without using that terminal. There are
-three ways to do this:
-
-@itemize @bullet
-@item
-Using a window system, run @code{mail} and the principal Emacs in two
-separate windows. While @code{mail} is waiting for @code{emacsclient},
-the window where it was running is blocked, but you can use Emacs by
-switching windows.
-
-@item
-Using virtual terminals, run @code{mail} in one virtual terminal
-and run Emacs in another.
+name, using the @samp{-s} option (@pxref{emacsclient Options}).
-@item
-Use Shell mode or Term mode in Emacs to run the other program such as
-@code{mail}; then, @code{emacsclient} blocks only the subshell under
-Emacs, and you can still use Emacs to edit the file.
-@end itemize
-
- If you run @code{emacsclient} with the option @samp{--no-wait}, it
-returns immediately without waiting for you to ``finish'' the buffer
-in Emacs. Note that server buffers created in this way are not killed
-automatically when you finish with them.
+@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.
@menu
-* Invoking emacsclient:: Emacs client startup options.
+* Invoking emacsclient:: Connecting to the Emacs server.
+* emacsclient Options:: Emacs client startup options.
@end menu
-@node Invoking emacsclient,, Emacs Server, Emacs Server
+@node Invoking emacsclient
@subsection Invoking @code{emacsclient}
-@cindex @code{emacsclient} invocation and options
+@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-only 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. 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, or on a text-only terminal, using the @samp{-c} and
+@samp{-t} options. @xref{emacsclient Options}.
+
+ If you are running on a single text-only 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});
+@code{emacsclient} blocks only the subshell under Emacs, and you can
+still use Emacs to edit the file.
- To run the @code{emacsclient} program, specify file names as arguments,
-and optionally line numbers as well, like this:
+@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.
+
+ 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).
-@example
-emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
-@end example
+@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.
-@noindent
-This tells Emacs to visit each of the specified files; if you specify a
-line number for a certain file, Emacs moves to that line in the file.
-If you specify a column number as well, Emacs puts point on that column
-in the line.
-
- Ordinarily, @code{emacsclient} does not return until you use the
-@kbd{C-x #} command on each of these buffers. When that happens,
-Emacs sends a message to the @code{emacsclient} program telling it to
-return.
-
- If you invoke @code{emacsclient} for more than one file, the
-additional client buffers are buried at the bottom of the buffer list
-(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing
-a client buffer, the next client buffer is automatically selected.
-
- But if you use the option @samp{-n} or @samp{--no-wait} when running
-@code{emacsclient}, then it returns immediately. (You can take as
-long as you like to edit the files in Emacs.)
-
- The option @samp{-a @var{command}} or
-@samp{--alternate-editor=@var{command}} specifies a command to run if
-@code{emacsclient} fails to contact Emacs. This is useful when
-running @code{emacsclient} in a script. For example, the following
-setting for the @env{EDITOR} environment variable will always give you
-an editor, even if no Emacs server is running:
+ 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.
+
+@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
-EDITOR="emacsclient --alternate-editor emacs +%d %s"
+emacsclient -c +12 @var{file1} +4:3 @var{file2}
@end example
@noindent
-@cindex @env{ALTERNATE_EDITOR} environment variable
-The environment variable @env{ALTERNATE_EDITOR} has the same effect, with
-the value of the @samp{--alternate-editor} option taking precedence.
+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}.
-If you use several displays, you can tell Emacs on which display to
-open the given files with the @samp{-d @var{display}} or
-@samp{--display=@var{display}} option to @code{emacsclient}. This is
-handy when connecting from home to an Emacs session running on your
-machine at your workplace.
+ The other optional arguments recognized by @command{emacsclient} are
+listed below:
-If there is more than one Emacs server running, you can specify a
-server name with the @samp{-s @var{name}} or
-@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This
-option is not supported on MS-Windows.)
+@table @samp
+@item -a @var{command}
+@itemx --alternate-editor=@var{command}
+Specify a command to run if @code{emacsclient} fails to contact Emacs.
+This is useful when running @code{emacsclient} in a script.
-You can also use @code{emacsclient} to execute any piece of Emacs Lisp
-code, using the @samp{-e} or @samp{--eval} option. When this option
-is given, the rest of the arguments is interpreted as a list of
-expressions to evaluate, not a list of files to visit.
+As a special exception, if @var{command} is the empty string, then
+@code{emacsclient} starts Emacs in daemon mode (as @command{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.
+
+@item -c
+Create a new graphical frame, instead of using an existing Emacs
+frame. Emacs can create a graphical frame even if it was started in a
+text-only terminal, provided it is able to connect to a graphical
+display. If no graphical display is available, Emacs creates a new
+text-only terminal frame (@pxref{Frames}). If you omit a filename
+argument while supplying the @samp{-c} option, the new frame displays
+the @samp{*scratch*} buffer (@pxref{Buffers}).
+
+@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.
+
+@item -f @var{server-file}
+@itemx --server-file=@var{server-file}
@cindex @env{EMACS_SERVER_FILE} environment variable
-When you start the Emacs server (by calling @code{server-start}),
-Emacs creates a file with information about TCP connection to the
-server: the host where Emacs is running, the port where it is
-listening, and an authentication string. @code{emacsclient} uses this
-information if it needs to connect to the server via TCP. By default,
-the file goes in the @file{~/.emacs.d/server/} directory@footnote{On
-MS-Windows, if @env{HOME} is not set or the TCP configuration file
-cannot be found there, Emacs also looks for the file in the
-@file{.emacs.d/server/} subdirectory of the directory pointed to by
-the @env{APPDATA} environment variable.}. You can specify the file
-name to use with the @samp{-f @var{file}} or
-@samp{--server-file=@var{file}} options, or by setting
-@env{EMACS_SERVER_FILE} environment variable to the file name.
+@cindex server file
+@vindex server-use-tcp
+@vindex server-host
+Specify a @dfn{server file} for connecting to an Emacs server via TCP.
+
+An Emacs server usually uses an operating system feature called a
+``local socket'' to listen for connections. Some operating systems,
+such as Microsoft Windows, do not support local sockets; in that case,
+Emacs uses TCP instead. When you start the Emacs server, Emacs
+creates a server file containing some TCP information that
+@command{emacsclient} needs for making the connection. By default,
+the server file is in @file{~/.emacs.d/server/}. On Microsoft
+Windows, if @command{emacsclient} does not find the server file there,
+it looks in the @file{.emacs.d/server/} subdirectory of the directory
+pointed to by the @env{APPDATA} environment variable. You can tell
+@command{emacsclient} to use a specific server file with the @samp{-f}
+or @samp{--server-file} option, or by setting the
+@env{EMACS_SERVER_FILE} environment variable.
+
+Even if local sockets are available, you can tell Emacs to use TCP by
+setting the variable @code{server-use-tcp} to @code{t}. One advantage
+of TCP is that the server can accept connections from remote machines.
+For this to work, you must (i) set the variable @code{server-host} to
+the hostname or IP address of the machine on which the Emacs server
+runs, and (ii) provide @command{emacsclient} with the server file.
+(One convenient way to do the latter is to put the server file on a
+networked file system such as NFS.)
+
+@vindex server-port
+ When the Emacs server is using TCP, the variable @code{server-port}
+determines the port number to listen on; the default value,
+@code{nil}, means to choose a random port when the server starts.
+
+@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 --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 -s @var{server-name}
+@itemx --socket-name=@var{server-name}
+Connect to the Emacs server named @var{server-name}. 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 first
+server it finds. (This option is not supported on MS-Windows.)
+
+@item -t
+@itemx --tty
+@itemx -nw
+Create a new Emacs frame on the current text-only terminal, instead of
+using an existing Emacs frame. Emacs can open a text-only terminal
+even if it was started in another text-only terminal, or on a
+graphical display. If you omit a filename argument while supplying
+this option, the new frame displays the @samp{*scratch*} buffer.
+@xref{Buffers}.
+@end table
+
+ If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
+Emacs frame created with @command{emacsclient}, via the @samp{-c} or
+@samp{-t} options, Emacs deletes the frame instead of killing the
+Emacs process itself. On a text-only terminal frame created with the
+@samp{-t} option, this returns control to the terminal. Emacs also
+marks all the server buffers for the client as finished, as though you
+had typed @kbd{C-x #} in all of them.
+
+ When Emacs is started as a daemon, all frames are considered client
+frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs
+process, type @kbd{M-x kill-emacs}.
@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
@cindex hardcopy
@cindex printing
- Emacs provides commands for printing hard copies of either an entire
-buffer or just part of one, with or without page headers. You can
-invoke the printing commands directly, as detailed in the following
-section, or using the @samp{File} menu on the menu bar. See also the
-hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary
-(@pxref{Displaying the Diary}).
+ 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.
+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
@findex lpr-buffer
@findex lpr-region
@vindex lpr-switches
- The hardcopy commands (aside from the PostScript commands) pass extra
-switches to the @code{lpr} program based on the value of the variable
-@code{lpr-switches}. Its value should be a list of strings, each string
-an option starting with @samp{-}. For example, to specify a line width
-of 80 columns for all the printing you do in Emacs, set
-@code{lpr-switches} like this:
-
-@example
-(setq lpr-switches '("-w80"))
-@end example
+@vindex lpr-commands
+ On most operating system, 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
- You can specify the printer to use by setting the variable
-@code{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-commands
@vindex lpr-add-switches
- The variable @code{lpr-command} specifies the name of the printer
-program to run; the default value depends on your operating system type.
-On most systems, the default is @code{"lpr"}. 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
-@code{lpr}) to the printer program: @code{nil} means don't add them.
-@code{lpr-add-switches} should be @code{nil} if your printer program is
-not compatible with @code{lpr}.
+ 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:: Printing buffers or regions as PostScript.
* PostScript Variables:: Customizing the PostScript printing commands.
* Printing Package:: An optional advanced printing interface.
@end menu
@node PostScript, PostScript Variables,, Printing
-@section PostScript Hardcopy
+@subsection PostScript Hardcopy
These commands convert buffer contents to PostScript,
either printing it or leaving it in another Emacs buffer.
Print hardcopy of the current region in PostScript form, showing the
faces used in the text.
@item M-x ps-spool-buffer
-Generate PostScript for the current buffer text.
+Generate and spool a PostScript image for the current buffer text.
@item M-x ps-spool-region
-Generate PostScript for the current region.
+Generate and spool a PostScript image for the current region.
@item M-x ps-spool-buffer-with-faces
-Generate PostScript for the current buffer, showing the faces used.
+Generate and spool a PostScript image for the current buffer, showing the faces used.
@item M-x ps-spool-region-with-faces
-Generate PostScript for the current region, showing the faces used.
+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
-Generates/prints PostScript for the current buffer as if handwritten.
+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 PostScript commands, @code{ps-print-buffer} and
-@code{ps-print-region}, print buffer contents in PostScript form. One
-command prints the entire buffer; the other, just the region. The
-corresponding @samp{-with-faces} commands,
-@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
-use PostScript features to show the faces (fonts and colors) in the text
-properties of the text being printed.
-
- If you are using a color display, you can print a buffer of program
-code with color highlighting by turning on Font-Lock mode in that
-buffer, and using @code{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}), the command
+prompts the user for a file name, and saves 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}
+ 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
+ @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.
-@ifnottex
- The following section describes variables for customizing these commands.
-@end ifnottex
-
@node PostScript Variables, Printing Package, PostScript, Printing
-@section Variables for PostScript Hardcopy
+@subsection Variables for PostScript Hardcopy
@vindex ps-lpr-command
@vindex ps-lpr-switches
with shades of gray. This might produce illegible output, even if your
screen colors only use shades of gray.
+ Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to
+print colors on black/white printers.
+
@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
described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
@node Printing Package,, PostScript Variables, Printing
-@section Printing Package
+@subsection Printing Package
@cindex Printing package
The basic Emacs facilities for printing hardcopy can be extended
further information on the various options, use the @samp{Interface
Help} button.
-@node Sorting, Narrowing, Printing, Top
+@node Sorting
@section Sorting Text
@cindex sorting
Many of the sort commands ignore case differences when comparing, if
@code{sort-fold-case} is non-@code{nil}.
-@node Narrowing, Two-Column, Sorting, Top
-@section Narrowing
-@cindex widening
-@cindex restriction
-@cindex narrowing
-@cindex accessible portion
-
- @dfn{Narrowing} means focusing in on some portion of the buffer,
-making the rest temporarily inaccessible. The portion which you can
-still get to is called the @dfn{accessible portion}. Canceling the
-narrowing, which makes the entire buffer once again accessible, is
-called @dfn{widening}. The bounds of narrowing in effect in a buffer
-are called the buffer's @dfn{restriction}.
-
- Narrowing can make it easier to concentrate on a single subroutine or
-paragraph by eliminating clutter. It can also be used to limit the
-range of operation of a replace command or repeating keyboard macro.
-
-@table @kbd
-@item C-x n n
-Narrow down to between point and mark (@code{narrow-to-region}).
-@item C-x n w
-Widen to make the entire buffer accessible again (@code{widen}).
-@item C-x n p
-Narrow down to the current page (@code{narrow-to-page}).
-@item C-x n d
-Narrow down to the current defun (@code{narrow-to-defun}).
-@end table
+@c Picture Mode documentation
+@ifnottex
+@include picture-xtra.texi
+@end ifnottex
- When you have narrowed down to a part of the buffer, that part appears
-to be all there is. You can't see the rest, you can't move into it
-(motion commands won't go outside the accessible part), you can't change
-it in any way. However, it is not gone, and if you save the file all
-the inaccessible text will be saved. The word @samp{Narrow} appears in
-the mode line whenever narrowing is in effect.
-
-@kindex C-x n n
-@findex narrow-to-region
- The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
-It sets the current buffer's restrictions so that the text in the current
-region remains accessible, but all text before the region or after the
-region is inaccessible. Point and mark do not change.
-
-@kindex C-x n p
-@findex narrow-to-page
-@kindex C-x n d
-@findex narrow-to-defun
- Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
-down to the current page. @xref{Pages}, for the definition of a page.
-@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
-containing point (@pxref{Defuns}).
-
-@kindex C-x n w
-@findex widen
- The way to cancel narrowing is to widen with @kbd{C-x n w}
-(@code{widen}). This makes all text in the buffer accessible again.
-
- You can get information on what part of the buffer you are narrowed down
-to using the @kbd{C-x =} command. @xref{Position Info}.
-
- Because narrowing can easily confuse users who do not understand it,
-@code{narrow-to-region} is normally a disabled command. Attempting to use
-this command asks for confirmation and gives you the option of enabling it;
-if you enable the command, confirmation will no longer be required for
-it. @xref{Disabling}.
-
-@node Two-Column, Editing Binary Files, Narrowing, Top
-@section Two-Column Editing
-@cindex two-column editing
-@cindex splitting columns
-@cindex columns, splitting
-
- Two-column mode lets you conveniently edit two side-by-side columns of
-text. It uses two side-by-side windows, each showing its own
-buffer.
-
- There are three ways to enter two-column mode:
-@table @asis
-@item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
-@kindex F2 2
-@kindex C-x 6 2
-@findex 2C-two-columns
-Enter two-column mode with the current buffer on the left, and on the
-right, a buffer whose name is based on the current buffer's name
-(@code{2C-two-columns}). If the right-hand buffer doesn't already
-exist, it starts out empty; the current buffer's contents are not
-changed.
-
-This command is appropriate when the current buffer is empty or contains
-just one column and you want to add another column.
-
-@item @kbd{@key{F2} s} or @kbd{C-x 6 s}
-@kindex F2 s
-@kindex C-x 6 s
-@findex 2C-split
-Split the current buffer, which contains two-column text, into two
-buffers, and display them side by side (@code{2C-split}). The current
-buffer becomes the left-hand buffer, but the text in the right-hand
-column is moved into the right-hand buffer. The current column
-specifies the split point. Splitting starts with the current line and
-continues to the end of the buffer.
-
-This command is appropriate when you have a buffer that already contains
-two-column text, and you wish to separate the columns temporarily.
-
-@item @kbd{@key{F2} b @var{buffer} @key{RET}}
-@itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
-@kindex F2 b
-@kindex C-x 6 b
-@findex 2C-associate-buffer
-Enter two-column mode using the current buffer as the left-hand buffer,
-and using buffer @var{buffer} as the right-hand buffer
-(@code{2C-associate-buffer}).
-@end table
-
- @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
-is a string that appears on each line between the two columns. You can
-specify the width of the separator with a numeric argument to
-@kbd{@key{F2} s}; that many characters, before point, constitute the
-separator string. By default, the width is 1, so the column separator
-is the character before point.
-
- When a line has the separator at the proper place, @kbd{@key{F2} s}
-puts the text after the separator into the right-hand buffer, and
-deletes the separator. Lines that don't have the column separator at
-the proper place remain unsplit; they stay in the left-hand buffer, and
-the right-hand buffer gets an empty line to correspond. (This is the
-way to write a line that ``spans both columns while in two-column
-mode'': write it in the left-hand buffer, and put an empty line in the
-right-hand buffer.)
-
-@kindex F2 RET
-@kindex C-x 6 RET
-@findex 2C-newline
- The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
-(@code{2C-newline}) inserts a newline in each of the two buffers at
-corresponding positions. This is the easiest way to add a new line to
-the two-column text while editing it in split buffers.
-
-@kindex F2 1
-@kindex C-x 6 1
-@findex 2C-merge
- When you have edited both buffers as you wish, merge them with
-@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
-text from the right-hand buffer as a second column in the other buffer.
-To go back to two-column editing, use @kbd{@key{F2} s}.
-
-@kindex F2 d
-@kindex C-x 6 d
-@findex 2C-dissociate
- Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
-leaving each as it stands (@code{2C-dissociate}). If the other buffer,
-the one not current when you type @kbd{@key{F2} d}, is empty,
-@kbd{@key{F2} d} kills it.
-
-@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top
+@node Editing Binary Files
@section Editing Binary Files
@cindex Hexl mode
when you exit Emacs, and automatic restoration of the last saved
desktop when Emacs starts: 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 @file{~/.emacs} file:
+sessions, or add this line in your init file (@pxref{Init File}):
@example
(desktop-save-mode 1)
@findex desktop-change-dir
@findex desktop-revert
- If you turn on @code{desktop-save-mode} in your @file{~/.emacs},
-then when Emacs starts, it looks for a saved desktop in the current
-directory. Thus, you can have separate saved desktops in different
-directories, and the starting directory determines which one Emacs
-reloads. You can save the current desktop and reload one saved in
-another directory by typing @kbd{M-x desktop-change-dir}. Typing
-@kbd{M-x desktop-revert} reverts to the desktop previously reloaded.
+@vindex desktop-path
+ If you turn on @code{desktop-save-mode} in your init file, then when
+Emacs starts, it looks for a saved desktop in the current directory.
+(More precisely, it looks in the directories specified by
+@var{desktop-path}, and uses the first desktop it finds.)
+Thus, you can have separate saved desktops in different directories,
+and the starting directory determines which one Emacs reloads. You
+can save the current desktop and reload one saved in another directory
+by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x
+desktop-revert} reverts to the desktop previously reloaded.
Specify the option @samp{--no-desktop} on the command line when you
don't want it to reload any saved desktop. 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 @file{.emacs} init file, where
-@code{desktop-save-mode} is usually turned on.
+since it bypasses the init file, where @code{desktop-save-mode} is
+usually turned on.
@vindex desktop-restore-eager
By default, all the buffers in the desktop are restored at one go.
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.
+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
@item EDT (DEC VMS editor)
@findex edt-emulation-on
@findex edt-emulation-off
-Turn on EDT emulation with the command @kbd{M-x edt-emulation-on},
-while @kbd{M-x edt-emulation-off} restores normal Emacs command
-bindings.
+Turn on EDT emulation @kbd{M-x edt-emulation-on}; use @kbd{M-x
+edt-emulation-off} to restore normal Emacs command bindings.
Most of the EDT emulation commands are keypad keys, and most standard
Emacs key bindings are still available. The EDT emulation rebindings
key bindings.
@end table
-@node Hyperlinking, Dissociated Press, Emulation, Top
+@node Hyperlinking, Amusements, Emulation, Top
@section Hyperlinking and Navigation Features
-@cindex hyperlinking
-@cindex navigation
- Various modes documented elsewhere have hypertext features so that
-you can follow links, usually by clicking @kbd{Mouse-2} on the link or
-typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1}
-quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer
-if you want to set point instead.)
-
- Info mode, Help mode and the Dired-like modes are examples of modes
-that have links in the buffer. The Tags facility links between uses
-and definitions in source files, see @ref{Tags}. Imenu provides
-navigation amongst items indexed in the current buffer, see
-@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions
-in Info indexes, see @ref{Documentation}. Speedbar maintains a frame
-in which links to files, and locations in files are displayed, see
-@ref{Speedbar}.
-
- Other non-mode-specific facilities described in this section enable
-following links from the current buffer in a context-sensitive
-fashion.
+ The following subsections describe convenience features for handling
+URLs and other types of links occurring in Emacs buffer text.
@menu
* Browse-URL:: Following URLs.
-* Goto-address:: Activating URLs.
+* Goto Address mode:: Activating URLs.
* FFAP:: Finding files etc. at point.
@end menu
Load a URL into a Web browser.
@end table
-The Browse-URL package provides facilities for following URLs specifying
-links on the World Wide Web. Usually this works by invoking a web
-browser, but you can, for instance, arrange to invoke @code{compose-mail}
-from @samp{mailto:} URLs.
+ 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 general way to use this feature is to type @kbd{M-x browse-url},
-which displays a specified URL. If point is located near a plausible
-URL, that URL is used as the default. Other commands are available
-which you might like to bind to keys, such as
-@code{browse-url-at-point} and @code{browse-url-at-mouse}.
+ 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, particularly
-@code{browse-url-browser-function}. You can invoke actions dependent
-on the type of URL by defining @code{browse-url-browser-function} as
-an association list. The package's commentary available via @kbd{C-h
-p} under the @samp{hypermedia} keyword provides more information.
-Packages with facilities for following URLs should always go through
-Browse-URL, so that the customization options for Browse-URL will
-affect all browsing in Emacs.
-
-@node Goto-address
+@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} lets you
+define how to follow other types of URLs. For more information, view
+the package commentary by typing @kbd{C-h P browse-url @key{RET}}.
+
+@node Goto Address mode
@subsection Activating URLs
-@findex goto-address
-@cindex Goto-address
+@findex goto-address-mode
+@cindex mode, Goto Address
+@cindex Goto Address mode
@cindex URLs, activating
@table @kbd
-@item M-x goto-address
+@item M-x goto-address-mode
Activate URLs and e-mail addresses in the current buffer.
@end table
- You can make URLs in the current buffer active with @kbd{M-x
-goto-address}. This finds all the URLs in the buffer, and establishes
-bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them. After
-activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL
-and type @kbd{C-c @key{RET}}, that will display the web page that the URL
-specifies. For a @samp{mailto} URL, it sends mail instead, using your
-selected mail-composition method (@pxref{Mail Methods}).
-
- It can be useful to add @code{goto-address} to mode hooks and the
-hooks used to display an incoming message.
-@code{rmail-show-message-hook} is the appropriate hook for Rmail, and
-@code{mh-show-mode-hook} for MH-E. This is not needed for Gnus,
+@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, and
+@code{mh-show-mode-hook} for MH-E). This is not needed for Gnus,
which has a similar feature of its own.
-
@node FFAP
@subsection Finding Files and URLs at Point
@findex find-file-at-point
@findex ffap-menu
@cindex finding file at point
- FFAP mode replaces certain key bindings for finding files, including
-@kbd{C-x C-f}, with commands that provide more sensitive 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.
+ The FFAP package replaces certain key bindings for finding files,
+such as @kbd{C-x C-f}, with commands that provide more sensitive
+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. The
-@samp{ffap} package's commentary available via @kbd{C-h p} under the
-@samp{files} keyword and the @code{ffap} Custom group provide details.
+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
- You can turn on FFAP minor mode by calling @code{ffap-bindings} to
-make the following key bindings and to install hooks for using
-@code{ffap} in Rmail, Gnus and VM article buffers.
+ 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}
find the one you select (@code{ffap-menu}).
@end table
-@node Dissociated Press, Amusements, Hyperlinking, Top
-@section Dissociated Press
-
-@findex dissociated-press
- @kbd{M-x dissociated-press} is a command for scrambling a file of text
-either word by word or character by character. Starting from a buffer of
-straight English, it produces extremely amusing output. The input comes
-from the current Emacs buffer. Dissociated Press writes its output in a
-buffer named @samp{*Dissociation*}, and redisplays that buffer after every
-couple of lines (approximately) so you can read the output as it comes out.
-
- Dissociated Press asks every so often whether to continue generating
-output. Answer @kbd{n} to stop it. You can also stop at any time by
-typing @kbd{C-g}. The dissociation output remains in the
-@samp{*Dissociation*} buffer for you to copy elsewhere if you wish.
-
-@cindex presidentagon
- Dissociated Press operates by jumping at random from one point in the
-buffer to another. In order to produce plausible output rather than
-gibberish, it insists on a certain amount of overlap between the end of
-one run of consecutive words or characters and the start of the next.
-That is, if it has just output `president' and then decides to jump
-to a different point in the file, it might spot the `ent' in `pentagon'
-and continue from there, producing `presidentagon'.@footnote{This
-dissociword actually appeared during the Vietnam War, when it was very
-appropriate. Bush has made it appropriate again.} Long sample texts
-produce the best results.
-
-@cindex againformation
- A positive argument to @kbd{M-x dissociated-press} tells it to operate
-character by character, and specifies the number of overlap characters. A
-negative argument tells it to operate word by word, and specifies the number
-of overlap words. In this mode, whole words are treated as the elements to
-be permuted, rather than characters. No argument is equivalent to an
-argument of two. For your againformation, the output goes only into the
-buffer @samp{*Dissociation*}. The buffer you start with is not changed.
-
-@cindex Markov chain
-@cindex ignoriginal
-@cindex techniquitous
- Dissociated Press produces results fairly like those of a Markov
-chain based on a frequency table constructed from the sample text. It
-is, however, an independent, ignoriginal invention. Dissociated Press
-techniquitously copies several consecutive characters from the sample
-between random choices, whereas a Markov chain would choose randomly
-for each word or character. This makes for more plausible sounding
-results, and runs faster.
-
-@cindex outragedy
-@cindex buggestion
-@cindex properbose
-@cindex mustatement
-@cindex developediment
-@cindex userenced
- It is a mustatement that too much use of Dissociated Press can be a
-developediment to your real work, sometimes to the point of outragedy.
-And keep dissociwords out of your documentation, if you want it to be well
-userenced and properbose. Have fun. Your buggestions are welcome.
-
-@node Amusements, Customization, Dissociated Press, Top
+@node Amusements, Packages, Hyperlinking, Top
@section Other Amusements
@cindex boredom
-@findex hanoi
-@findex yow
-@findex gomoku
-@cindex tower of 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.
-
-@cindex Go Moku
- If you want a little more personal involvement, try @kbd{M-x gomoku},
-which plays the game Go Moku with you.
+@findex animate-birthday-present
+@cindex animate
+ The @code{animate} package makes text dance. For an example, try
+@kbd{M-x animate-birthday-present}.
@findex blackbox
@findex mpuz
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
+ @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.
+ @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 @samp{*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
- @kbd{M-x dunnet} runs an adventure-style exploration game, which is
-a bigger sort of puzzle.
+ @kbd{M-x dunnet} runs an text-based adventure game.
-@findex lm
-@cindex landmark game
-@kbd{M-x lm} runs a relatively non-participatory game in which a robot
-attempts to maneuver towards a tree at the center of the window based on
-unique olfactory cues from each of the four directions.
+@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 ``Life'' cellular automaton.
+ @kbd{M-x life} runs Conway's ``Life'' cellular automaton.
+
+@findex landmark
+@cindex landmark game
+ @kbd{M-x landmark} runs a relatively non-participatory game in which
+a robot attempts to maneuver towards a tree at the center of the
+window based on unique olfactory cues from each of the four
+directions.
@findex morse-region
@findex unmorse-region
+@findex nato-region
@cindex Morse code
@cindex --/---/.-./.../.
-@kbd{M-x morse-region} converts text in a region to Morse code and
-@kbd{M-x unmorse-region} converts it back. No cause for remorse.
+ @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
-@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing
-bats.
-
-@findex solitaire
-@cindex solitaire
-@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
-across other pegs.
-
-@findex studlify-region
-@cindex StudlyCaps
-@kbd{M-x studlify-region} studlify-cases the region, producing
-text like this:
-
-@example
-M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
-@end example
-
@findex tetris
@cindex Tetris
@findex snake
@cindex Snake
-@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
-Likewise, @kbd{M-x snake} provides an implementation of Snake.
-
- When you are frustrated, try the famous Eliza program. Just do
-@kbd{M-x doctor}. End each input by typing @key{RET} twice.
+ @kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are
+implementations of the well-known Pong, Snake and Tetris games.
-@cindex Zippy
- When you are feeling strange, type @kbd{M-x yow}.
+@findex solitaire
+@cindex solitaire
+ @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
+across other pegs.
@findex zone
-The command @kbd{M-x zone} plays games with the display when Emacs is
-idle.
+ The command @kbd{M-x zone} plays games with the display when Emacs
+is idle.
+
+@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
-
-@ignore
- arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474
-@end ignore
HCoop / bpt / emacs.git / blobdiff