1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
6 @chapter Miscellaneous Commands
8 This chapter contains several brief topics that do not fit anywhere
9 else: viewing ``document files'', reading netnews, running shell
10 commands and shell subprocesses, using a single shared Emacs for
11 utilities that expect to run an editor as a subprocess, printing
12 hardcopy, sorting text, narrowing display to part of the buffer,
13 editing double-column files and binary files, saving an Emacs session
14 for later resumption, following hyperlinks, browsing images, emulating
15 other editors, and various diversions and amusements.
23 @node Document View, Gnus, Calendar/Diary, Top
24 @section Document Viewing
28 @cindex Postscript file
31 @cindex document viewer (DocView)
34 DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript
35 (PS), and PDF documents. It provides features such as slicing,
36 zooming, and searching inside documents. It works by converting the
37 document to a set of images using the @command{gs} (GhostScript)
38 command, and displaying those images.
40 @findex doc-view-toggle-display
41 @findex doc-view-toggle-display
42 @cindex doc-view-minor-mode
43 When you visit a PDF or DVI file, Emacs automatically switches to
44 DocView mode. When you visit a Postscript file, Emacs switches to PS
45 mode, a major mode for editing Postscript files as text; however, it
46 also enables DocView minor mode, so you can type @kbd{C-c C-c} to view
47 the document with DocView. (PDF and DVI files, unlike Postscript
48 files, are not usually human-editable.) In either case, repeating
49 @kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView
52 You can explicitly toggle DocView mode with the command @code{M-x
53 doc-view-mode}, and DocView minor mode with the command @code{M-x
56 When DocView mode starts, it displays a welcome screen and begins
57 formatting the file, page by page. It displays the first page once
58 that has been formatted.
60 @findex doc-view-enlarge
61 @findex doc-view-shrink
62 @vindex doc-view-resolution
63 When in DocView mode, you can enlarge or shrink the document with
64 @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
65 (@code{doc-view-shrink}). To specify the default size for DocView,
66 set or customize the variable @code{doc-view-resolution}.
68 To kill the DocView buffer, type @kbd{k}
69 (@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q}
73 * Navigation:: Navigation inside DocView buffers.
74 * Searching:: Searching inside documents.
75 * Slicing:: Specifing which part of pages should be displayed.
76 * Conversion:: Influencing and triggering converison.
80 @subsection Navigation
82 When in DocView mode, you can scroll the current page using the usual
83 Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
86 @findex doc-view-next-page
87 @findex doc-view-previous-page
88 To display the next page, type @kbd{n}, @key{next} or @kbd{C-x ]}
89 (@code{doc-view-next-page}). To display the previous page, type
90 @kbd{p}, @key{prior} or @kbd{C-x [} (@code{doc-view-previous-page}).
92 @findex doc-view-scroll-up-or-next-page
93 @findex doc-view-scroll-down-or-previous-page
94 The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a
95 convenient way to advance through the document. It scrolls within the
96 current page or advances to the next. @key{DEL} moves backwards in a
97 similar way (@code{doc-view-scroll-down-or-previous-page}).
99 @findex doc-view-first-page
100 @findex doc-view-last-page
101 @findex doc-view-goto-page
102 To go to the first page, type @kbd{M-<}
103 (@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
104 (@code{doc-view-last-page}). To jump to a page by its number, type
105 @kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
108 @subsection Searching
110 While in DocView mode, you can search the file's text for a regular
111 expression (@pxref{Regexps}). The interface for searching is inspired
112 by @code{isearch} (@pxref{Incremental Search}).
114 @findex doc-view-search
115 @findex doc-view-search-backward
116 @findex doc-view-show-tooltip
117 To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
118 @kbd{C-r} (@code{doc-view-search-backward}). This reads a regular
119 expression using a minibuffer, then echoes the number of matches found
120 within the document. You can move forward and back among the matches
121 by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show
122 the match inside the page image; instead, it displays a tooltip (at
123 the mouse position) listing all matching lines in the current page.
124 To force display of this tooltip, type @kbd{C-t}
125 (@code{doc-view-show-tooltip}).
127 To start a new search, use the search command with a prefix
128 argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
129 for a backward search.
134 Documents often have wide margins for printing. They are annoying
135 when reading the document on the screen, because they use up screen
136 space and can cause inconvenient scrolling.
138 @findex doc-view-set-slice
139 @findex doc-view-set-slice-using-mouse
140 With DocView you can hide these margins by selecting a @dfn{slice}
141 of pages to display. A slice is a rectangle within the page area;
142 once you specify a slice in DocView, it applies to whichever page you
145 To specify the slice numerically, type @kbd{s s}
146 (@code{doc-view-set-slice}); then enter the top left pixel position
147 and the slice's width and height.
148 @c ??? how does this work?
150 A more convenient graphical way to specify the slice is with @kbd{s
151 m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
153 @c ??? How does this work?
155 @findex doc-view-reset-slice
156 To cancel the selected slice, type @kbd{s r}
157 (@code{doc-view-reset-slice}). Then DocView shows the entire page
158 including its entire margins.
161 @subsection Conversion
163 @vindex doc-view-cache-directory
164 @findex doc-view-clear-cache
165 For efficiency, DocView caches the images produced by @command{gs}.
166 The name of this directory is given by the variable
167 @code{doc-view-cache-directory}. You can clear the cache directory by
168 typing @code{M-x doc-view-clear-cache}.
170 @findex doc-view-kill-proc
171 @findex doc-view-kill-proc-and-buffer
172 To force a reconversion of the currently viewed document, type
173 @kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter
174 process associated with the current buffer, type @kbd{K}
175 (@code{doc-view-kill-proc}). The command @kbd{k}
176 (@code{doc-view-kill-proc-and-buffer}) kills the converter process and
179 The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
180 (@code{doc-view-shrink}) need to reconvert the document at the new
181 size. The current page is converted first.
183 @node Gnus, Shell, Document View, Top
186 @cindex reading netnews
188 Gnus is an Emacs package primarily designed for reading and posting
189 Usenet news. It can also be used to read and respond to messages from a
190 number of other sources---mail, remote directories, digests, and so on.
192 Here we introduce Gnus and describe several basic features.
194 For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
197 For full details on Gnus, type @kbd{M-x info} and then select the Gnus
202 To start Gnus, type @kbd{M-x gnus @key{RET}}.
205 * Buffers of Gnus:: The group, summary, and article buffers.
206 * Gnus Startup:: What you should know about starting Gnus.
207 * Summary of Gnus:: A short description of the basic Gnus commands.
210 @node Buffers of Gnus
211 @subsection Gnus Buffers
213 Unlike most Emacs packages, Gnus uses several buffers to display
214 information and to receive commands. The three Gnus buffers users use
215 most are the @dfn{group buffer}, the @dfn{summary buffer} and the
216 @dfn{article buffer}.
218 The @dfn{group buffer} contains a list of newsgroups. This is the
219 first buffer Gnus displays when it starts up. It normally displays
220 only the groups to which you subscribe and that contain unread
221 articles. Use this buffer to select a specific group.
223 The @dfn{summary buffer} lists one line for each article in a single
224 group. By default, the author, the subject and the line number are
225 displayed for each article, but this is customizable, like most aspects
226 of Gnus display. The summary buffer is created when you select a group
227 in the group buffer, and is killed when you exit the group. Use this
228 buffer to select an article.
230 The @dfn{article buffer} displays the article. In normal Gnus usage,
231 you see this buffer but you don't select it---all useful
232 article-oriented commands work in the summary buffer. But you can
233 select the article buffer, and execute all Gnus commands from that
234 buffer, if you want to.
237 @subsection When Gnus Starts Up
239 At startup, Gnus reads your @file{.newsrc} news initialization file
240 and attempts to communicate with the local news server, which is a
241 repository of news articles. The news server need not be the same
242 computer you are logged in on.
244 If you start Gnus and connect to the server, but do not see any
245 newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get
246 a listing of all the groups. Then type @kbd{u} to toggle
247 subscription to groups.
249 The first time you start Gnus, Gnus subscribes you to a few selected
250 groups. All other groups start out as @dfn{killed groups} for you; you
251 can list them with @kbd{A k}. All new groups that subsequently come to
252 exist at the news server become @dfn{zombie groups} for you; type @kbd{A
253 z} to list them. You can subscribe to a group shown in these lists
254 using the @kbd{u} command.
256 When you quit Gnus with @kbd{q}, it automatically records in your
257 @file{.newsrc} and @file{.newsrc.eld} initialization files the
258 subscribed or unsubscribed status of all groups. You should normally
259 not edit these files manually, but you may if you know how.
261 @node Summary of Gnus
262 @subsection Summary of Gnus Commands
264 Reading news is a two-step process:
268 Choose a group in the group buffer.
271 Select articles from the summary buffer. Each article selected is
272 displayed in the article buffer in a large window, below the summary
273 buffer in its small window.
276 Each Gnus buffer has its own special commands; the meanings of any
277 given key in the various Gnus buffers are usually analogous, even if
278 not identical. Here are commands for the group and summary buffers:
281 @kindex q @r{(Gnus Group mode)}
282 @findex gnus-group-exit
284 In the group buffer, update your @file{.newsrc} initialization file
287 In the summary buffer, exit the current group and return to the
288 group buffer. Thus, typing @kbd{q} twice quits Gnus.
290 @kindex L @r{(Gnus Group mode)}
291 @findex gnus-group-list-all-groups
293 In the group buffer, list all the groups available on your news
294 server (except those you have killed). This may be a long list!
296 @kindex l @r{(Gnus Group mode)}
297 @findex gnus-group-list-groups
299 In the group buffer, list only the groups to which you subscribe and
300 which contain unread articles.
302 @kindex u @r{(Gnus Group mode)}
303 @findex gnus-group-unsubscribe-current-group
304 @cindex subscribe groups
305 @cindex unsubscribe groups
307 In the group buffer, unsubscribe from (or subscribe to) the group listed
308 in the line that point is on. When you quit Gnus by typing @kbd{q},
309 Gnus lists in your @file{.newsrc} file which groups you have subscribed
310 to. The next time you start Gnus, you won't see this group,
311 because Gnus normally displays only subscribed-to groups.
313 @kindex C-k @r{(Gnus)}
314 @findex gnus-group-kill-group
316 In the group buffer, ``kill'' the current line's group---don't
317 even list it in @file{.newsrc} from now on. This affects future
318 Gnus sessions as well as the present session.
320 When you quit Gnus by typing @kbd{q}, Gnus writes information
321 in the file @file{.newsrc} describing all newsgroups except those you
324 @kindex SPC @r{(Gnus)}
325 @findex gnus-group-read-group
327 In the group buffer, select the group on the line under the cursor
328 and display the first unread article in that group.
331 In the summary buffer,
335 Select the article on the line under the cursor if none is selected.
338 Scroll the text of the selected article (if there is one).
341 Select the next unread article if at the end of the current article.
344 Thus, you can move through all the articles by repeatedly typing @key{SPC}.
346 @kindex DEL @r{(Gnus)}
348 In the group buffer, move point to the previous group containing
351 @findex gnus-summary-prev-page
352 In the summary buffer, scroll the text of the article backwards.
355 @findex gnus-group-next-unread-group
356 @findex gnus-summary-next-unread-article
358 Move point to the next unread group, or select the next unread article.
361 @findex gnus-group-prev-unread-group
362 @findex gnus-summary-prev-unread-article
364 Move point to the previous unread group, or select the previous
367 @kindex C-n @r{(Gnus Group mode)}
368 @findex gnus-group-next-group
369 @kindex C-p @r{(Gnus Group mode)}
370 @findex gnus-group-prev-group
371 @kindex C-n @r{(Gnus Summary mode)}
372 @findex gnus-summary-next-subject
373 @kindex C-p @r{(Gnus Summary mode)}
374 @findex gnus-summary-prev-subject
377 Move point to the next or previous item, even if it is marked as read.
378 This does not select the article or group on that line.
380 @kindex s @r{(Gnus Summary mode)}
381 @findex gnus-summary-isearch-article
383 In the summary buffer, do an incremental search of the current text in
384 the article buffer, just as if you switched to the article buffer and
387 @kindex M-s @r{(Gnus Summary mode)}
388 @findex gnus-summary-search-article-forward
389 @item M-s @var{regexp} @key{RET}
390 In the summary buffer, search forward for articles containing a match
397 @subsection Where to Look Further
399 @c Too many references to the name of the manual if done with xref in TeX!
400 Gnus is powerful and customizable. Here are references to a few
406 additional topics in @cite{The Gnus Manual}:
410 Follow discussions on specific topics.@*
411 See section ``Threading.''
414 Read digests. See section ``Document Groups.''
417 Refer to and jump to the parent of the current article.@*
418 See section ``Finding the Parent.''
421 Refer to articles by using Message-IDs included in the messages.@*
422 See section ``Article Keymap.''
425 Save articles. See section ``Saving Articles.''
428 Have Gnus score articles according to various criteria, like author
429 name, subject, or string in the body of the articles.@*
430 See section ``Scoring.''
433 Send an article to a newsgroup.@*
434 See section ``Composing Messages.''
440 Follow discussions on specific topics.@*
441 @xref{Threading, , Reading Based on Conversation Threads,
442 gnus, The Gnus Manual}.
445 Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}.
448 Refer to and jump to the parent of the current article.@*
449 @xref{Finding the Parent, , , gnus, The Gnus Manual}.
452 Refer to articles by using Message-IDs included in the messages.@*
453 @xref{Article Keymap, , , gnus, The Gnus Manual}.
456 Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}.
459 Have Gnus score articles according to various criteria, like author
460 name, subject, or string in the body of the articles.@*
461 @xref{Scoring, , , gnus, The Gnus Manual}.
464 Send an article to a newsgroup.@*
465 @xref{Composing Messages, , , gnus, The Gnus Manual}.
470 @node Shell, Emacs Server, Gnus, Top
471 @section Running Shell Commands from Emacs
473 @cindex shell commands
475 Emacs has commands for passing single command lines to inferior shell
476 processes; it can also run a shell interactively with input and output
477 to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
481 @item M-! @var{cmd} @key{RET}
482 Run the shell command line @var{cmd} and display the output
483 (@code{shell-command}).
484 @item M-| @var{cmd} @key{RET}
485 Run the shell command line @var{cmd} with region contents as input;
486 optionally replace the region with the output
487 (@code{shell-command-on-region}).
489 Run a subshell with input and output through an Emacs buffer.
490 You can then give commands interactively.
492 Run a subshell with input and output through an Emacs buffer.
493 You can then give commands interactively.
494 Full terminal emulation is available.
497 @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It
498 is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell,
499 Eshell: The Emacs Shell}.
502 * Single Shell:: How to run one shell command and return.
503 * Interactive Shell:: Permanent shell taking input via Emacs.
504 * Shell Mode:: Special Emacs commands used with permanent shell.
505 * Shell Prompts:: Two ways to recognize shell prompts.
506 * History: Shell History. Repeating previous commands in a shell buffer.
507 * Directory Tracking:: Keeping track when the subshell changes directory.
508 * Options: Shell Options. Options for customizing Shell mode.
509 * Terminal emulator:: An Emacs window as a terminal emulator.
510 * Term Mode:: Special Emacs commands used in Term mode.
511 * Paging in Term:: Paging in the terminal emulator.
512 * Remote Host:: Connecting to another computer.
513 * Serial Terminal:: Connecting to a serial port.
517 @subsection Single Shell Commands
520 @findex shell-command
521 @kbd{M-!} (@code{shell-command}) reads a line of text using the
522 minibuffer and executes it as a shell command in a subshell made just
523 for that command. Standard input for the command comes from the null
524 device. If the shell command produces any output, the output appears
525 either in the echo area (if it is short), or in an Emacs buffer named
526 @samp{*Shell Command Output*}, which is displayed in another window
527 but not selected (if the output is long).
529 For instance, one way to decompress a file @file{foo.gz} from Emacs
530 is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command
531 normally creates the file @file{foo} and produces no terminal output.
533 A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
534 output into the current buffer instead of a separate buffer. It puts
535 point before the output, and sets the mark after the output. For
536 instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
537 uncompressed equivalent of @file{foo.gz} into the current buffer.
539 If the shell command line ends in @samp{&}, it runs asynchronously.
540 For a synchronous shell command, @code{shell-command} returns the
541 command's exit status (0 means success), when it is called from a Lisp
542 program. You do not get any status information for an asynchronous
543 command, since it hasn't finished yet when @code{shell-command} returns.
546 @findex shell-command-on-region
547 @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
548 passes the contents of the region as the standard input to the shell
549 command, instead of no input. With a numeric argument, meaning insert
550 the output in the current buffer, it deletes the old region and the
551 output replaces it as the contents of the region. It returns the
552 command's exit status, like @kbd{M-!}.
554 One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
555 the buffer. For instance, if the buffer contains a GPG key, type
556 @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to
557 the @code{gpg} program. That program will ignore everything except
558 the encoded keys, and will output a list of the keys the buffer
561 @vindex shell-file-name
562 Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify
563 the shell to use. This variable is initialized based on your
564 @env{SHELL} environment variable when Emacs is started. If the file
565 name is relative, Emacs searches the directories in the list
566 @code{exec-path}; this list is initialized based on the environment
567 variable @env{PATH} when Emacs is started. Your init file can
568 override either or both of these default initializations (@pxref{Init
571 Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
572 unless you end the command with @samp{&} to make it asynchronous. To
573 stop waiting, type @kbd{C-g} to quit; that terminates the shell
574 command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
575 normally generates in the shell. Emacs then waits until the command
576 actually terminates. If the shell command doesn't stop (because it
577 ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
578 the command a @code{SIGKILL} signal which is impossible to ignore.
580 Asynchronous commands ending in @samp{&} feed their output into
581 the buffer @samp{*Async Shell Command*}. Output arrives in that
582 buffer regardless of whether it is visible in a window.
584 To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
585 @kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}.
587 @vindex shell-command-default-error-buffer
588 Error output from these commands is normally intermixed with the
589 regular output. But if the variable
590 @code{shell-command-default-error-buffer} has a string as value, and
591 it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output
592 before point in that buffer.
594 @node Interactive Shell
595 @subsection Interactive Inferior Shell
598 To run a subshell interactively, use @kbd{M-x shell}. This creates
599 (or reuses) a buffer named @samp{*shell*} and runs a subshell with
600 input coming from and output going to that buffer. That is to say,
601 any ``terminal output'' from the subshell goes into the buffer,
602 advancing point, and any ``terminal input'' for the subshell comes
603 from text in the buffer. To give input to the subshell, go to the end
604 of the buffer and type the input, terminated by @key{RET}.
606 Emacs does not wait for the subshell to do anything. You can switch
607 windows or buffers and edit them while the shell is waiting, or while it is
608 running a command. Output from the subshell waits until Emacs has time to
609 process it; this happens whenever Emacs is waiting for keyboard input or
612 @cindex @code{comint-highlight-input} face
613 @cindex @code{comint-highlight-prompt} face
614 Input lines, once you submit them, are displayed using the face
615 @code{comint-highlight-input}, and prompts are displayed using the
616 face @code{comint-highlight-prompt}. This makes it easier to see
617 previous input lines in the buffer. @xref{Faces}.
619 To make multiple subshells, you can invoke @kbd{M-x shell} with a
620 prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
621 name and create (or reuse) a subshell in that buffer. You can also
622 rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
623 create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
624 Subshells in different buffers run independently and in parallel.
626 @vindex explicit-shell-file-name
627 @cindex environment variables for subshells
628 @cindex @env{ESHELL} environment variable
629 @cindex @env{SHELL} environment variable
630 The file name used to load the subshell is the value of the variable
631 @code{explicit-shell-file-name}, if that is non-@code{nil}.
632 Otherwise, the environment variable @env{ESHELL} is used, or the
633 environment variable @env{SHELL} if there is no @env{ESHELL}. If the
634 file name specified is relative, the directories in the list
635 @code{exec-path} are searched; this list is initialized based on the
636 environment variable @env{PATH} when Emacs is started. Your init file
637 can override either or both of these default initializations.
640 Emacs sends the new shell the contents of the file
641 @file{~/.emacs_@var{shellname}} as input, if it exists, where
642 @var{shellname} is the name of the file that the shell was loaded
643 from. For example, if you use bash, the file sent to it is
644 @file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback
645 on @file{~/.emacs.d/init_@var{shellname}.sh}.
647 To specify a coding system for the shell, you can use the command
648 @kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can
649 also change the coding system for a running subshell by typing
650 @kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication
653 @cindex @env{INSIDE_EMACS} environment variable
654 Emacs sets the environment variable @env{INSIDE_EMACS} in the
655 subshell to a comma-separated list including the Emacs version.
656 Programs can check this variable to determine whether they are running
657 inside an Emacs subshell.
659 @cindex @env{EMACS} environment variable
660 Emacs also sets the @env{EMACS} environment variable (to @code{t}) if
661 it is not already defined. @strong{Warning:} This environment
662 variable is deprecated. Programs that check this variable should be
663 changed to check @env{INSIDE_EMACS} instead.
666 @subsection Shell Mode
670 Shell buffers use Shell mode, which defines several special keys
671 attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
672 editing and job control characters present in shells that are not under
673 Emacs, except that you must type @kbd{C-c} first. Here is a complete list
674 of the special key bindings of Shell mode:
678 @kindex RET @r{(Shell mode)}
679 @findex comint-send-input
680 At end of buffer send line as input; otherwise, copy current line to
681 end of buffer and send it (@code{comint-send-input}). Copying a line
682 in this way omits any prompt at the beginning of the line (text output
683 by programs preceding your input). @xref{Shell Prompts}, for how
684 Shell mode recognizes prompts.
687 @kindex TAB @r{(Shell mode)}
688 @findex comint-dynamic-complete
689 Complete the command name or file name before point in the shell buffer
690 (@code{comint-dynamic-complete}). @key{TAB} also completes history
691 references (@pxref{History References}) and environment variable names.
693 @vindex shell-completion-fignore
694 @vindex comint-completion-fignore
695 The variable @code{shell-completion-fignore} specifies a list of file
696 name extensions to ignore in Shell mode completion. The default
697 setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
698 ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other
699 related Comint modes use the variable @code{comint-completion-fignore}
703 @kindex M-? @r{(Shell mode)}
704 @findex comint-dynamic-list-filename@dots{}
705 Display temporarily a list of the possible completions of the file name
706 before point in the shell buffer
707 (@code{comint-dynamic-list-filename-completions}).
710 @kindex C-d @r{(Shell mode)}
711 @findex comint-delchar-or-maybe-eof
712 Either delete a character or send @acronym{EOF}
713 (@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
714 buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other
715 position in the buffer, @kbd{C-d} deletes a character as usual.
718 @kindex C-c C-a @r{(Shell mode)}
719 @findex comint-bol-or-process-mark
720 Move to the beginning of the line, but after the prompt if any
721 (@code{comint-bol-or-process-mark}). If you repeat this command twice
722 in a row, the second time it moves back to the process mark, which is
723 the beginning of the input that you have not yet sent to the subshell.
724 (Normally that is the same place---the end of the prompt on this
725 line---but after @kbd{C-c @key{SPC}} the process mark may be in a
729 Accumulate multiple lines of input, then send them together. This
730 command inserts a newline before point, but does not send the preceding
731 text as input to the subshell---at least, not yet. Both lines, the one
732 before this newline and the one after, will be sent together (along with
733 the newline that separates them), when you type @key{RET}.
736 @kindex C-c C-u @r{(Shell mode)}
737 @findex comint-kill-input
738 Kill all text pending at end of buffer to be sent as input
739 (@code{comint-kill-input}). If point is not at end of buffer,
740 this only kills the part of this text that precedes point.
743 @kindex C-c C-w @r{(Shell mode)}
744 Kill a word before point (@code{backward-kill-word}).
747 @kindex C-c C-c @r{(Shell mode)}
748 @findex comint-interrupt-subjob
749 Interrupt the shell or its current subjob if any
750 (@code{comint-interrupt-subjob}). This command also kills
751 any shell input pending in the shell buffer and not yet sent.
754 @kindex C-c C-z @r{(Shell mode)}
755 @findex comint-stop-subjob
756 Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
757 This command also kills any shell input pending in the shell buffer and
761 @findex comint-quit-subjob
762 @kindex C-c C-\ @r{(Shell mode)}
763 Send quit signal to the shell or its current subjob if any
764 (@code{comint-quit-subjob}). This command also kills any shell input
765 pending in the shell buffer and not yet sent.
768 @kindex C-c C-o @r{(Shell mode)}
769 @findex comint-delete-output
770 Delete the last batch of output from a shell command
771 (@code{comint-delete-output}). This is useful if a shell command spews
772 out lots of output that just gets in the way. This command used to be
773 called @code{comint-kill-output}.
776 @kindex C-c C-s @r{(Shell mode)}
777 @findex comint-write-output
778 Write the last batch of output from a shell command to a file
779 (@code{comint-write-output}). With a prefix argument, the file is
780 appended to instead. Any prompt at the end of the output is not
785 @kindex C-c C-r @r{(Shell mode)}
786 @kindex C-M-l @r{(Shell mode)}
787 @findex comint-show-output
788 Scroll to display the beginning of the last batch of output at the top
789 of the window; also move the cursor there (@code{comint-show-output}).
792 @kindex C-c C-e @r{(Shell mode)}
793 @findex comint-show-maximum-output
794 Scroll to put the end of the buffer at the bottom of the window
795 (@code{comint-show-maximum-output}).
798 @kindex C-c C-f @r{(Shell mode)}
799 @findex shell-forward-command
800 @vindex shell-command-regexp
801 Move forward across one shell command, but not beyond the current line
802 (@code{shell-forward-command}). The variable @code{shell-command-regexp}
803 specifies how to recognize the end of a command.
806 @kindex C-c C-b @r{(Shell mode)}
807 @findex shell-backward-command
808 Move backward across one shell command, but not beyond the current line
809 (@code{shell-backward-command}).
812 Ask the shell what its current directory is, so that Emacs can agree
815 @item M-x send-invisible @key{RET} @var{text} @key{RET}
816 @findex send-invisible
817 Send @var{text} as input to the shell, after reading it without
818 echoing. This is useful when a shell command runs a program that asks
821 Please note that Emacs will not echo passwords by default. If you
822 really want them to be echoed, evaluate the following Lisp
826 (remove-hook 'comint-output-filter-functions
827 'comint-watch-for-password-prompt)
830 @item M-x comint-continue-subjob
831 @findex comint-continue-subjob
832 Continue the shell process. This is useful if you accidentally suspend
833 the shell process.@footnote{You should not suspend the shell process.
834 Suspending a subjob of the shell is a completely different matter---that
835 is normal practice, but you must use the shell to continue the subjob;
836 this command won't do it.}
838 @item M-x comint-strip-ctrl-m
839 @findex comint-strip-ctrl-m
840 Discard all control-M characters from the current group of shell output.
841 The most convenient way to use this command is to make it run
842 automatically when you get output from the subshell. To do that,
843 evaluate this Lisp expression:
846 (add-hook 'comint-output-filter-functions
847 'comint-strip-ctrl-m)
850 @item M-x comint-truncate-buffer
851 @findex comint-truncate-buffer
852 This command truncates the shell buffer to a certain maximum number of
853 lines, specified by the variable @code{comint-buffer-maximum-size}.
854 Here's how to do this automatically each time you get output from the
858 (add-hook 'comint-output-filter-functions
859 'comint-truncate-buffer)
865 Shell mode is a derivative of Comint mode, a general-purpose mode for
866 communicating with interactive subprocesses. Most of the features of
867 Shell mode actually come from Comint mode, as you can see from the
868 command names listed above. The special features of Shell mode include
869 the directory tracking feature, and a few user commands.
871 Other Emacs features that use variants of Comint mode include GUD
872 (@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
875 You can use @kbd{M-x comint-run} to execute any program of your choice
876 in a subprocess using unmodified Comint mode---without the
877 specializations of Shell mode.
880 @subsection Shell Prompts
882 @vindex shell-prompt-pattern
883 @vindex comint-prompt-regexp
884 @vindex comint-use-prompt-regexp
885 @cindex prompt, shell
886 A prompt is text output by a program to show that it is ready to
887 accept new user input. Normally, Comint mode (and thus Shell mode)
888 considers the prompt to be any text output by a program at the
889 beginning of an input line. However, if the variable
890 @code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode
891 uses a regular expression to recognize prompts. In Shell mode,
892 @code{shell-prompt-pattern} specifies the regular expression.
894 The value of @code{comint-use-prompt-regexp} also affects many
895 motion and paragraph commands. If the value is non-@code{nil}, the
896 general Emacs motion commands behave as they normally do in buffers
897 without special text properties. However, if the value is @code{nil},
898 the default, then Comint mode divides the buffer into two types of
899 ``fields'' (ranges of consecutive characters having the same
900 @code{field} text property): input and output. Prompts are part of
901 the output. Most Emacs motion commands do not cross field boundaries,
902 unless they move over multiple lines. For instance, when point is in
903 input on the same line as a prompt, @kbd{C-a} puts point at the
904 beginning of the input if @code{comint-use-prompt-regexp} is
905 @code{nil} and at the beginning of the line otherwise.
907 In Shell mode, only shell prompts start new paragraphs. Thus, a
908 paragraph consists of a prompt and the input and output that follow
909 it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the
910 default, most paragraph commands do not cross field boundaries. This
911 means that prompts, ranges of input, and ranges of non-prompt output
912 behave mostly like separate paragraphs; with this setting, numeric
913 arguments to most paragraph commands yield essentially undefined
914 behavior. For the purpose of finding paragraph boundaries, Shell mode
915 uses @code{shell-prompt-pattern}, regardless of
916 @code{comint-use-prompt-regexp}.
919 @subsection Shell Command History
921 Shell buffers support three ways of repeating earlier commands. You
922 can use keys like those used for the minibuffer history; these work
923 much as they do in the minibuffer, inserting text from prior commands
924 while point remains always at the end of the buffer. You can move
925 through the buffer to previous inputs in their original place, then
926 resubmit them or copy them to the end. Or you can use a
927 @samp{!}-style history reference.
930 * Ring: Shell Ring. Fetching commands from the history list.
931 * Copy: Shell History Copying. Moving to a command and then copying it.
932 * History References:: Expanding @samp{!}-style history references.
936 @subsubsection Shell History Ring
939 @findex comint-previous-input
940 @kindex M-p @r{(Shell mode)}
943 Fetch the next earlier old shell command.
945 @kindex M-n @r{(Shell mode)}
946 @findex comint-next-input
949 Fetch the next later old shell command.
951 @kindex M-r @r{(Shell mode)}
952 @kindex M-s @r{(Shell mode)}
953 @findex comint-previous-matching-input
954 @findex comint-next-matching-input
955 @item M-r @var{regexp} @key{RET}
956 @itemx M-s @var{regexp} @key{RET}
957 Search backwards or forwards for old shell commands that match @var{regexp}.
960 @kindex C-c C-x @r{(Shell mode)}
961 @findex comint-get-next-from-history
962 Fetch the next subsequent command from the history.
965 @kindex C-c . @r{(Shell mode)}
966 @findex comint-input-previous-argument
967 Fetch one argument from an old shell command.
970 @kindex C-c C-l @r{(Shell mode)}
971 @findex comint-dynamic-list-input-ring
972 Display the buffer's history of shell commands in another window
973 (@code{comint-dynamic-list-input-ring}).
976 Shell buffers provide a history of previously entered shell commands. To
977 reuse shell commands from the history, use the editing commands @kbd{M-p},
978 @kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer
979 history commands except that they operate on the text at the end of the
980 shell buffer, where you would normally insert text to send to the shell.
982 @kbd{M-p} fetches an earlier shell command to the end of the shell
983 buffer. Successive use of @kbd{M-p} fetches successively earlier
984 shell commands, each replacing any text that was already present as
985 potential shell input. @kbd{M-n} does likewise except that it finds
986 successively more recent shell commands from the buffer.
987 @kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
990 The history search commands @kbd{M-r} and @kbd{M-s} read a regular
991 expression and search through the history for a matching command. Aside
992 from the choice of which command to fetch, they work just like @kbd{M-p}
993 and @kbd{M-n}. If you enter an empty regexp, these commands reuse the
994 same regexp used last time.
996 When you find the previous input you want, you can resubmit it by
997 typing @key{RET}, or you can edit it first and then resubmit it if you
998 wish. Any partial input you were composing before navigating the
999 history list is restored when you go to the beginning or end of the
1002 Often it is useful to reexecute several successive shell commands that
1003 were previously executed in sequence. To do this, first find and
1004 reexecute the first command of the sequence. Then type @kbd{C-c C-x};
1005 that will fetch the following command---the one that follows the command
1006 you just repeated. Then type @key{RET} to reexecute this command. You
1007 can reexecute several successive commands by typing @kbd{C-c C-x
1008 @key{RET}} over and over.
1010 The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
1011 copies an individual argument from a previous command, like @kbd{ESC
1012 .} in Bash. The simplest use copies the last argument from the
1013 previous shell command. With a prefix argument @var{n}, it copies the
1014 @var{n}th argument instead. Repeating @kbd{C-c .} copies from an
1015 earlier shell command instead, always using the same value of @var{n}
1016 (don't give a prefix argument when you repeat the @kbd{C-c .}
1019 These commands get the text of previous shell commands from a special
1020 history list, not from the shell buffer itself. Thus, editing the shell
1021 buffer, or even killing large parts of it, does not affect the history
1022 that these commands access.
1024 @vindex shell-input-ring-file-name
1025 Some shells store their command histories in files so that you can
1026 refer to commands from previous shell sessions. Emacs reads
1027 the command history file for your chosen shell, to initialize its own
1028 command history. The file name is @file{~/.bash_history} for bash,
1029 @file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
1031 @node Shell History Copying
1032 @subsubsection Shell History Copying
1035 @kindex C-c C-p @r{(Shell mode)}
1036 @findex comint-previous-prompt
1038 Move point to the previous prompt (@code{comint-previous-prompt}).
1040 @kindex C-c C-n @r{(Shell mode)}
1041 @findex comint-next-prompt
1043 Move point to the following prompt (@code{comint-next-prompt}).
1045 @kindex C-c RET @r{(Shell mode)}
1046 @findex comint-copy-old-input
1048 Copy the input command at point, inserting the copy at the end of the
1049 buffer (@code{comint-copy-old-input}). This is useful if you move
1050 point back to a previous command. After you copy the command, you can
1051 submit the copy as input with @key{RET}. If you wish, you can edit
1052 the copy before resubmitting it. If you use this command on an output
1053 line, it copies that line to the end of the buffer.
1056 If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
1057 the old input command that you click on, inserting the copy at the end
1058 of the buffer (@code{comint-insert-input}). If
1059 @code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
1060 not over old input, just yank as usual.
1063 Moving to a previous input and then copying it with @kbd{C-c
1064 @key{RET}} or @kbd{Mouse-2} produces the same results---the same
1065 buffer contents---that you would get by using @kbd{M-p} enough times
1066 to fetch that previous input from the history list. However, @kbd{C-c
1067 @key{RET}} copies the text from the buffer, which can be different
1068 from what is in the history list if you edit the input text in the
1069 buffer after it has been sent.
1071 @node History References
1072 @subsubsection Shell History References
1073 @cindex history reference
1075 Various shells including csh and bash support @dfn{history
1076 references} that begin with @samp{!} and @samp{^}. Shell mode
1077 recognizes these constructs, and can perform the history substitution
1080 If you insert a history reference and type @key{TAB}, this searches
1081 the input history for a matching command, performs substitution if
1082 necessary, and places the result in the buffer in place of the history
1083 reference. For example, you can fetch the most recent command
1084 beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the
1085 command if you wish, and then resubmit the command to the shell by
1088 @vindex comint-input-autoexpand
1089 @findex comint-magic-space
1090 Shell mode can optionally expand history references in the buffer
1091 when you send them to the shell. To request this, set the variable
1092 @code{comint-input-autoexpand} to @code{input}. You can make
1093 @key{SPC} perform history expansion by binding @key{SPC} to the
1094 command @code{comint-magic-space}.
1096 Shell mode recognizes history references when they follow a prompt.
1097 @xref{Shell Prompts}, for how Shell mode recognizes prompts.
1099 @node Directory Tracking
1100 @subsection Directory Tracking
1101 @cindex directory tracking
1103 @vindex shell-pushd-regexp
1104 @vindex shell-popd-regexp
1105 @vindex shell-cd-regexp
1106 Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
1107 commands given to the inferior shell, so it can keep the
1108 @samp{*shell*} buffer's default directory the same as the shell's
1109 working directory. It recognizes these commands syntactically, by
1110 examining lines of input that are sent.
1112 If you use aliases for these commands, you can tell Emacs to
1113 recognize them also. For example, if the value of the variable
1114 @code{shell-pushd-regexp} matches the beginning of a shell command
1115 line, that line is regarded as a @code{pushd} command. Change this
1116 variable when you add aliases for @samp{pushd}. Likewise,
1117 @code{shell-popd-regexp} and @code{shell-cd-regexp} are used to
1118 recognize commands with the meaning of @samp{popd} and @samp{cd}.
1119 These commands are recognized only at the beginning of a shell command
1122 @ignore @c This seems to have been deleted long ago.
1123 @vindex shell-set-directory-error-hook
1124 If Emacs gets an error while trying to handle what it believes is a
1125 @samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
1126 @code{shell-set-directory-error-hook} (@pxref{Hooks}).
1130 If Emacs gets confused about changes in the current directory of the
1131 subshell, use the command @kbd{M-x dirs} to ask the shell what its
1132 current directory is. This command works for shells that support the
1133 most common command syntax; it may not work for unusual shells.
1135 @findex dirtrack-mode
1136 You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
1137 alternative method of tracking changes in the current directory. This
1138 method relies on your shell prompt containing the full current working
1139 directory at all times.
1142 @subsection Shell Mode Options
1144 @vindex comint-scroll-to-bottom-on-input
1145 If the variable @code{comint-scroll-to-bottom-on-input} is
1146 non-@code{nil}, insertion and yank commands scroll the selected window
1147 to the bottom before inserting. The default is @code{nil}.
1149 @vindex comint-scroll-show-maximum-output
1150 If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
1151 arrival of output when point is at the end tries to scroll the last
1152 line of text to the bottom line of the window, showing as much useful
1153 text as possible. (This mimics the scrolling behavior of most
1154 terminals.) The default is @code{t}.
1156 @vindex comint-move-point-for-output
1157 By setting @code{comint-move-point-for-output}, you can opt for
1158 having point jump to the end of the buffer whenever output arrives---no
1159 matter where in the buffer point was before. If the value is
1160 @code{this}, point jumps in the selected window. If the value is
1161 @code{all}, point jumps in each window that shows the Comint buffer. If
1162 the value is @code{other}, point jumps in all nonselected windows that
1163 show the current buffer. The default value is @code{nil}, which means
1164 point does not jump to the end.
1166 @vindex comint-prompt-read-only
1167 If you set @code{comint-prompt-read-only}, the prompts in the Comint
1168 buffer are read-only.
1170 @vindex comint-input-ignoredups
1171 The variable @code{comint-input-ignoredups} controls whether successive
1172 identical inputs are stored in the input history. A non-@code{nil}
1173 value means to omit an input that is the same as the previous input.
1174 The default is @code{nil}, which means to store each input even if it is
1175 equal to the previous input.
1177 @vindex comint-completion-addsuffix
1178 @vindex comint-completion-recexact
1179 @vindex comint-completion-autolist
1180 Three variables customize file name completion. The variable
1181 @code{comint-completion-addsuffix} controls whether completion inserts a
1182 space or a slash to indicate a fully completed file or directory name
1183 (non-@code{nil} means do insert a space or slash).
1184 @code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
1185 to choose the shortest possible completion if the usual Emacs completion
1186 algorithm cannot add even a single character.
1187 @code{comint-completion-autolist}, if non-@code{nil}, says to list all
1188 the possible completions whenever completion is not exact.
1190 @vindex shell-completion-execonly
1191 Command completion normally considers only executable files.
1192 If you set @code{shell-completion-execonly} to @code{nil},
1193 it considers nonexecutable files as well.
1195 @findex shell-pushd-tohome
1196 @findex shell-pushd-dextract
1197 @findex shell-pushd-dunique
1198 You can configure the behavior of @samp{pushd}. Variables control
1199 whether @samp{pushd} behaves like @samp{cd} if no argument is given
1200 (@code{shell-pushd-tohome}), pop rather than rotate with a numeric
1201 argument (@code{shell-pushd-dextract}), and only add directories to the
1202 directory stack if they are not already on it
1203 (@code{shell-pushd-dunique}). The values you choose should match the
1204 underlying shell, of course.
1206 If you want Shell mode to handle color output from shell commands,
1207 you can enable ANSI Color mode. Here is how to do this:
1210 (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
1213 @node Terminal emulator
1214 @subsection Emacs Terminal Emulator
1217 To run a subshell in a terminal emulator, use @kbd{M-x term}. This
1218 creates (or reuses) a buffer named @samp{*terminal*}, and runs a
1219 subshell with input coming from your keyboard, and output going to
1222 The terminal emulator uses Term mode, which has two input modes. In
1223 line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
1225 In char mode, each character is sent directly to the inferior
1226 subshell, as ``terminal input.'' Any ``echoing'' of your input is the
1227 responsibility of the subshell. The sole exception is the terminal
1228 escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
1229 Any ``terminal output'' from the subshell goes into the buffer,
1232 Some programs (such as Emacs itself) need to control the appearance
1233 on the terminal screen in detail. They do this by sending special
1234 control codes. The exact control codes needed vary from terminal to
1235 terminal, but nowadays most terminals and terminal emulators
1236 (including @code{xterm}) understand the ANSI-standard (VT100-style)
1237 escape sequences. Term mode recognizes these escape sequences, and
1238 handles each one appropriately, changing the buffer so that the
1239 appearance of the window matches what it would be on a real terminal.
1240 You can actually run Emacs inside an Emacs Term window.
1242 You can use Term mode to communicate with a device connected to a
1243 serial port of your computer. @xref{Serial Terminal}.
1245 The file name used to load the subshell is determined the same way
1246 as for Shell mode. To make multiple terminal emulators, rename the
1247 buffer @samp{*terminal*} to something different using @kbd{M-x
1248 rename-uniquely}, just as with Shell mode.
1250 Unlike Shell mode, Term mode does not track the current directory by
1251 examining your input. But some shells can tell Term what the current
1252 directory is. This is done automatically by @code{bash} version 1.15
1256 @subsection Term Mode
1260 The terminal emulator uses Term mode, which has two input modes. In
1261 line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
1262 In char mode, each character is sent directly to the inferior
1263 subshell, except for the Term escape character, normally @kbd{C-c}.
1265 To switch between line and char mode, use these commands:
1268 @kindex C-c C-j @r{(Term mode)}
1269 @findex term-char-mode
1271 Switch to line mode. Do nothing if already in line mode.
1273 @kindex C-c C-k @r{(Term mode)}
1274 @findex term-line-mode
1276 Switch to char mode. Do nothing if already in char mode.
1279 The following commands are only available in char mode:
1283 Send a literal @key{C-c} to the sub-shell.
1285 @item C-c @var{char}
1286 This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For
1287 example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
1288 is normally @samp{other-window}.
1291 @node Paging in Term
1292 @subsection Page-At-A-Time Output
1293 @cindex page-at-a-time
1295 Term mode has a page-at-a-time feature. When enabled it makes
1296 output pause at the end of each screenful.
1299 @kindex C-c C-q @r{(Term mode)}
1300 @findex term-pager-toggle
1302 Toggle the page-at-a-time feature. This command works in both line
1303 and char modes. When page-at-a-time is enabled, the mode-line
1304 displays the word @samp{page}.
1307 With page-at-a-time enabled, whenever Term receives more than a
1308 screenful of output since your last input, it pauses, displaying
1309 @samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
1310 screenful of output. Type @kbd{?} to see your other options. The
1311 interface is similar to the @code{more} program.
1314 @subsection Remote Host Shell
1316 @cindex connecting to remote host
1320 You can login to a remote computer, using whatever commands you
1321 would from a regular terminal (e.g.@: using the @code{telnet} or
1322 @code{rlogin} commands), from a Term window.
1324 A program that asks you for a password will normally suppress
1325 echoing of the password, so the password will not show up in the
1326 buffer. This will happen just as if you were using a real terminal,
1327 if the buffer is in char mode. If it is in line mode, the password is
1328 temporarily visible, but will be erased when you hit return. (This
1329 happens automatically; there is no special password processing.)
1331 When you log in to a different machine, you need to specify the type
1332 of terminal you're using, by setting the @env{TERM} environment
1333 variable in the environment for the remote login command. (If you use
1334 bash, you do that by writing the variable assignment before the remote
1335 login command, without separating comma.) Terminal types @samp{ansi}
1336 or @samp{vt100} will work on most systems.
1338 @c If you are talking to a Bourne-compatible
1339 @c shell, and your system understands the @env{TERMCAP} variable,
1340 @c you can use the command @kbd{M-x shell-send-termcap}, which
1341 @c sends a string specifying the terminal type and size.
1342 @c (This command is also useful after the window has changed size.)
1344 @c You can of course run @samp{gdb} on that remote computer. One useful
1345 @c trick: If you invoke gdb with the @code{--fullname} option,
1346 @c it will send special commands to Emacs that will cause Emacs to
1347 @c pop up the source files you're debugging. This will work
1348 @c whether or not gdb is running on a different computer than Emacs,
1349 @c as long as Emacs can access the source files specified by gdb.
1352 You cannot log in to a remote computer using the Shell mode.
1353 @c (This will change when Shell is re-written to use Term.)
1354 Instead, Emacs provides two commands for logging in to another computer
1355 and communicating with it through an Emacs buffer using Comint mode:
1358 @item M-x telnet @key{RET} @var{hostname} @key{RET}
1359 Set up a Telnet connection to the computer named @var{hostname}.
1360 @item M-x rlogin @key{RET} @var{hostname} @key{RET}
1361 Set up an Rlogin connection to the computer named @var{hostname}.
1365 Use @kbd{M-x telnet} to set up a Telnet connection to another
1366 computer. (Telnet is the standard Internet protocol for remote login.)
1367 It reads the host name of the other computer as an argument with the
1368 minibuffer. Once the connection is established, talking to the other
1369 computer works like talking to a subshell: you can edit input with the
1370 usual Emacs commands, and send it a line at a time by typing @key{RET}.
1371 The output is inserted in the Telnet buffer interspersed with the input.
1374 @vindex rlogin-explicit-args
1375 Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is
1376 another remote login communication protocol, essentially much like the
1377 Telnet protocol but incompatible with it, and supported only by certain
1378 systems. Rlogin's advantages are that you can arrange not to have to
1379 give your user name and password when communicating between two machines
1380 you frequently use, and that you can make an 8-bit-clean connection.
1381 (To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")}
1382 before you run Rlogin.)
1384 @kbd{M-x rlogin} sets up the default file directory of the Emacs
1385 buffer to access the remote host via FTP (@pxref{File Names}), and it
1386 tracks the shell commands that change the current directory, just like
1389 @findex rlogin-directory-tracking-mode
1390 There are two ways of doing directory tracking in an Rlogin
1391 buffer---either with remote directory names
1392 @file{/@var{host}:@var{dir}/} or with local names (that works if the
1393 ``remote'' machine shares file systems with your machine of origin).
1394 You can use the command @code{rlogin-directory-tracking-mode} to switch
1395 modes. No argument means use remote directory names, a positive
1396 argument means use local names, and a negative argument means turn
1397 off directory tracking.
1401 @node Serial Terminal
1402 @subsection Serial Terminal
1403 @cindex terminal, serial
1406 If you have a device connected to a serial port of your computer,
1407 you can use Emacs to communicate with it. @kbd{M-x serial-term} will
1408 ask you for a serial port name and speed and will then open a new
1409 window in @ref{Term Mode}.
1411 The speed of the serial port is measured in bits per second. The
1412 most common speed is 9600 bits per second. You can change the speed
1413 interactively by clicking on the mode line.
1415 A serial port can be configured even more by clicking on ``8N1'' in
1416 the mode line. By default, a serial port is configured as ``8N1'',
1417 which means that each byte consists of 8 data bits, No parity check
1420 When you have opened the serial port connection, you will see output
1421 from the device in the window. Also, what you type in the window is
1424 If the speed or the configuration is wrong, you cannot communicate
1425 with your device and will probably only see garbage output in the
1428 @node Emacs Server, Printing, Shell, Top
1429 @section Using Emacs as a Server
1431 @cindex Emacs as a server
1432 @cindex server, using Emacs as
1433 @cindex @env{EDITOR} environment variable
1435 Various programs such as @command{mail} can invoke your choice of
1436 editor to edit a particular piece of text, such as a message that you
1437 are sending. By convention, most of these programs use the
1438 environment variable @env{EDITOR} to specify which editor to run. If
1439 you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
1440 inconvenient way, by starting a new Emacs process. This is
1441 inconvenient because the new Emacs process doesn't share buffers, a
1442 command history, or other kinds of information with any existing Emacs
1445 You can solve this problem by setting up Emacs as an @dfn{edit
1446 server}, so that it ``listens'' for external edit requests and acts
1447 accordingly. There are two ways to start an Emacs server:
1449 @findex server-start
1450 The first is to run the command @code{server-start} in an existing
1451 Emacs process: either type @kbd{M-x server-start}, or put the
1452 expression @code{(server-start)} in your initialization file
1453 (@pxref{Init File}). The existing Emacs process is the server; when
1454 you exit Emacs, the server dies with the Emacs process.
1456 @cindex daemon, Emacs
1457 The second way to start an Emacs server is to run Emacs as a
1458 @dfn{daemon}, using the @samp{--daemon} command-line option.
1459 @xref{Initial Options}. When Emacs is started this way, it calls
1460 @code{server-start} after initialization, and returns control to the
1461 calling terminal instead of opening an initial frame; it then waits in
1462 the background, listening for edit requests.
1464 @cindex @env{TEXEDIT} environment variable
1465 Once an Emacs server is set up, you can use a shell command called
1466 @command{emacsclient} to connect to the existing Emacs process and
1467 tell it to visit a file. If you set the @env{EDITOR} environment
1468 variable to @samp{emacsclient}, programs such as @command{mail} will
1469 use the existing Emacs process for editing.@footnote{Some programs use
1470 a different environment variable; for example, to make @TeX{} use
1471 @samp{emacsclient}, set the @env{TEXEDIT} environment variable to
1472 @samp{emacsclient +%d %s}.}
1475 You can run multiple Emacs servers on the same machine by giving
1476 each one a unique ``server name'', using the variable
1477 @code{server-name}. For example, @kbd{M-x set-variable @key{RET}
1478 server-name @key{RET} foo @key{RET}} sets the server name to
1479 @samp{foo}. The @code{emacsclient} program can specify a server by
1480 name, using the @samp{-s} option (@pxref{emacsclient Options}).
1483 * Invoking emacsclient:: Connecting to the Emacs server.
1484 * emacsclient Options:: Emacs client startup options.
1487 @node Invoking emacsclient
1488 @subsection Invoking @code{emacsclient}
1489 @cindex @code{emacsclient} invocation
1491 The simplest way to use the @command{emacsclient} program is to run
1492 the shell command @samp{emacsclient @var{file}}, where @var{file} is a
1493 file name. This connects to an Emacs server, and tells that Emacs
1494 process to visit @var{file} in one of its existing frames---either a
1495 graphical frame, or one in a text-only terminal (@pxref{Frames}). You
1496 can then select that frame to begin editing.
1498 If there is no Emacs server, the @command{emacsclient} program halts
1499 with an error message. If the Emacs process has no existing
1500 frame---which can happen if it was started as a daemon (@pxref{Emacs
1501 Server})---then Emacs opens a frame on the terminal in which you
1502 called @command{emacsclient}, as though you had used the @samp{-t}
1503 option (@pxref{emacsclient Options}).
1505 On a graphical display, switching to the Emacs server is
1506 straightforward---just select its (system-level) window. If you are
1507 using a text-only terminal, there are two ways to switch between
1508 @command{emacsclient}'s shell and the Emacs server: (i) run the Emacs
1509 server and @command{emacsclient} on different virtual terminals, and
1510 switch to the Emacs server's virtual terminal after calling
1511 @command{emacsclient}; or (ii) call @command{emacsclient} from within
1512 the Emacs server itself, using Shell mode (@pxref{Interactive Shell})
1513 or Term mode (@pxref{Term Mode}); @code{emacsclient} blocks only the
1514 subshell under Emacs, and you can still use Emacs to edit the file.
1518 When you finish editing @var{file} in the Emacs server, type
1519 @kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file
1520 and sends a message back to the @command{emacsclient} program, telling
1521 it to exit. Programs that use @env{EDITOR} usually wait for the
1522 ``editor''---in the case @command{emacsclient}---to exit before doing
1525 You can also call @command{emacsclient} with multiple file name
1526 arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
1527 Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs
1528 selects the buffer visiting @var{file1}, and buries the other buffers
1529 at the bottom of the buffer list (@pxref{Buffers}). The
1530 @command{emacsclient} program exits once all the specified files are
1531 finished (i.e., once you have typed @kbd{C-x #} in each server
1534 @vindex server-kill-new-buffers
1535 @vindex server-temp-file-regexp
1536 Finishing with a server buffer also kills the buffer, unless it
1537 already existed in the Emacs session before the server was asked to
1538 create it. However, if you set @code{server-kill-new-buffers} to
1539 @code{nil}, then a different criterion is used: finishing with a
1540 server buffer kills it if the file name matches the regular expression
1541 @code{server-temp-file-regexp}. This is set up to distinguish certain
1542 ``temporary'' files.
1544 Each @kbd{C-x #} checks for other pending external requests to edit
1545 various files, and selects the next such file. You can switch to a
1546 server buffer manually if you wish; you don't have to arrive at it
1547 with @kbd{C-x #}. But @kbd{C-x #} is the way to tell
1548 @command{emacsclient} that you are finished.
1550 @vindex server-window
1551 If you set the variable @code{server-window} to a window or a frame,
1552 @kbd{C-x #} always displays the next server buffer in that window or
1555 @node emacsclient Options
1556 @subsection @code{emacsclient} Options
1557 @cindex @code{emacsclient} options
1559 You can pass some optional arguments to the @command{emacsclient}
1563 emacsclient -c +12 @var{file1} +4:3 @var{file2}
1567 The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments
1568 specify line numbers, or line and column numbers, for the next file
1569 argument. These behave like the command line arguments for Emacs
1570 itself. @xref{Action Arguments}.
1572 The other optional arguments recognized by @command{emacsclient} are
1576 @item -a @var{command}
1577 @itemx --alternate-editor=@var{command}
1578 Specify a command to run if @code{emacsclient} fails to contact Emacs.
1579 This is useful when running @code{emacsclient} in a script. For
1580 example, the following setting for the @env{EDITOR} environment
1581 variable will always give you an editor, even if no Emacs server is
1585 EDITOR="emacsclient --alternate-editor emacs +%d %s"
1589 As a special exception, if @var{command} is the empty string, then
1590 @code{emacsclient} starts Emacs in daemon mode and then tries
1593 @cindex @env{ALTERNATE_EDITOR} environment variable
1594 The environment variable @env{ALTERNATE_EDITOR} has the same effect as
1595 the @samp{-a} option. If both are present, the latter takes
1599 Create a new graphical frame, instead of using an existing Emacs
1600 frame. Emacs 23 can create a graphical frame even if it was started
1601 in a text-only terminal, provided it is able to connect to a graphical
1602 display. If no graphical display is available, Emacs creates a new
1603 text-only terminal frame (@pxref{Frames}). If you omit a filename
1604 argument while supplying the @samp{-c} option, the new frame displays
1605 the @samp{*scratch*} buffer (@pxref{Buffers}).
1607 @item -d @var{display}
1608 @itemx --display=@var{display}
1609 Tell Emacs to open the given files on the X display @var{display}
1610 (assuming there is more than one X display available).
1614 Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
1615 files. When this option is given, the arguments to
1616 @command{emacsclient} are interpreted as a list of expressions to
1617 evaluate, @emph{not} as a list of files to visit.
1619 @item -f @var{server-file}
1620 @itemx --server-file=@var{server-file}
1621 @cindex @env{EMACS_SERVER_FILE} environment variable
1623 @vindex server-use-tcp
1625 Specify a @dfn{server file} for connecting to an Emacs server via TCP.
1627 An Emacs server usually uses an operating system feature called a
1628 ``local socket'' to listen for connections. Some operating systems,
1629 such as Microsoft Windows, do not support local sockets; in that case,
1630 Emacs uses TCP instead. When you start the Emacs server, Emacs
1631 creates a server file containing some TCP information that
1632 @command{emacsclient} needs for making the connection. By default,
1633 the server file is in @file{~/.emacs.d/server/}. On Microsoft
1634 Windows, if @command{emacsclient} does not find the server file there,
1635 it looks in the @file{.emacs.d/server/} subdirectory of the directory
1636 pointed to by the @env{APPDATA} environment variable. You can tell
1637 @command{emacsclient} to use a specific server file with the @samp{-f}
1638 or @samp{--server-file} option, or by setting the
1639 @env{EMACS_SERVER_FILE} environment variable.
1641 Even if local sockets are available, you can tell Emacs to use TCP by
1642 setting the variable @code{server-use-tcp} to @code{t}. One advantage
1643 of TCP is that the server can accept connections from remote machines.
1644 For this to work, you must (i) set the variable @code{server-host} to
1645 the hostname or IP address of the machine on which the Emacs server
1646 runs, and (ii) provide @command{emacsclient} with the server file.
1647 (One convenient way to do the latter is to put the server file on a
1648 networked file system such as NFS.)
1652 Let @command{emacsclient} exit immediately, instead of waiting until
1653 all server buffers are finished. You can take as long as you like to
1654 edit the server buffers within Emacs, and they are @emph{not} killed
1655 when you type @kbd{C-x #} in them.
1657 @item -s @var{server-name}
1658 @itemx --socket-name=@var{server-name}
1659 Connect to the Emacs server named @var{server-name}. The server name
1660 is given by the variable @code{server-name} on the Emacs server. If
1661 this option is omitted, @command{emacsclient} connects to the first
1662 server it finds. (This option is not supported on MS-Windows.)
1667 Create a new Emacs frame on the current text-only terminal, instead of
1668 using an existing Emacs frame. Emacs 23 can open a text-only terminal
1669 even if it was started in another text-only terminal, or on a
1670 graphical display. If you omit a filename argument while supplying
1671 this option, the new frame displays the @samp{*scratch*} buffer.
1675 If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
1676 Emacs frame created with @command{emacsclient}, via the @samp{-c} or
1677 @samp{-t} options, Emacs deletes the frame instead of killing the
1678 Emacs process itself. On a text-only terminal frame created with the
1679 @samp{-t} option, this returns control to the terminal. Emacs also
1680 marks all the server buffers for the client as finished, as though you
1681 had typed @kbd{C-x #} in all of them.
1683 When Emacs is started as a daemon, all frames are considered client
1684 frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs
1685 process, type @kbd{M-x kill-emacs}.
1687 @node Printing, Sorting, Emacs Server, Top
1688 @section Printing Hard Copies
1692 Emacs provides commands for printing hard copies of either an entire
1693 buffer or just part of one, with or without page headers. You can
1694 invoke the printing commands directly, as detailed in the following
1695 section, or using the @samp{File} menu on the menu bar. See also the
1696 hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary
1697 (@pxref{Displaying the Diary}).
1700 @item M-x print-buffer
1701 Print hardcopy of current buffer with page headings containing the file
1702 name and page number.
1703 @item M-x lpr-buffer
1704 Print hardcopy of current buffer without page headings.
1705 @item M-x print-region
1706 Like @code{print-buffer} but print only the current region.
1707 @item M-x lpr-region
1708 Like @code{lpr-buffer} but print only the current region.
1711 @findex print-buffer
1712 @findex print-region
1715 @vindex lpr-switches
1716 The hardcopy commands (aside from the PostScript commands) pass extra
1717 switches to the @code{lpr} program based on the value of the variable
1718 @code{lpr-switches}. Its value should be a list of strings, each string
1719 an option starting with @samp{-}. For example, to specify a line width
1720 of 80 columns for all the printing you do in Emacs, set
1721 @code{lpr-switches} like this:
1724 (setq lpr-switches '("-w80"))
1727 @vindex printer-name
1728 You can specify the printer to use by setting the variable
1729 @code{printer-name}.
1731 @vindex lpr-headers-switches
1732 @vindex lpr-commands
1733 @vindex lpr-add-switches
1734 The variable @code{lpr-command} specifies the name of the printer
1735 program to run; the default value depends on your operating system type.
1736 On most systems, the default is @code{"lpr"}. The variable
1737 @code{lpr-headers-switches} similarly specifies the extra switches to
1738 use to make page headers. The variable @code{lpr-add-switches} controls
1739 whether to supply @samp{-T} and @samp{-J} options (suitable for
1740 @code{lpr}) to the printer program: @code{nil} means don't add them.
1741 @code{lpr-add-switches} should be @code{nil} if your printer program is
1742 not compatible with @code{lpr}.
1745 * PostScript:: Printing buffers or regions as PostScript.
1746 * PostScript Variables:: Customizing the PostScript printing commands.
1747 * Printing Package:: An optional advanced printing interface.
1750 @node PostScript, PostScript Variables,, Printing
1751 @section PostScript Hardcopy
1753 These commands convert buffer contents to PostScript,
1754 either printing it or leaving it in another Emacs buffer.
1757 @item M-x ps-print-buffer
1758 Print hardcopy of the current buffer in PostScript form.
1759 @item M-x ps-print-region
1760 Print hardcopy of the current region in PostScript form.
1761 @item M-x ps-print-buffer-with-faces
1762 Print hardcopy of the current buffer in PostScript form, showing the
1763 faces used in the text by means of PostScript features.
1764 @item M-x ps-print-region-with-faces
1765 Print hardcopy of the current region in PostScript form, showing the
1766 faces used in the text.
1767 @item M-x ps-spool-buffer
1768 Generate and spool a PostScript image for the current buffer text.
1769 @item M-x ps-spool-region
1770 Generate and spool a PostScript image for the current region.
1771 @item M-x ps-spool-buffer-with-faces
1772 Generate and spool a PostScript image for the current buffer, showing the faces used.
1773 @item M-x ps-spool-region-with-faces
1774 Generate and spool a PostScript image for the current region, showing the faces used.
1775 @item M-x ps-despool
1776 Send the spooled PostScript to the printer.
1778 Generate/print PostScript for the current buffer as if handwritten.
1781 @findex ps-print-region
1782 @findex ps-print-buffer
1783 @findex ps-print-region-with-faces
1784 @findex ps-print-buffer-with-faces
1785 The PostScript commands, @code{ps-print-buffer} and
1786 @code{ps-print-region}, print buffer contents in PostScript form. One
1787 command prints the entire buffer; the other, just the region. The
1788 corresponding @samp{-with-faces} commands,
1789 @code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
1790 use PostScript features to show the faces (fonts and colors) in the text
1791 properties of the text being printed. The @samp{-with-faces} commands only
1792 work if they are used in a window system, so it has a way to determine color
1795 Interactively, when you use a prefix argument (@kbd{C-u}), the command
1796 prompts the user for a file name, and saves the PostScript image in that file
1797 instead of sending it to the printer.
1799 Noninteractively, the argument @var{filename} is treated as follows: if it is
1800 @code{nil}, send the image to the printer. If @var{filename} is a string, save
1801 the PostScript image in a file with that name.
1803 If you are using a color display, you can print a buffer of program
1804 code with color highlighting by turning on Font-Lock mode in that
1805 buffer, and using @code{ps-print-buffer-with-faces}.
1807 @findex ps-spool-region
1808 @findex ps-spool-buffer
1809 @findex ps-spool-region-with-faces
1810 @findex ps-spool-buffer-with-faces
1811 The commands whose names have @samp{spool} instead of @samp{print},
1812 generate the PostScript output in an Emacs buffer instead of sending
1815 Use the command @code{ps-despool} to send the spooled images to the printer.
1818 This command sends the PostScript generated by @samp{-spool-} commands (see
1819 commands above) to the printer.
1821 Interactively, when you use a prefix argument (@kbd{C-u}), the command
1822 prompts the user for a file name, and saves the spooled PostScript image in
1823 that file instead of sending it to the printer.
1825 Noninteractively, the argument @var{filename} is treated as follows: if it is
1826 @code{nil}, send the image to the printer. If @var{filename} is a string, save
1827 the PostScript image in a file with that name.
1831 @kbd{M-x handwrite} is more frivolous. It generates a PostScript
1832 rendition of the current buffer as a cursive handwritten document. It
1833 can be customized in group @code{handwrite}. This function only
1834 supports ISO 8859-1 characters.
1837 The following section describes variables for customizing these commands.
1840 @node PostScript Variables, Printing Package, PostScript, Printing
1841 @section Variables for PostScript Hardcopy
1843 @vindex ps-lpr-command
1844 @vindex ps-lpr-switches
1845 @vindex ps-printer-name
1846 All the PostScript hardcopy commands use the variables
1847 @code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
1848 the output. @code{ps-lpr-command} specifies the command name to run,
1849 @code{ps-lpr-switches} specifies command line options to use, and
1850 @code{ps-printer-name} specifies the printer. If you don't set the
1851 first two variables yourself, they take their initial values from
1852 @code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name}
1853 is @code{nil}, @code{printer-name} is used.
1855 @vindex ps-print-header
1856 The variable @code{ps-print-header} controls whether these commands
1857 add header lines to each page---set it to @code{nil} to turn headers
1860 @cindex color emulation on black-and-white printers
1861 @vindex ps-print-color-p
1862 If your printer doesn't support colors, you should turn off color
1863 processing by setting @code{ps-print-color-p} to @code{nil}. By
1864 default, if the display supports colors, Emacs produces hardcopy output
1865 with color information; on black-and-white printers, colors are emulated
1866 with shades of gray. This might produce illegible output, even if your
1867 screen colors only use shades of gray.
1869 Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to
1870 print colors on black/white printers.
1872 @vindex ps-use-face-background
1873 By default, PostScript printing ignores the background colors of the
1874 faces, unless the variable @code{ps-use-face-background} is
1875 non-@code{nil}. This is to avoid unwanted interference with the zebra
1876 stripes and background image/text.
1878 @vindex ps-paper-type
1879 @vindex ps-page-dimensions-database
1880 The variable @code{ps-paper-type} specifies which size of paper to
1881 format for; legitimate values include @code{a4}, @code{a3},
1882 @code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger},
1883 @code{legal}, @code{letter}, @code{letter-small}, @code{statement},
1884 @code{tabloid}. The default is @code{letter}. You can define
1885 additional paper sizes by changing the variable
1886 @code{ps-page-dimensions-database}.
1888 @vindex ps-landscape-mode
1889 The variable @code{ps-landscape-mode} specifies the orientation of
1890 printing on the page. The default is @code{nil}, which stands for
1891 ``portrait'' mode. Any non-@code{nil} value specifies ``landscape''
1894 @vindex ps-number-of-columns
1895 The variable @code{ps-number-of-columns} specifies the number of
1896 columns; it takes effect in both landscape and portrait mode. The
1899 @vindex ps-font-family
1900 @vindex ps-font-size
1901 @vindex ps-font-info-database
1902 The variable @code{ps-font-family} specifies which font family to use
1903 for printing ordinary text. Legitimate values include @code{Courier},
1904 @code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
1905 @code{Times}. The variable @code{ps-font-size} specifies the size of
1906 the font for ordinary text. It defaults to 8.5 points.
1908 @vindex ps-multibyte-buffer
1909 @cindex Intlfonts for PostScript printing
1910 @cindex fonts for PostScript printing
1911 Emacs supports more scripts and characters than a typical PostScript
1912 printer. Thus, some of the characters in your buffer might not be
1913 printable using the fonts built into your printer. You can augment
1914 the fonts supplied with the printer with those from the GNU Intlfonts
1915 package, or you can instruct Emacs to use Intlfonts exclusively. The
1916 variable @code{ps-multibyte-buffer} controls this: the default value,
1917 @code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1
1918 characters; a value of @code{non-latin-printer} is for printers which
1919 have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean
1920 characters built into them. A value of @code{bdf-font} arranges for
1921 the BDF fonts from the Intlfonts package to be used for @emph{all}
1922 characters. Finally, a value of @code{bdf-font-except-latin}
1923 instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1
1924 characters, and Intlfonts BDF fonts for the rest.
1926 @vindex bdf-directory-list
1927 To be able to use the BDF fonts, Emacs needs to know where to find
1928 them. The variable @code{bdf-directory-list} holds the list of
1929 directories where Emacs should look for the fonts; the default value
1930 includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
1932 Many other customization variables for these commands are defined and
1933 described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
1935 @node Printing Package,, PostScript Variables, Printing
1936 @section Printing Package
1937 @cindex Printing package
1939 The basic Emacs facilities for printing hardcopy can be extended
1940 using the Printing package. This provides an easy-to-use interface
1941 for choosing what to print, previewing PostScript files before
1942 printing, and setting various printing options such as print headers,
1943 landscape or portrait modes, duplex modes, and so forth. On GNU/Linux
1944 or Unix systems, the Printing package relies on the @file{gs} and
1945 @file{gv} utilities, which are distributed as part of the GhostScript
1946 program. On MS-Windows, the @file{gstools} port of Ghostscript can be
1949 @findex pr-interface
1950 To use the Printing package, add @code{(require 'printing)} to your
1951 init file (@pxref{Init File}), followed by @code{(pr-update-menus)}.
1952 This function replaces the usual printing commands in the menu bar
1953 with a @samp{Printing} submenu that contains various printing options.
1954 You can also type @kbd{M-x pr-interface RET}; this creates a
1955 @samp{*Printing Interface*} buffer, similar to a customization buffer,
1956 where you can set the printing options. After selecting what and how
1957 to print, you start the print job using the @samp{Print} button (click
1958 @kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For
1959 further information on the various options, use the @samp{Interface
1962 @node Sorting, Narrowing, Printing, Top
1963 @section Sorting Text
1966 Emacs provides several commands for sorting text in the buffer. All
1967 operate on the contents of the region.
1968 They divide the text of the region into many @dfn{sort records},
1969 identify a @dfn{sort key} for each record, and then reorder the records
1970 into the order determined by the sort keys. The records are ordered so
1971 that their keys are in alphabetical order, or, for numeric sorting, in
1972 numeric order. In alphabetic sorting, all upper-case letters `A' through
1973 `Z' come before lower-case `a', in accord with the @acronym{ASCII} character
1976 The various sort commands differ in how they divide the text into sort
1977 records and in which part of each record is used as the sort key. Most of
1978 the commands make each line a separate sort record, but some commands use
1979 paragraphs or pages as sort records. Most of the sort commands use each
1980 entire sort record as its own sort key, but some use only a portion of the
1981 record as the sort key.
1984 @findex sort-paragraphs
1987 @findex sort-numeric-fields
1988 @vindex sort-numeric-base
1990 @item M-x sort-lines
1991 Divide the region into lines, and sort by comparing the entire
1992 text of a line. A numeric argument means sort into descending order.
1994 @item M-x sort-paragraphs
1995 Divide the region into paragraphs, and sort by comparing the entire
1996 text of a paragraph (except for leading blank lines). A numeric
1997 argument means sort into descending order.
1999 @item M-x sort-pages
2000 Divide the region into pages, and sort by comparing the entire
2001 text of a page (except for leading blank lines). A numeric
2002 argument means sort into descending order.
2004 @item M-x sort-fields
2005 Divide the region into lines, and sort by comparing the contents of
2006 one field in each line. Fields are defined as separated by
2007 whitespace, so the first run of consecutive non-whitespace characters
2008 in a line constitutes field 1, the second such run constitutes field
2011 Specify which field to sort by with a numeric argument: 1 to sort by
2012 field 1, etc. A negative argument means count fields from the right
2013 instead of from the left; thus, minus 1 means sort by the last field.
2014 If several lines have identical contents in the field being sorted, they
2015 keep the same relative order that they had in the original buffer.
2017 @item M-x sort-numeric-fields
2018 Like @kbd{M-x sort-fields} except the specified field is converted
2019 to an integer for each line, and the numbers are compared. @samp{10}
2020 comes before @samp{2} when considered as text, but after it when
2021 considered as a number. By default, numbers are interpreted according
2022 to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or
2023 @samp{0} are interpreted as hexadecimal and octal, respectively.
2025 @item M-x sort-columns
2026 Like @kbd{M-x sort-fields} except that the text within each line
2027 used for comparison comes from a fixed range of columns. See below
2030 @item M-x reverse-region
2031 Reverse the order of the lines in the region. This is useful for
2032 sorting into descending order by fields or columns, since those sort
2033 commands do not have a feature for doing that.
2036 For example, if the buffer contains this:
2039 On systems where clash detection (locking of files being edited) is
2040 implemented, Emacs also checks the first time you modify a buffer
2041 whether the file has changed on disk since it was last visited or
2042 saved. If it has, you are asked to confirm that you want to change
2047 applying @kbd{M-x sort-lines} to the entire buffer produces this:
2050 On systems where clash detection (locking of files being edited) is
2051 implemented, Emacs also checks the first time you modify a buffer
2052 saved. If it has, you are asked to confirm that you want to change
2054 whether the file has changed on disk since it was last visited or
2058 where the upper-case @samp{O} sorts before all lower-case letters. If
2059 you use @kbd{C-u 2 M-x sort-fields} instead, you get this:
2062 implemented, Emacs also checks the first time you modify a buffer
2063 saved. If it has, you are asked to confirm that you want to change
2065 On systems where clash detection (locking of files being edited) is
2066 whether the file has changed on disk since it was last visited or
2070 where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
2071 @samp{systems} and @samp{the}.
2073 @findex sort-columns
2074 @kbd{M-x sort-columns} requires more explanation. You specify the
2075 columns by putting point at one of the columns and the mark at the other
2076 column. Because this means you cannot put point or the mark at the
2077 beginning of the first line of the text you want to sort, this command
2078 uses an unusual definition of ``region'': all of the line point is in is
2079 considered part of the region, and so is all of the line the mark is in,
2080 as well as all the lines in between.
2082 For example, to sort a table by information found in columns 10 to 15,
2083 you could put the mark on column 10 in the first line of the table, and
2084 point on column 15 in the last line of the table, and then run
2085 @code{sort-columns}. Equivalently, you could run it with the mark on
2086 column 15 in the first line and point on column 10 in the last line.
2088 This can be thought of as sorting the rectangle specified by point and
2089 the mark, except that the text on each line to the left or right of the
2090 rectangle moves along with the text inside the rectangle.
2093 @vindex sort-fold-case
2094 Many of the sort commands ignore case differences when comparing, if
2095 @code{sort-fold-case} is non-@code{nil}.
2097 @node Narrowing, Two-Column, Sorting, Top
2102 @cindex accessible portion
2104 @dfn{Narrowing} means focusing in on some portion of the buffer,
2105 making the rest temporarily inaccessible. The portion which you can
2106 still get to is called the @dfn{accessible portion}. Canceling the
2107 narrowing, which makes the entire buffer once again accessible, is
2108 called @dfn{widening}. The bounds of narrowing in effect in a buffer
2109 are called the buffer's @dfn{restriction}.
2111 Narrowing can make it easier to concentrate on a single subroutine or
2112 paragraph by eliminating clutter. It can also be used to limit the
2113 range of operation of a replace command or repeating keyboard macro.
2117 Narrow down to between point and mark (@code{narrow-to-region}).
2119 Widen to make the entire buffer accessible again (@code{widen}).
2121 Narrow down to the current page (@code{narrow-to-page}).
2123 Narrow down to the current defun (@code{narrow-to-defun}).
2126 When you have narrowed down to a part of the buffer, that part appears
2127 to be all there is. You can't see the rest, you can't move into it
2128 (motion commands won't go outside the accessible part), you can't change
2129 it in any way. However, it is not gone, and if you save the file all
2130 the inaccessible text will be saved. The word @samp{Narrow} appears in
2131 the mode line whenever narrowing is in effect.
2134 @findex narrow-to-region
2135 The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
2136 It sets the current buffer's restrictions so that the text in the current
2137 region remains accessible, but all text before the region or after the
2138 region is inaccessible. Point and mark do not change.
2141 @findex narrow-to-page
2143 @findex narrow-to-defun
2144 Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
2145 down to the current page. @xref{Pages}, for the definition of a page.
2146 @kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
2147 containing point (@pxref{Defuns}).
2151 The way to cancel narrowing is to widen with @kbd{C-x n w}
2152 (@code{widen}). This makes all text in the buffer accessible again.
2154 You can get information on what part of the buffer you are narrowed down
2155 to using the @kbd{C-x =} command. @xref{Position Info}.
2157 Because narrowing can easily confuse users who do not understand it,
2158 @code{narrow-to-region} is normally a disabled command. Attempting to use
2159 this command asks for confirmation and gives you the option of enabling it;
2160 if you enable the command, confirmation will no longer be required for
2161 it. @xref{Disabling}.
2163 @node Two-Column, Editing Binary Files, Narrowing, Top
2164 @section Two-Column Editing
2165 @cindex two-column editing
2166 @cindex splitting columns
2167 @cindex columns, splitting
2169 Two-column mode lets you conveniently edit two side-by-side columns of
2170 text. It uses two side-by-side windows, each showing its own
2173 There are three ways to enter two-column mode:
2176 @item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
2179 @findex 2C-two-columns
2180 Enter two-column mode with the current buffer on the left, and on the
2181 right, a buffer whose name is based on the current buffer's name
2182 (@code{2C-two-columns}). If the right-hand buffer doesn't already
2183 exist, it starts out empty; the current buffer's contents are not
2186 This command is appropriate when the current buffer is empty or contains
2187 just one column and you want to add another column.
2189 @item @kbd{@key{F2} s} or @kbd{C-x 6 s}
2193 Split the current buffer, which contains two-column text, into two
2194 buffers, and display them side by side (@code{2C-split}). The current
2195 buffer becomes the left-hand buffer, but the text in the right-hand
2196 column is moved into the right-hand buffer. The current column
2197 specifies the split point. Splitting starts with the current line and
2198 continues to the end of the buffer.
2200 This command is appropriate when you have a buffer that already contains
2201 two-column text, and you wish to separate the columns temporarily.
2203 @item @kbd{@key{F2} b @var{buffer} @key{RET}}
2204 @itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
2207 @findex 2C-associate-buffer
2208 Enter two-column mode using the current buffer as the left-hand buffer,
2209 and using buffer @var{buffer} as the right-hand buffer
2210 (@code{2C-associate-buffer}).
2213 @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
2214 is a string that appears on each line between the two columns. You can
2215 specify the width of the separator with a numeric argument to
2216 @kbd{@key{F2} s}; that many characters, before point, constitute the
2217 separator string. By default, the width is 1, so the column separator
2218 is the character before point.
2220 When a line has the separator at the proper place, @kbd{@key{F2} s}
2221 puts the text after the separator into the right-hand buffer, and
2222 deletes the separator. Lines that don't have the column separator at
2223 the proper place remain unsplit; they stay in the left-hand buffer, and
2224 the right-hand buffer gets an empty line to correspond. (This is the
2225 way to write a line that ``spans both columns while in two-column
2226 mode'': write it in the left-hand buffer, and put an empty line in the
2232 The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
2233 (@code{2C-newline}) inserts a newline in each of the two buffers at
2234 corresponding positions. This is the easiest way to add a new line to
2235 the two-column text while editing it in split buffers.
2240 When you have edited both buffers as you wish, merge them with
2241 @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
2242 text from the right-hand buffer as a second column in the other buffer.
2243 To go back to two-column editing, use @kbd{@key{F2} s}.
2247 @findex 2C-dissociate
2248 Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
2249 leaving each as it stands (@code{2C-dissociate}). If the other buffer,
2250 the one not current when you type @kbd{@key{F2} d}, is empty,
2251 @kbd{@key{F2} d} kills it.
2253 @node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top
2254 @section Editing Binary Files
2258 @cindex editing binary files
2260 There is a special major mode for editing binary files: Hexl mode. To
2261 use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
2262 the file. This command converts the file's contents to hexadecimal and
2263 lets you edit the translation. When you save the file, it is converted
2264 automatically back to binary.
2266 You can also use @kbd{M-x hexl-mode} to translate an existing buffer
2267 into hex. This is useful if you visit a file normally and then discover
2268 it is a binary file.
2270 Ordinary text characters overwrite in Hexl mode. This is to reduce
2271 the risk of accidentally spoiling the alignment of data in the file.
2272 There are special commands for insertion. Here is a list of the
2273 commands of Hexl mode:
2275 @c I don't think individual index entries for these commands are useful--RMS.
2278 Insert a byte with a code typed in decimal.
2281 Insert a byte with a code typed in octal.
2284 Insert a byte with a code typed in hex.
2287 Move to the beginning of a 1k-byte ``page.''
2290 Move to the end of a 1k-byte ``page.''
2293 Move to an address specified in hex.
2296 Move to an address specified in decimal.
2299 Leave Hexl mode, going back to the major mode this buffer had before you
2300 invoked @code{hexl-mode}.
2304 Other Hexl commands let you insert strings (sequences) of binary
2305 bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a
2306 hexl-@key{RET}} for details.
2309 @node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
2310 @section Saving Emacs Sessions
2311 @cindex saving sessions
2312 @cindex restore session
2313 @cindex remember editing session
2314 @cindex reload files
2317 Use the desktop library to save the state of Emacs from one session
2318 to another. Once you save the Emacs @dfn{desktop}---the buffers,
2319 their file names, major modes, buffer positions, and so on---then
2320 subsequent Emacs sessions reload the saved desktop.
2322 @findex desktop-save
2323 @vindex desktop-save-mode
2324 You can save the desktop manually with the command @kbd{M-x
2325 desktop-save}. You can also enable automatic saving of the desktop
2326 when you exit Emacs, and automatic restoration of the last saved
2327 desktop when Emacs starts: use the Customization buffer (@pxref{Easy
2328 Customization}) to set @code{desktop-save-mode} to @code{t} for future
2329 sessions, or add this line in your init file (@pxref{Init File}):
2332 (desktop-save-mode 1)
2335 @findex desktop-change-dir
2336 @findex desktop-revert
2337 If you turn on @code{desktop-save-mode} in your init file, then when
2338 Emacs starts, it looks for a saved desktop in the current directory.
2339 Thus, you can have separate saved desktops in different directories,
2340 and the starting directory determines which one Emacs reloads. You
2341 can save the current desktop and reload one saved in another directory
2342 by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x
2343 desktop-revert} reverts to the desktop previously reloaded.
2345 Specify the option @samp{--no-desktop} on the command line when you
2346 don't want it to reload any saved desktop. This turns off
2347 @code{desktop-save-mode} for the current session. Starting Emacs with
2348 the @samp{--no-init-file} option also disables desktop reloading,
2349 since it bypasses the init file, where @code{desktop-save-mode} is
2352 @vindex desktop-restore-eager
2353 By default, all the buffers in the desktop are restored at one go.
2354 However, this may be slow if there are a lot of buffers in the
2355 desktop. You can specify the maximum number of buffers to restore
2356 immediately with the variable @code{desktop-restore-eager}; the
2357 remaining buffers are restored ``lazily,'' when Emacs is idle.
2359 @findex desktop-clear
2360 @vindex desktop-globals-to-clear
2361 @vindex desktop-clear-preserve-buffers-regexp
2362 Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills
2363 all buffers except for internal ones, and clears the global variables
2364 listed in @code{desktop-globals-to-clear}. If you want this to
2365 preserve certain buffers, customize the variable
2366 @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
2367 expression matching the names of buffers not to kill.
2369 If you want to save minibuffer history from one session to
2370 another, use the @code{savehist} library.
2372 @node Recursive Edit, Emulation, Saving Emacs Sessions, Top
2373 @section Recursive Editing Levels
2374 @cindex recursive editing level
2375 @cindex editing level, recursive
2377 A @dfn{recursive edit} is a situation in which you are using Emacs
2378 commands to perform arbitrary editing while in the middle of another
2379 Emacs command. For example, when you type @kbd{C-r} inside of a
2380 @code{query-replace}, you enter a recursive edit in which you can change
2381 the current buffer. On exiting from the recursive edit, you go back to
2382 the @code{query-replace}.
2385 @findex exit-recursive-edit
2386 @cindex exiting recursive edit
2387 @dfn{Exiting} the recursive edit means returning to the unfinished
2388 command, which continues execution. The command to exit is @kbd{C-M-c}
2389 (@code{exit-recursive-edit}).
2391 You can also @dfn{abort} the recursive edit. This is like exiting,
2392 but also quits the unfinished command immediately. Use the command
2393 @kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}.
2395 The mode line shows you when you are in a recursive edit by displaying
2396 square brackets around the parentheses that always surround the major and
2397 minor mode names. Every window's mode line shows this in the same way,
2398 since being in a recursive edit is true of Emacs as a whole rather than
2399 any particular window or buffer.
2401 It is possible to be in recursive edits within recursive edits. For
2402 example, after typing @kbd{C-r} in a @code{query-replace}, you may type a
2403 command that enters the debugger. This begins a recursive editing level
2404 for the debugger, within the recursive editing level for @kbd{C-r}.
2405 Mode lines display a pair of square brackets for each recursive editing
2406 level currently in progress.
2408 Exiting the inner recursive edit (such as with the debugger @kbd{c}
2409 command) resumes the command running in the next level up. When that
2410 command finishes, you can then use @kbd{C-M-c} to exit another recursive
2411 editing level, and so on. Exiting applies to the innermost level only.
2412 Aborting also gets out of only one level of recursive edit; it returns
2413 immediately to the command level of the previous recursive edit. If you
2414 wish, you can then abort the next recursive editing level.
2416 Alternatively, the command @kbd{M-x top-level} aborts all levels of
2417 recursive edits, returning immediately to the top-level command
2418 reader. It also exits the minibuffer, if it is active.
2420 The text being edited inside the recursive edit need not be the same text
2421 that you were editing at top level. It depends on what the recursive edit
2422 is for. If the command that invokes the recursive edit selects a different
2423 buffer first, that is the buffer you will edit recursively. In any case,
2424 you can switch buffers within the recursive edit in the normal manner (as
2425 long as the buffer-switching keys have not been rebound). You could
2426 probably do all the rest of your editing inside the recursive edit,
2427 visiting files and all. But this could have surprising effects (such as
2428 stack overflow) from time to time. So remember to exit or abort the
2429 recursive edit when you no longer need it.
2431 In general, we try to minimize the use of recursive editing levels in
2432 GNU Emacs. This is because they constrain you to ``go back'' in a
2433 particular order---from the innermost level toward the top level. When
2434 possible, we present different activities in separate buffers so that
2435 you can switch between them as you please. Some commands switch to a
2436 new major mode which provides a command to switch back. These
2437 approaches give you more flexibility to go back to unfinished tasks in
2438 the order you choose.
2440 @node Emulation, Hyperlinking, Recursive Edit, Top
2442 @cindex emulating other editors
2443 @cindex other editors
2446 @cindex PC key bindings
2447 @cindex scrolling all windows
2448 @cindex PC selection
2449 @cindex Motif key bindings
2450 @cindex Macintosh key bindings
2453 GNU Emacs can be programmed to emulate (more or less) most other
2454 editors. Standard facilities can emulate these:
2457 @item CRiSP/Brief (PC editor)
2459 @vindex crisp-override-meta-x
2460 @findex scroll-all-mode
2462 @cindex Brief emulation
2463 @cindex emulation of Brief
2465 You can turn on key bindings to emulate the CRiSP/Brief editor with
2466 @kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs
2467 unless you set the variable @code{crisp-override-meta-x}. You can
2468 also use the command @kbd{M-x scroll-all-mode} or set the variable
2469 @code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature
2470 (scrolling all windows together).
2472 @item EDT (DEC VMS editor)
2473 @findex edt-emulation-on
2474 @findex edt-emulation-off
2475 Turn on EDT emulation with the command @kbd{M-x edt-emulation-on},
2476 while @kbd{M-x edt-emulation-off} restores normal Emacs command
2479 Most of the EDT emulation commands are keypad keys, and most standard
2480 Emacs key bindings are still available. The EDT emulation rebindings
2481 are done in the global keymap, so there is no problem switching
2482 buffers or major modes while in EDT emulation.
2484 @item TPU (DEC VMS editor)
2487 @kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT.
2489 @item vi (Berkeley editor)
2491 Viper is the newest emulator for vi. It implements several levels of
2492 emulation; level 1 is closest to vi itself, while level 5 departs
2493 somewhat from strict emulation to take advantage of the capabilities of
2494 Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you
2495 the rest of the way and ask for the emulation level. @inforef{Top,
2498 @item vi (another emulator)
2500 @kbd{M-x vi-mode} enters a major mode that replaces the previously
2501 established major mode. All of the vi commands that, in real vi, enter
2502 ``input'' mode are programmed instead to return to the previous major
2503 mode. Thus, ordinary Emacs serves as vi's ``input'' mode.
2505 Because vi emulation works through major modes, it does not work
2506 to switch buffers during emulation. Return to normal Emacs first.
2508 If you plan to use vi emulation much, you probably want to bind a key
2509 to the @code{vi-mode} command.
2511 @item vi (alternate emulator)
2513 @kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi
2514 more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator
2515 is changed from ordinary Emacs so you can use @key{ESC} to go back to
2516 emulated vi command mode. To get from emulated vi command mode back to
2517 ordinary Emacs, type @kbd{C-z}.
2519 This emulation does not work through major modes, and it is possible
2520 to switch buffers in various ways within the emulator. It is not
2521 so necessary to assign a key to the command @code{vip-mode} as
2522 it is with @code{vi-mode} because terminating insert mode does
2525 @inforef{Top, VIP, vip}, for full information.
2527 @item WordStar (old wordprocessor)
2528 @findex wordstar-mode
2529 @kbd{M-x wordstar-mode} provides a major mode with WordStar-like
2533 @node Hyperlinking, Dissociated Press, Emulation, Top
2534 @section Hyperlinking and Navigation Features
2536 @cindex hyperlinking
2538 Various modes documented elsewhere have hypertext features so that
2539 you can follow links, usually by clicking @kbd{Mouse-2} on the link or
2540 typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1}
2541 quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer
2542 if you want to set point instead.)
2544 Info mode, Help mode and the Dired-like modes are examples of modes
2545 that have links in the buffer. The Tags facility links between uses
2546 and definitions in source files, see @ref{Tags}. Imenu provides
2547 navigation amongst items indexed in the current buffer, see
2548 @ref{Imenu}. Info-lookup provides mode-specific lookup of definitions
2549 in Info indexes, see @ref{Documentation}. Speedbar maintains a frame
2550 in which links to files, and locations in files are displayed, see
2553 Other non-mode-specific facilities described in this section enable
2554 following links from the current buffer in a context-sensitive
2558 * Browse-URL:: Following URLs.
2559 * Goto Address mode:: Activating URLs.
2560 * FFAP:: Finding files etc. at point.
2564 @subsection Following URLs
2565 @cindex World Wide Web
2568 @findex browse-url-at-point
2569 @findex browse-url-at-mouse
2574 @item M-x browse-url @key{RET} @var{url} @key{RET}
2575 Load a URL into a Web browser.
2578 The Browse-URL package provides facilities for following URLs specifying
2579 links on the World Wide Web. Usually this works by invoking a web
2580 browser, but you can, for instance, arrange to invoke @code{compose-mail}
2581 from @samp{mailto:} URLs.
2583 The general way to use this feature is to type @kbd{M-x browse-url},
2584 which displays a specified URL. If point is located near a plausible
2585 URL, that URL is used as the default. Other commands are available
2586 which you might like to bind to keys, such as
2587 @code{browse-url-at-point} and @code{browse-url-at-mouse}.
2589 @vindex browse-url-browser-function
2590 You can customize Browse-URL's behavior via various options in the
2591 @code{browse-url} Customize group, particularly
2592 @code{browse-url-browser-function}. You can invoke actions dependent
2593 on the type of URL by defining @code{browse-url-browser-function} as
2594 an association list. The package's commentary available via @kbd{C-h
2595 p} under the @samp{hypermedia} keyword provides more information.
2596 Packages with facilities for following URLs should always go through
2597 Browse-URL, so that the customization options for Browse-URL will
2598 affect all browsing in Emacs.
2600 @node Goto Address mode
2601 @subsection Activating URLs
2602 @findex goto-address-mode
2603 @cindex Goto Address mode
2604 @cindex URLs, activating
2607 @item M-x goto-address-mode
2608 Activate URLs and e-mail addresses in the current buffer.
2611 You can make URLs in the current buffer active with @kbd{M-x
2612 goto-address-mode}. This minor mode finds all the URLs in the buffer,
2613 highlights them, and turns them into @dfn{buttons}: if you click on a
2614 URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or
2615 move to the URL and type @kbd{C-c @key{RET}}, that displays the web
2616 page that the URL specifies. For a @samp{mailto} URL, it sends mail
2617 instead, using your selected mail-composition method (@pxref{Mail
2620 It can be useful to add @code{goto-address-mode} to mode hooks and
2621 the hooks used to display an incoming message (e.g.,
2622 @code{rmail-show-message-hook} for Rmail, and @code{mh-show-mode-hook}
2623 for MH-E). This is not needed for Gnus, which has a similar feature
2627 @subsection Finding Files and URLs at Point
2628 @findex find-file-at-point
2630 @findex dired-at-point
2633 @cindex finding file at point
2635 FFAP mode replaces certain key bindings for finding files, including
2636 @kbd{C-x C-f}, with commands that provide more sensitive defaults.
2637 These commands behave like the ordinary ones when given a prefix
2638 argument. Otherwise, they get the default file name or URL from the
2639 text around point. If what is found in the buffer has the form of a
2640 URL rather than a file name, the commands use @code{browse-url} to
2643 This feature is useful for following references in mail or news
2644 buffers, @file{README} files, @file{MANIFEST} files, and so on. The
2645 @samp{ffap} package's commentary available via @kbd{C-h p} under the
2646 @samp{files} keyword and the @code{ffap} Custom group provide details.
2648 @cindex FFAP minor mode
2650 You can turn on FFAP minor mode by calling @code{ffap-bindings} to
2651 make the following key bindings and to install hooks for using
2652 @code{ffap} in Rmail, Gnus and VM article buffers.
2655 @item C-x C-f @var{filename} @key{RET}
2656 @kindex C-x C-f @r{(FFAP)}
2657 Find @var{filename}, guessing a default from text around point
2658 (@code{find-file-at-point}).
2660 @kindex C-x C-r @r{(FFAP)}
2661 @code{ffap-read-only}, analogous to @code{find-file-read-only}.
2663 @kindex C-x C-v @r{(FFAP)}
2664 @code{ffap-alternate-file}, analogous to @code{find-alternate-file}.
2665 @item C-x d @var{directory} @key{RET}
2666 @kindex C-x d @r{(FFAP)}
2667 Start Dired on @var{directory}, defaulting to the directory name at
2668 point (@code{dired-at-point}).
2670 @code{ffap-list-directory}, analogous to @code{list-directory}.
2672 @kindex C-x 4 f @r{(FFAP)}
2673 @code{ffap-other-window}, analogous to @code{find-file-other-window}.
2675 @code{ffap-read-only-other-window}, analogous to
2676 @code{find-file-read-only-other-window}.
2678 @code{ffap-dired-other-window}, analogous to @code{dired-other-window}.
2680 @kindex C-x 5 f @r{(FFAP)}
2681 @code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
2683 @code{ffap-read-only-other-frame}, analogous to
2684 @code{find-file-read-only-other-frame}.
2686 @code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}.
2688 Search buffer for next file name or URL, then find that file or URL.
2690 @kindex S-Mouse-3 @r{(FFAP)}
2691 @code{ffap-at-mouse} finds the file guessed from text around the position
2694 @kindex C-S-Mouse-3 @r{(FFAP)}
2695 Display a menu of files and URLs mentioned in current buffer, then
2696 find the one you select (@code{ffap-menu}).
2699 @node Dissociated Press, Amusements, Hyperlinking, Top
2700 @section Dissociated Press
2702 @findex dissociated-press
2703 @kbd{M-x dissociated-press} is a command for scrambling a file of text
2704 either word by word or character by character. Starting from a buffer of
2705 straight English, it produces extremely amusing output. The input comes
2706 from the current Emacs buffer. Dissociated Press writes its output in a
2707 buffer named @samp{*Dissociation*}, and redisplays that buffer after every
2708 couple of lines (approximately) so you can read the output as it comes out.
2710 Dissociated Press asks every so often whether to continue generating
2711 output. Answer @kbd{n} to stop it. You can also stop at any time by
2712 typing @kbd{C-g}. The dissociation output remains in the
2713 @samp{*Dissociation*} buffer for you to copy elsewhere if you wish.
2715 @cindex presidentagon
2716 Dissociated Press operates by jumping at random from one point in
2717 the buffer to another. In order to produce plausible output rather
2718 than gibberish, it insists on a certain amount of overlap between the
2719 end of one run of consecutive words or characters and the start of the
2720 next. That is, if it has just output `president' and then decides to
2721 jump to a different point in the buffer, it might spot the `ent' in
2722 `pentagon' and continue from there, producing `presidentagon'. Long
2723 sample texts produce the best results.
2725 @cindex againformation
2726 A positive argument to @kbd{M-x dissociated-press} tells it to operate
2727 character by character, and specifies the number of overlap characters. A
2728 negative argument tells it to operate word by word, and specifies the number
2729 of overlap words. In this mode, whole words are treated as the elements to
2730 be permuted, rather than characters. No argument is equivalent to an
2731 argument of two. For your againformation, the output goes only into the
2732 buffer @samp{*Dissociation*}. The buffer you start with is not changed.
2734 @cindex Markov chain
2736 @cindex techniquitous
2737 Dissociated Press produces results fairly like those of a Markov
2738 chain based on a frequency table constructed from the sample text. It
2739 is, however, an independent, ignoriginal invention. Dissociated Press
2740 techniquitously copies several consecutive characters from the sample
2741 text between random jumps, unlike a Markov chain which would jump
2742 randomly after each word or character. This makes for more plausible
2743 sounding results, and runs faster.
2749 @cindex developediment
2751 It is a mustatement that too much use of Dissociated Press can be a
2752 developediment to your real work, sometimes to the point of outragedy.
2753 And keep dissociwords out of your documentation, if you want it to be well
2754 userenced and properbose. Have fun. Your buggestions are welcome.
2756 @node Amusements, Customization, Dissociated Press, Top
2757 @section Other Amusements
2762 @cindex tower of Hanoi
2764 If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
2765 considerably bored, give it a numeric argument. If you are very, very
2766 bored, try an argument of 9. Sit back and watch.
2769 If you want a little more personal involvement, try @kbd{M-x gomoku},
2770 which plays the game Go Moku with you.
2776 @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles.
2777 @code{blackbox} challenges you to determine the location of objects
2778 inside a box by tomography. @code{mpuz} displays a multiplication
2779 puzzle with letters standing for digits in a code that you must
2780 guess---to guess a value, type a letter and then the digit you think it
2781 stands for. The aim of @code{5x5} is to fill in all the squares.
2785 @cindex cryptanalysis
2786 @kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted
2787 in a simple monoalphabetic substitution cipher.
2790 @kbd{M-x dunnet} runs an adventure-style exploration game, which is
2791 a bigger sort of puzzle.
2794 @cindex landmark game
2795 @kbd{M-x lm} runs a relatively non-participatory game in which a robot
2796 attempts to maneuver towards a tree at the center of the window based on
2797 unique olfactory cues from each of the four directions.
2801 @kbd{M-x life} runs Conway's ``Life'' cellular automaton.
2803 @findex morse-region
2804 @findex unmorse-region
2806 @cindex --/---/.-./.../.
2807 @kbd{M-x morse-region} converts text in a region to Morse code and
2808 @kbd{M-x unmorse-region} converts it back. No cause for remorse.
2812 @kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing
2817 @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
2820 @findex studlify-region
2822 @kbd{M-x studlify-region} studlify-cases the region, producing
2826 M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
2833 @kbd{M-x tetris} runs an implementation of the well-known Tetris game.
2834 Likewise, @kbd{M-x snake} provides an implementation of Snake.
2836 When you are frustrated, try the famous Eliza program. Just do
2837 @kbd{M-x doctor}. End each input by typing @key{RET} twice.
2840 When you are feeling strange, type @kbd{M-x yow}.
2843 The command @kbd{M-x zone} plays games with the display when Emacs is
2851 arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474