Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
b61a98c8 | 2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
5df4f04c | 3 | @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 |
42e96065 | 4 | @c Free Software Foundation, Inc. |
6bf7aab6 DL |
5 | @c See file emacs.texi for copying conditions. |
6 | @iftex | |
7 | @chapter Miscellaneous Commands | |
8 | ||
9 | This chapter contains several brief topics that do not fit anywhere | |
d14202c2 CY |
10 | else: viewing ``document files'', reading netnews, running shell |
11 | commands and shell subprocesses, using a single shared Emacs for | |
12 | utilities that expect to run an editor as a subprocess, printing | |
13 | hardcopy, sorting text, narrowing display to part of the buffer, | |
14 | editing double-column files and binary files, saving an Emacs session | |
15 | for later resumption, following hyperlinks, browsing images, emulating | |
16 | other editors, and various diversions and amusements. | |
6bf7aab6 DL |
17 | |
18 | @end iftex | |
2e7cfad6 LT |
19 | |
20 | @ifnottex | |
21 | @raisesections | |
22 | @end ifnottex | |
23 | ||
3388237a | 24 | @node Document View, Gnus, Calendar/Diary, Top |
3388237a | 25 | @section Document Viewing |
d14202c2 | 26 | @cindex DVI file |
5abad626 RS |
27 | @cindex PDF file |
28 | @cindex PS file | |
d14202c2 | 29 | @cindex Postscript file |
3388237a CY |
30 | @cindex DocView mode |
31 | @cindex mode, DocView | |
5abad626 | 32 | @cindex document viewer (DocView) |
3388237a CY |
33 | @findex doc-view-mode |
34 | ||
d14202c2 CY |
35 | DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript |
36 | (PS), and PDF documents. It provides features such as slicing, | |
37 | zooming, and searching inside documents. It works by converting the | |
38 | document to a set of images using the @command{gs} (GhostScript) | |
39 | command, and displaying those images. | |
3388237a | 40 | |
5abad626 | 41 | @findex doc-view-toggle-display |
3388237a | 42 | @findex doc-view-toggle-display |
d14202c2 CY |
43 | @cindex doc-view-minor-mode |
44 | When you visit a PDF or DVI file, Emacs automatically switches to | |
45 | DocView mode. When you visit a Postscript file, Emacs switches to PS | |
46 | mode, a major mode for editing Postscript files as text; however, it | |
47 | also enables DocView minor mode, so you can type @kbd{C-c C-c} to view | |
48 | the document with DocView. (PDF and DVI files, unlike Postscript | |
49 | files, are not usually human-editable.) In either case, repeating | |
50 | @kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView | |
51 | and the file text. | |
52 | ||
53 | You can explicitly toggle DocView mode with the command @code{M-x | |
54 | doc-view-mode}, and DocView minor mode with the command @code{M-x | |
55 | doc-view-minor-mode}. | |
56 | ||
57 | When DocView mode starts, it displays a welcome screen and begins | |
58 | formatting the file, page by page. It displays the first page once | |
59 | that has been formatted. | |
3388237a CY |
60 | |
61 | @findex doc-view-enlarge | |
62 | @findex doc-view-shrink | |
5abad626 | 63 | @vindex doc-view-resolution |
d14202c2 | 64 | When in DocView mode, you can enlarge or shrink the document with |
5abad626 RS |
65 | @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} |
66 | (@code{doc-view-shrink}). To specify the default size for DocView, | |
67 | set or customize the variable @code{doc-view-resolution}. | |
3388237a | 68 | |
d14202c2 CY |
69 | To kill the DocView buffer, type @kbd{k} |
70 | (@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} | |
71 | (@code{quit-window}). | |
3388237a CY |
72 | |
73 | @menu | |
8838673e GM |
74 | * Navigation:: Navigation inside DocView buffers. |
75 | * Searching:: Searching inside documents. | |
76 | * Slicing:: Specifying which part of pages should be displayed. | |
77 | * Conversion:: Influencing and triggering conversion. | |
3388237a CY |
78 | @end menu |
79 | ||
80 | @node Navigation | |
81 | @subsection Navigation | |
82 | ||
5abad626 | 83 | When in DocView mode, you can scroll the current page using the usual |
d14202c2 CY |
84 | Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and |
85 | the arrow keys. | |
3388237a | 86 | |
0f72a391 CY |
87 | @vindex doc-view-continuous |
88 | By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop | |
89 | scrolling at the beginning and end of the current page, respectively. | |
90 | However, if you change the variable @code{doc-view-continuous} to a | |
91 | non-@code{nil} value, then @kbd{C-p} displays the previous page if you | |
92 | are already at the beginning of the current page, and @kbd{C-n} | |
93 | displays the next page if you are at the end of the current page. | |
94 | ||
3388237a CY |
95 | @findex doc-view-next-page |
96 | @findex doc-view-previous-page | |
0f72a391 CY |
97 | You can also display the next page by typing @kbd{n}, @key{next} or |
98 | @kbd{C-x ]} (@code{doc-view-next-page}). To display the previous | |
99 | page, type @kbd{p}, @key{prior} or @kbd{C-x [} | |
100 | (@code{doc-view-previous-page}). | |
3388237a CY |
101 | |
102 | @findex doc-view-scroll-up-or-next-page | |
103 | @findex doc-view-scroll-down-or-previous-page | |
d14202c2 | 104 | The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a |
5abad626 RS |
105 | convenient way to advance through the document. It scrolls within the |
106 | current page or advances to the next. @key{DEL} moves backwards in a | |
d14202c2 | 107 | similar way (@code{doc-view-scroll-down-or-previous-page}). |
3388237a CY |
108 | |
109 | @findex doc-view-first-page | |
110 | @findex doc-view-last-page | |
3388237a | 111 | @findex doc-view-goto-page |
d14202c2 CY |
112 | To go to the first page, type @kbd{M-<} |
113 | (@code{doc-view-first-page}); to go to the last one, type @kbd{M->} | |
114 | (@code{doc-view-last-page}). To jump to a page by its number, type | |
115 | @kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). | |
3388237a CY |
116 | |
117 | @node Searching | |
118 | @subsection Searching | |
119 | ||
d14202c2 | 120 | While in DocView mode, you can search the file's text for a regular |
5abad626 RS |
121 | expression (@pxref{Regexps}). The interface for searching is inspired |
122 | by @code{isearch} (@pxref{Incremental Search}). | |
3388237a CY |
123 | |
124 | @findex doc-view-search | |
125 | @findex doc-view-search-backward | |
3388237a | 126 | @findex doc-view-show-tooltip |
d14202c2 CY |
127 | To begin a search, type @kbd{C-s} (@code{doc-view-search}) or |
128 | @kbd{C-r} (@code{doc-view-search-backward}). This reads a regular | |
129 | expression using a minibuffer, then echoes the number of matches found | |
130 | within the document. You can move forward and back among the matches | |
131 | by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show | |
132 | the match inside the page image; instead, it displays a tooltip (at | |
133 | the mouse position) listing all matching lines in the current page. | |
134 | To force display of this tooltip, type @kbd{C-t} | |
135 | (@code{doc-view-show-tooltip}). | |
136 | ||
137 | To start a new search, use the search command with a prefix | |
138 | argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} | |
139 | for a backward search. | |
3388237a CY |
140 | |
141 | @node Slicing | |
142 | @subsection Slicing | |
143 | ||
5abad626 RS |
144 | Documents often have wide margins for printing. They are annoying |
145 | when reading the document on the screen, because they use up screen | |
146 | space and can cause inconvenient scrolling. | |
3388237a CY |
147 | |
148 | @findex doc-view-set-slice | |
149 | @findex doc-view-set-slice-using-mouse | |
d14202c2 | 150 | With DocView you can hide these margins by selecting a @dfn{slice} |
5abad626 RS |
151 | of pages to display. A slice is a rectangle within the page area; |
152 | once you specify a slice in DocView, it applies to whichever page you | |
153 | look at. | |
154 | ||
d14202c2 | 155 | To specify the slice numerically, type @kbd{s s} |
5abad626 RS |
156 | (@code{doc-view-set-slice}); then enter the top left pixel position |
157 | and the slice's width and height. | |
158 | @c ??? how does this work? | |
159 | ||
160 | A more convenient graphical way to specify the slice is with @kbd{s | |
161 | m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to | |
162 | select the slice. | |
163 | @c ??? How does this work? | |
3388237a CY |
164 | |
165 | @findex doc-view-reset-slice | |
d14202c2 | 166 | To cancel the selected slice, type @kbd{s r} |
5abad626 RS |
167 | (@code{doc-view-reset-slice}). Then DocView shows the entire page |
168 | including its entire margins. | |
3388237a CY |
169 | |
170 | @node Conversion | |
171 | @subsection Conversion | |
172 | ||
5abad626 | 173 | @vindex doc-view-cache-directory |
3388237a | 174 | @findex doc-view-clear-cache |
d14202c2 CY |
175 | For efficiency, DocView caches the images produced by @command{gs}. |
176 | The name of this directory is given by the variable | |
177 | @code{doc-view-cache-directory}. You can clear the cache directory by | |
178 | typing @code{M-x doc-view-clear-cache}. | |
3388237a CY |
179 | |
180 | @findex doc-view-kill-proc | |
181 | @findex doc-view-kill-proc-and-buffer | |
d14202c2 CY |
182 | To force a reconversion of the currently viewed document, type |
183 | @kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter | |
184 | process associated with the current buffer, type @kbd{K} | |
5abad626 RS |
185 | (@code{doc-view-kill-proc}). The command @kbd{k} |
186 | (@code{doc-view-kill-proc-and-buffer}) kills the converter process and | |
187 | the DocView buffer. | |
3388237a | 188 | |
d14202c2 | 189 | The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} |
5abad626 RS |
190 | (@code{doc-view-shrink}) need to reconvert the document at the new |
191 | size. The current page is converted first. | |
3388237a CY |
192 | |
193 | @node Gnus, Shell, Document View, Top | |
6bf7aab6 DL |
194 | @section Gnus |
195 | @cindex Gnus | |
196 | @cindex reading netnews | |
197 | ||
198 | Gnus is an Emacs package primarily designed for reading and posting | |
199 | Usenet news. It can also be used to read and respond to messages from a | |
200 | number of other sources---mail, remote directories, digests, and so on. | |
6bf7aab6 | 201 | Here we introduce Gnus and describe several basic features. |
d3ea5f55 | 202 | @ifnottex |
6bf7aab6 | 203 | For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. |
d3ea5f55 | 204 | @end ifnottex |
6bf7aab6 | 205 | @iftex |
a42dbee1 | 206 | For full details on Gnus, type @kbd{C-h i} and then select the Gnus |
6bf7aab6 DL |
207 | manual. |
208 | @end iftex | |
209 | ||
210 | @findex gnus | |
211 | To start Gnus, type @kbd{M-x gnus @key{RET}}. | |
212 | ||
213 | @menu | |
8838673e GM |
214 | * Buffers of Gnus:: The group, summary, and article buffers. |
215 | * Gnus Startup:: What you should know about starting Gnus. | |
216 | * Summary of Gnus:: A short description of the basic Gnus commands. | |
6bf7aab6 DL |
217 | @end menu |
218 | ||
219 | @node Buffers of Gnus | |
220 | @subsection Gnus Buffers | |
221 | ||
ab192107 RS |
222 | Unlike most Emacs packages, Gnus uses several buffers to display |
223 | information and to receive commands. The three Gnus buffers users use | |
224 | most are the @dfn{group buffer}, the @dfn{summary buffer} and the | |
225 | @dfn{article buffer}. | |
6bf7aab6 | 226 | |
ab192107 RS |
227 | The @dfn{group buffer} contains a list of newsgroups. This is the |
228 | first buffer Gnus displays when it starts up. It normally displays | |
229 | only the groups to which you subscribe and that contain unread | |
230 | articles. Use this buffer to select a specific group. | |
6bf7aab6 DL |
231 | |
232 | The @dfn{summary buffer} lists one line for each article in a single | |
233 | group. By default, the author, the subject and the line number are | |
234 | displayed for each article, but this is customizable, like most aspects | |
235 | of Gnus display. The summary buffer is created when you select a group | |
236 | in the group buffer, and is killed when you exit the group. Use this | |
237 | buffer to select an article. | |
238 | ||
239 | The @dfn{article buffer} displays the article. In normal Gnus usage, | |
ab192107 RS |
240 | you see this buffer but you don't select it---all useful |
241 | article-oriented commands work in the summary buffer. But you can | |
242 | select the article buffer, and execute all Gnus commands from that | |
243 | buffer, if you want to. | |
6bf7aab6 DL |
244 | |
245 | @node Gnus Startup | |
246 | @subsection When Gnus Starts Up | |
247 | ||
248 | At startup, Gnus reads your @file{.newsrc} news initialization file | |
249 | and attempts to communicate with the local news server, which is a | |
250 | repository of news articles. The news server need not be the same | |
251 | computer you are logged in on. | |
252 | ||
253 | If you start Gnus and connect to the server, but do not see any | |
254 | newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get | |
255 | a listing of all the groups. Then type @kbd{u} to toggle | |
256 | subscription to groups. | |
257 | ||
258 | The first time you start Gnus, Gnus subscribes you to a few selected | |
259 | groups. All other groups start out as @dfn{killed groups} for you; you | |
260 | can list them with @kbd{A k}. All new groups that subsequently come to | |
261 | exist at the news server become @dfn{zombie groups} for you; type @kbd{A | |
262 | z} to list them. You can subscribe to a group shown in these lists | |
263 | using the @kbd{u} command. | |
264 | ||
265 | When you quit Gnus with @kbd{q}, it automatically records in your | |
266 | @file{.newsrc} and @file{.newsrc.eld} initialization files the | |
267 | subscribed or unsubscribed status of all groups. You should normally | |
268 | not edit these files manually, but you may if you know how. | |
269 | ||
270 | @node Summary of Gnus | |
271 | @subsection Summary of Gnus Commands | |
272 | ||
021037cb | 273 | Reading news is a two-step process: |
6bf7aab6 DL |
274 | |
275 | @enumerate | |
276 | @item | |
277 | Choose a group in the group buffer. | |
278 | ||
279 | @item | |
280 | Select articles from the summary buffer. Each article selected is | |
281 | displayed in the article buffer in a large window, below the summary | |
282 | buffer in its small window. | |
283 | @end enumerate | |
284 | ||
ab192107 RS |
285 | Each Gnus buffer has its own special commands; the meanings of any |
286 | given key in the various Gnus buffers are usually analogous, even if | |
287 | not identical. Here are commands for the group and summary buffers: | |
6bf7aab6 DL |
288 | |
289 | @table @kbd | |
290 | @kindex q @r{(Gnus Group mode)} | |
291 | @findex gnus-group-exit | |
292 | @item q | |
293 | In the group buffer, update your @file{.newsrc} initialization file | |
294 | and quit Gnus. | |
295 | ||
296 | In the summary buffer, exit the current group and return to the | |
297 | group buffer. Thus, typing @kbd{q} twice quits Gnus. | |
298 | ||
299 | @kindex L @r{(Gnus Group mode)} | |
300 | @findex gnus-group-list-all-groups | |
301 | @item L | |
302 | In the group buffer, list all the groups available on your news | |
303 | server (except those you have killed). This may be a long list! | |
304 | ||
305 | @kindex l @r{(Gnus Group mode)} | |
306 | @findex gnus-group-list-groups | |
307 | @item l | |
308 | In the group buffer, list only the groups to which you subscribe and | |
309 | which contain unread articles. | |
310 | ||
311 | @kindex u @r{(Gnus Group mode)} | |
312 | @findex gnus-group-unsubscribe-current-group | |
313 | @cindex subscribe groups | |
314 | @cindex unsubscribe groups | |
315 | @item u | |
316 | In the group buffer, unsubscribe from (or subscribe to) the group listed | |
317 | in the line that point is on. When you quit Gnus by typing @kbd{q}, | |
318 | Gnus lists in your @file{.newsrc} file which groups you have subscribed | |
319 | to. The next time you start Gnus, you won't see this group, | |
320 | because Gnus normally displays only subscribed-to groups. | |
321 | ||
322 | @kindex C-k @r{(Gnus)} | |
323 | @findex gnus-group-kill-group | |
324 | @item C-k | |
325 | In the group buffer, ``kill'' the current line's group---don't | |
326 | even list it in @file{.newsrc} from now on. This affects future | |
327 | Gnus sessions as well as the present session. | |
328 | ||
329 | When you quit Gnus by typing @kbd{q}, Gnus writes information | |
330 | in the file @file{.newsrc} describing all newsgroups except those you | |
331 | have ``killed.'' | |
332 | ||
333 | @kindex SPC @r{(Gnus)} | |
334 | @findex gnus-group-read-group | |
335 | @item @key{SPC} | |
336 | In the group buffer, select the group on the line under the cursor | |
337 | and display the first unread article in that group. | |
338 | ||
339 | @need 1000 | |
177c0ea7 | 340 | In the summary buffer, |
6bf7aab6 DL |
341 | |
342 | @itemize @bullet | |
343 | @item | |
344 | Select the article on the line under the cursor if none is selected. | |
345 | ||
346 | @item | |
347 | Scroll the text of the selected article (if there is one). | |
348 | ||
349 | @item | |
350 | Select the next unread article if at the end of the current article. | |
351 | @end itemize | |
352 | ||
353 | Thus, you can move through all the articles by repeatedly typing @key{SPC}. | |
354 | ||
355 | @kindex DEL @r{(Gnus)} | |
356 | @item @key{DEL} | |
357 | In the group buffer, move point to the previous group containing | |
358 | unread articles. | |
359 | ||
360 | @findex gnus-summary-prev-page | |
361 | In the summary buffer, scroll the text of the article backwards. | |
362 | ||
363 | @kindex n @r{(Gnus)} | |
364 | @findex gnus-group-next-unread-group | |
365 | @findex gnus-summary-next-unread-article | |
366 | @item n | |
367 | Move point to the next unread group, or select the next unread article. | |
368 | ||
369 | @kindex p @r{(Gnus)} | |
370 | @findex gnus-group-prev-unread-group | |
371 | @findex gnus-summary-prev-unread-article | |
372 | @item p | |
373 | Move point to the previous unread group, or select the previous | |
374 | unread article. | |
375 | ||
376 | @kindex C-n @r{(Gnus Group mode)} | |
377 | @findex gnus-group-next-group | |
378 | @kindex C-p @r{(Gnus Group mode)} | |
379 | @findex gnus-group-prev-group | |
380 | @kindex C-n @r{(Gnus Summary mode)} | |
381 | @findex gnus-summary-next-subject | |
382 | @kindex C-p @r{(Gnus Summary mode)} | |
383 | @findex gnus-summary-prev-subject | |
384 | @item C-n | |
385 | @itemx C-p | |
386 | Move point to the next or previous item, even if it is marked as read. | |
387 | This does not select the article or group on that line. | |
388 | ||
389 | @kindex s @r{(Gnus Summary mode)} | |
390 | @findex gnus-summary-isearch-article | |
391 | @item s | |
392 | In the summary buffer, do an incremental search of the current text in | |
393 | the article buffer, just as if you switched to the article buffer and | |
394 | typed @kbd{C-s}. | |
395 | ||
396 | @kindex M-s @r{(Gnus Summary mode)} | |
397 | @findex gnus-summary-search-article-forward | |
398 | @item M-s @var{regexp} @key{RET} | |
399 | In the summary buffer, search forward for articles containing a match | |
400 | for @var{regexp}. | |
401 | ||
402 | @end table | |
403 | ||
404 | @ignore | |
405 | @node Where to Look | |
406 | @subsection Where to Look Further | |
407 | ||
408 | @c Too many references to the name of the manual if done with xref in TeX! | |
409 | Gnus is powerful and customizable. Here are references to a few | |
d3ea5f55 | 410 | @ifnottex |
6bf7aab6 DL |
411 | additional topics: |
412 | ||
d3ea5f55 | 413 | @end ifnottex |
6bf7aab6 DL |
414 | @iftex |
415 | additional topics in @cite{The Gnus Manual}: | |
416 | ||
417 | @itemize @bullet | |
418 | @item | |
419 | Follow discussions on specific topics.@* | |
420 | See section ``Threading.'' | |
421 | ||
422 | @item | |
423 | Read digests. See section ``Document Groups.'' | |
424 | ||
425 | @item | |
426 | Refer to and jump to the parent of the current article.@* | |
427 | See section ``Finding the Parent.'' | |
428 | ||
429 | @item | |
430 | Refer to articles by using Message-IDs included in the messages.@* | |
431 | See section ``Article Keymap.'' | |
432 | ||
433 | @item | |
434 | Save articles. See section ``Saving Articles.'' | |
435 | ||
436 | @item | |
437 | Have Gnus score articles according to various criteria, like author | |
438 | name, subject, or string in the body of the articles.@* | |
439 | See section ``Scoring.'' | |
440 | ||
441 | @item | |
442 | Send an article to a newsgroup.@* | |
443 | See section ``Composing Messages.'' | |
444 | @end itemize | |
445 | @end iftex | |
d3ea5f55 | 446 | @ifnottex |
6bf7aab6 DL |
447 | @itemize @bullet |
448 | @item | |
449 | Follow discussions on specific topics.@* | |
450 | @xref{Threading, , Reading Based on Conversation Threads, | |
451 | gnus, The Gnus Manual}. | |
452 | ||
453 | @item | |
454 | Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. | |
455 | ||
456 | @item | |
457 | Refer to and jump to the parent of the current article.@* | |
458 | @xref{Finding the Parent, , , gnus, The Gnus Manual}. | |
459 | ||
460 | @item | |
461 | Refer to articles by using Message-IDs included in the messages.@* | |
462 | @xref{Article Keymap, , , gnus, The Gnus Manual}. | |
463 | ||
464 | @item | |
465 | Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. | |
466 | ||
467 | @item | |
468 | Have Gnus score articles according to various criteria, like author | |
469 | name, subject, or string in the body of the articles.@* | |
177c0ea7 | 470 | @xref{Scoring, , , gnus, The Gnus Manual}. |
6bf7aab6 DL |
471 | |
472 | @item | |
473 | Send an article to a newsgroup.@* | |
474 | @xref{Composing Messages, , , gnus, The Gnus Manual}. | |
475 | @end itemize | |
d3ea5f55 | 476 | @end ifnottex |
6bf7aab6 DL |
477 | @end ignore |
478 | ||
479 | @node Shell, Emacs Server, Gnus, Top | |
480 | @section Running Shell Commands from Emacs | |
481 | @cindex subshell | |
482 | @cindex shell commands | |
483 | ||
484 | Emacs has commands for passing single command lines to inferior shell | |
bd4af791 | 485 | processes; it can also run a shell interactively with input and output |
df9d7630 | 486 | to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal |
bd4af791 DL |
487 | emulator window. |
488 | ||
6bf7aab6 DL |
489 | @table @kbd |
490 | @item M-! @var{cmd} @key{RET} | |
491 | Run the shell command line @var{cmd} and display the output | |
492 | (@code{shell-command}). | |
493 | @item M-| @var{cmd} @key{RET} | |
494 | Run the shell command line @var{cmd} with region contents as input; | |
495 | optionally replace the region with the output | |
496 | (@code{shell-command-on-region}). | |
26e533e2 CY |
497 | @item M-& @var{cmd} @key{RET} |
498 | Run the shell command line @var{cmd} asynchronously, and display the | |
499 | output (@code{async-shell-command}). | |
6bf7aab6 DL |
500 | @item M-x shell |
501 | Run a subshell with input and output through an Emacs buffer. | |
502 | You can then give commands interactively. | |
3b65ce47 DL |
503 | @item M-x term |
504 | Run a subshell with input and output through an Emacs buffer. | |
505 | You can then give commands interactively. | |
506 | Full terminal emulation is available. | |
6bf7aab6 DL |
507 | @end table |
508 | ||
ab192107 RS |
509 | @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It |
510 | is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, | |
511 | Eshell: The Emacs Shell}. | |
512 | ||
6bf7aab6 DL |
513 | @menu |
514 | * Single Shell:: How to run one shell command and return. | |
515 | * Interactive Shell:: Permanent shell taking input via Emacs. | |
516 | * Shell Mode:: Special Emacs commands used with permanent shell. | |
e51d6b23 | 517 | * Shell Prompts:: Two ways to recognize shell prompts. |
6bf7aab6 | 518 | * History: Shell History. Repeating previous commands in a shell buffer. |
df9d7630 | 519 | * Directory Tracking:: Keeping track when the subshell changes directory. |
6bf7aab6 | 520 | * Options: Shell Options. Options for customizing Shell mode. |
3b65ce47 DL |
521 | * Terminal emulator:: An Emacs window as a terminal emulator. |
522 | * Term Mode:: Special Emacs commands used in Term mode. | |
523 | * Paging in Term:: Paging in the terminal emulator. | |
6bf7aab6 | 524 | * Remote Host:: Connecting to another computer. |
37e5d54a | 525 | * Serial Terminal:: Connecting to a serial port. |
6bf7aab6 DL |
526 | @end menu |
527 | ||
528 | @node Single Shell | |
529 | @subsection Single Shell Commands | |
530 | ||
531 | @kindex M-! | |
532 | @findex shell-command | |
533 | @kbd{M-!} (@code{shell-command}) reads a line of text using the | |
534 | minibuffer and executes it as a shell command in a subshell made just | |
535 | for that command. Standard input for the command comes from the null | |
fc98b4ba RS |
536 | device. If the shell command produces any output, the output appears |
537 | either in the echo area (if it is short), or in an Emacs buffer named | |
538 | @samp{*Shell Command Output*}, which is displayed in another window | |
d408f8d0 RS |
539 | but not selected (if the output is long). |
540 | ||
541 | For instance, one way to decompress a file @file{foo.gz} from Emacs | |
542 | is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command | |
543 | normally creates the file @file{foo} and produces no terminal output. | |
544 | ||
545 | A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal | |
546 | output into the current buffer instead of a separate buffer. It puts | |
547 | point before the output, and sets the mark after the output. For | |
a9749dab | 548 | instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the |
d408f8d0 | 549 | uncompressed equivalent of @file{foo.gz} into the current buffer. |
6bf7aab6 DL |
550 | |
551 | If the shell command line ends in @samp{&}, it runs asynchronously. | |
552 | For a synchronous shell command, @code{shell-command} returns the | |
553 | command's exit status (0 means success), when it is called from a Lisp | |
d408f8d0 | 554 | program. You do not get any status information for an asynchronous |
ab192107 | 555 | command, since it hasn't finished yet when @code{shell-command} returns. |
6bf7aab6 | 556 | |
26e533e2 CY |
557 | You can also type @kbd{M-&} (@code{async-shell-command}) to execute |
558 | a shell command asynchronously. This behaves exactly like calling | |
559 | @code{shell-command} with @samp{&}, except that you do not need to add | |
560 | the @samp{&} to the shell command line. | |
561 | ||
6bf7aab6 DL |
562 | @kindex M-| |
563 | @findex shell-command-on-region | |
564 | @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but | |
565 | passes the contents of the region as the standard input to the shell | |
ab192107 RS |
566 | command, instead of no input. With a numeric argument, meaning insert |
567 | the output in the current buffer, it deletes the old region and the | |
568 | output replaces it as the contents of the region. It returns the | |
569 | command's exit status, like @kbd{M-!}. | |
6bf7aab6 | 570 | |
982dcb1b RS |
571 | One use for @kbd{M-|} is to run @code{gpg} to see what keys are in |
572 | the buffer. For instance, if the buffer contains a GPG key, type | |
ab192107 RS |
573 | @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to |
574 | the @code{gpg} program. That program will ignore everything except | |
575 | the encoded keys, and will output a list of the keys the buffer | |
576 | contains. | |
d408f8d0 | 577 | |
6bf7aab6 | 578 | @vindex shell-file-name |
ab192107 RS |
579 | Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify |
580 | the shell to use. This variable is initialized based on your | |
581 | @env{SHELL} environment variable when Emacs is started. If the file | |
582 | name is relative, Emacs searches the directories in the list | |
583 | @code{exec-path}; this list is initialized based on the environment | |
932fd020 CY |
584 | variable @env{PATH} when Emacs is started. Your init file can |
585 | override either or both of these default initializations (@pxref{Init | |
586 | File}). | |
6bf7aab6 | 587 | |
982dcb1b | 588 | Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete, |
e51d6b23 | 589 | unless you end the command with @samp{&} to make it asynchronous. To |
982dcb1b | 590 | stop waiting, type @kbd{C-g} to quit; that terminates the shell |
6bf7aab6 | 591 | command with the signal @code{SIGINT}---the same signal that @kbd{C-c} |
ab192107 | 592 | normally generates in the shell. Emacs then waits until the command |
982dcb1b RS |
593 | actually terminates. If the shell command doesn't stop (because it |
594 | ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends | |
595 | the command a @code{SIGKILL} signal which is impossible to ignore. | |
596 | ||
597 | Asynchronous commands ending in @samp{&} feed their output into | |
598 | the buffer @samp{*Async Shell Command*}. Output arrives in that | |
599 | buffer regardless of whether it is visible in a window. | |
6bf7aab6 DL |
600 | |
601 | To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command | |
54b6e2d1 | 602 | @kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. |
6bf7aab6 DL |
603 | |
604 | @vindex shell-command-default-error-buffer | |
ab192107 RS |
605 | Error output from these commands is normally intermixed with the |
606 | regular output. But if the variable | |
607 | @code{shell-command-default-error-buffer} has a string as value, and | |
608 | it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output | |
609 | before point in that buffer. | |
6bf7aab6 DL |
610 | |
611 | @node Interactive Shell | |
612 | @subsection Interactive Inferior Shell | |
613 | ||
614 | @findex shell | |
932fd020 CY |
615 | To run a subshell interactively, use @kbd{M-x shell}. This creates |
616 | (or reuses) a buffer named @samp{*shell*} and runs a subshell with | |
617 | input coming from and output going to that buffer. That is to say, | |
618 | any ``terminal output'' from the subshell goes into the buffer, | |
619 | advancing point, and any ``terminal input'' for the subshell comes | |
620 | from text in the buffer. To give input to the subshell, go to the end | |
621 | of the buffer and type the input, terminated by @key{RET}. | |
6bf7aab6 DL |
622 | |
623 | Emacs does not wait for the subshell to do anything. You can switch | |
624 | windows or buffers and edit them while the shell is waiting, or while it is | |
625 | running a command. Output from the subshell waits until Emacs has time to | |
626 | process it; this happens whenever Emacs is waiting for keyboard input or | |
627 | for time to elapse. | |
628 | ||
df9d7630 RS |
629 | @cindex @code{comint-highlight-input} face |
630 | @cindex @code{comint-highlight-prompt} face | |
631 | Input lines, once you submit them, are displayed using the face | |
632 | @code{comint-highlight-input}, and prompts are displayed using the | |
633 | face @code{comint-highlight-prompt}. This makes it easier to see | |
634 | previous input lines in the buffer. @xref{Faces}. | |
635 | ||
a9749dab RS |
636 | To make multiple subshells, you can invoke @kbd{M-x shell} with a |
637 | prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer | |
638 | name and create (or reuse) a subshell in that buffer. You can also | |
639 | rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then | |
ab192107 RS |
640 | create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. |
641 | Subshells in different buffers run independently and in parallel. | |
6bf7aab6 DL |
642 | |
643 | @vindex explicit-shell-file-name | |
b2c8319e | 644 | @cindex environment variables for subshells |
60a96371 GM |
645 | @cindex @env{ESHELL} environment variable |
646 | @cindex @env{SHELL} environment variable | |
6bf7aab6 | 647 | The file name used to load the subshell is the value of the variable |
932fd020 CY |
648 | @code{explicit-shell-file-name}, if that is non-@code{nil}. |
649 | Otherwise, the environment variable @env{ESHELL} is used, or the | |
650 | environment variable @env{SHELL} if there is no @env{ESHELL}. If the | |
651 | file name specified is relative, the directories in the list | |
652 | @code{exec-path} are searched; this list is initialized based on the | |
653 | environment variable @env{PATH} when Emacs is started. Your init file | |
654 | can override either or both of these default initializations. | |
655 | (@pxref{Init File}). | |
6bf7aab6 | 656 | |
df9d7630 RS |
657 | Emacs sends the new shell the contents of the file |
658 | @file{~/.emacs_@var{shellname}} as input, if it exists, where | |
659 | @var{shellname} is the name of the file that the shell was loaded | |
660 | from. For example, if you use bash, the file sent to it is | |
36ff5b10 JB |
661 | @file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback |
662 | on @file{~/.emacs.d/init_@var{shellname}.sh}. | |
df9d7630 | 663 | |
6bf7aab6 | 664 | To specify a coding system for the shell, you can use the command |
ab192107 RS |
665 | @kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can |
666 | also change the coding system for a running subshell by typing | |
667 | @kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication | |
668 | Coding}. | |
6bf7aab6 | 669 | |
ed91b7ed | 670 | @cindex @env{INSIDE_EMACS} environment variable |
b6c764ef RS |
671 | Emacs sets the environment variable @env{INSIDE_EMACS} in the |
672 | subshell to a comma-separated list including the Emacs version. | |
fe6dcbf6 GM |
673 | Programs can check this variable to determine whether they are running |
674 | inside an Emacs subshell. | |
ed91b7ed | 675 | |
b2c8319e | 676 | @cindex @env{EMACS} environment variable |
fe6dcbf6 | 677 | Emacs also sets the @env{EMACS} environment variable (to @code{t}) if |
ed91b7ed CY |
678 | it is not already defined. @strong{Warning:} This environment |
679 | variable is deprecated. Programs that check this variable should be | |
680 | changed to check @env{INSIDE_EMACS} instead. | |
6bf7aab6 DL |
681 | |
682 | @node Shell Mode | |
683 | @subsection Shell Mode | |
684 | @cindex Shell mode | |
685 | @cindex mode, Shell | |
686 | ||
687 | Shell buffers use Shell mode, which defines several special keys | |
688 | attached to the @kbd{C-c} prefix. They are chosen to resemble the usual | |
689 | editing and job control characters present in shells that are not under | |
690 | Emacs, except that you must type @kbd{C-c} first. Here is a complete list | |
691 | of the special key bindings of Shell mode: | |
692 | ||
693 | @table @kbd | |
694 | @item @key{RET} | |
695 | @kindex RET @r{(Shell mode)} | |
696 | @findex comint-send-input | |
df9d7630 | 697 | At end of buffer send line as input; otherwise, copy current line to |
ab192107 RS |
698 | end of buffer and send it (@code{comint-send-input}). Copying a line |
699 | in this way omits any prompt at the beginning of the line (text output | |
700 | by programs preceding your input). @xref{Shell Prompts}, for how | |
701 | Shell mode recognizes prompts. | |
6bf7aab6 DL |
702 | |
703 | @item @key{TAB} | |
704 | @kindex TAB @r{(Shell mode)} | |
705 | @findex comint-dynamic-complete | |
706 | Complete the command name or file name before point in the shell buffer | |
707 | (@code{comint-dynamic-complete}). @key{TAB} also completes history | |
708 | references (@pxref{History References}) and environment variable names. | |
709 | ||
710 | @vindex shell-completion-fignore | |
711 | @vindex comint-completion-fignore | |
712 | The variable @code{shell-completion-fignore} specifies a list of file | |
fc98b4ba RS |
713 | name extensions to ignore in Shell mode completion. The default |
714 | setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to | |
715 | ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other | |
6bf7aab6 DL |
716 | related Comint modes use the variable @code{comint-completion-fignore} |
717 | instead. | |
718 | ||
719 | @item M-? | |
720 | @kindex M-? @r{(Shell mode)} | |
721 | @findex comint-dynamic-list-filename@dots{} | |
722 | Display temporarily a list of the possible completions of the file name | |
723 | before point in the shell buffer | |
724 | (@code{comint-dynamic-list-filename-completions}). | |
725 | ||
726 | @item C-d | |
727 | @kindex C-d @r{(Shell mode)} | |
728 | @findex comint-delchar-or-maybe-eof | |
76dd3692 | 729 | Either delete a character or send @acronym{EOF} |
6bf7aab6 | 730 | (@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell |
76dd3692 | 731 | buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other |
6bf7aab6 DL |
732 | position in the buffer, @kbd{C-d} deletes a character as usual. |
733 | ||
734 | @item C-c C-a | |
735 | @kindex C-c C-a @r{(Shell mode)} | |
fc98b4ba | 736 | @findex comint-bol-or-process-mark |
6bf7aab6 | 737 | Move to the beginning of the line, but after the prompt if any |
fc98b4ba RS |
738 | (@code{comint-bol-or-process-mark}). If you repeat this command twice |
739 | in a row, the second time it moves back to the process mark, which is | |
740 | the beginning of the input that you have not yet sent to the subshell. | |
741 | (Normally that is the same place---the end of the prompt on this | |
742 | line---but after @kbd{C-c @key{SPC}} the process mark may be in a | |
743 | previous line.) | |
6bf7aab6 DL |
744 | |
745 | @item C-c @key{SPC} | |
746 | Accumulate multiple lines of input, then send them together. This | |
747 | command inserts a newline before point, but does not send the preceding | |
748 | text as input to the subshell---at least, not yet. Both lines, the one | |
749 | before this newline and the one after, will be sent together (along with | |
750 | the newline that separates them), when you type @key{RET}. | |
751 | ||
752 | @item C-c C-u | |
753 | @kindex C-c C-u @r{(Shell mode)} | |
754 | @findex comint-kill-input | |
755 | Kill all text pending at end of buffer to be sent as input | |
e51d6b23 LT |
756 | (@code{comint-kill-input}). If point is not at end of buffer, |
757 | this only kills the part of this text that precedes point. | |
6bf7aab6 DL |
758 | |
759 | @item C-c C-w | |
760 | @kindex C-c C-w @r{(Shell mode)} | |
761 | Kill a word before point (@code{backward-kill-word}). | |
762 | ||
763 | @item C-c C-c | |
764 | @kindex C-c C-c @r{(Shell mode)} | |
765 | @findex comint-interrupt-subjob | |
766 | Interrupt the shell or its current subjob if any | |
767 | (@code{comint-interrupt-subjob}). This command also kills | |
768 | any shell input pending in the shell buffer and not yet sent. | |
769 | ||
770 | @item C-c C-z | |
771 | @kindex C-c C-z @r{(Shell mode)} | |
772 | @findex comint-stop-subjob | |
773 | Stop the shell or its current subjob if any (@code{comint-stop-subjob}). | |
774 | This command also kills any shell input pending in the shell buffer and | |
775 | not yet sent. | |
776 | ||
777 | @item C-c C-\ | |
778 | @findex comint-quit-subjob | |
779 | @kindex C-c C-\ @r{(Shell mode)} | |
780 | Send quit signal to the shell or its current subjob if any | |
781 | (@code{comint-quit-subjob}). This command also kills any shell input | |
782 | pending in the shell buffer and not yet sent. | |
783 | ||
784 | @item C-c C-o | |
785 | @kindex C-c C-o @r{(Shell mode)} | |
97f59309 MB |
786 | @findex comint-delete-output |
787 | Delete the last batch of output from a shell command | |
788 | (@code{comint-delete-output}). This is useful if a shell command spews | |
789 | out lots of output that just gets in the way. This command used to be | |
790 | called @code{comint-kill-output}. | |
791 | ||
792 | @item C-c C-s | |
793 | @kindex C-c C-s @r{(Shell mode)} | |
794 | @findex comint-write-output | |
795 | Write the last batch of output from a shell command to a file | |
796 | (@code{comint-write-output}). With a prefix argument, the file is | |
797 | appended to instead. Any prompt at the end of the output is not | |
798 | written. | |
6bf7aab6 DL |
799 | |
800 | @item C-c C-r | |
801 | @itemx C-M-l | |
802 | @kindex C-c C-r @r{(Shell mode)} | |
803 | @kindex C-M-l @r{(Shell mode)} | |
804 | @findex comint-show-output | |
805 | Scroll to display the beginning of the last batch of output at the top | |
806 | of the window; also move the cursor there (@code{comint-show-output}). | |
807 | ||
808 | @item C-c C-e | |
809 | @kindex C-c C-e @r{(Shell mode)} | |
810 | @findex comint-show-maximum-output | |
811 | Scroll to put the end of the buffer at the bottom of the window | |
812 | (@code{comint-show-maximum-output}). | |
813 | ||
814 | @item C-c C-f | |
815 | @kindex C-c C-f @r{(Shell mode)} | |
816 | @findex shell-forward-command | |
817 | @vindex shell-command-regexp | |
818 | Move forward across one shell command, but not beyond the current line | |
819 | (@code{shell-forward-command}). The variable @code{shell-command-regexp} | |
820 | specifies how to recognize the end of a command. | |
821 | ||
822 | @item C-c C-b | |
823 | @kindex C-c C-b @r{(Shell mode)} | |
824 | @findex shell-backward-command | |
825 | Move backward across one shell command, but not beyond the current line | |
826 | (@code{shell-backward-command}). | |
827 | ||
6bf7aab6 DL |
828 | @item M-x dirs |
829 | Ask the shell what its current directory is, so that Emacs can agree | |
830 | with the shell. | |
831 | ||
832 | @item M-x send-invisible @key{RET} @var{text} @key{RET} | |
833 | @findex send-invisible | |
834 | Send @var{text} as input to the shell, after reading it without | |
835 | echoing. This is useful when a shell command runs a program that asks | |
836 | for a password. | |
837 | ||
e5b7fee6 EZ |
838 | Please note that Emacs will not echo passwords by default. If you |
839 | really want them to be echoed, evaluate the following Lisp | |
840 | expression: | |
6bf7aab6 DL |
841 | |
842 | @example | |
e5b7fee6 EZ |
843 | (remove-hook 'comint-output-filter-functions |
844 | 'comint-watch-for-password-prompt) | |
6bf7aab6 DL |
845 | @end example |
846 | ||
847 | @item M-x comint-continue-subjob | |
848 | @findex comint-continue-subjob | |
849 | Continue the shell process. This is useful if you accidentally suspend | |
850 | the shell process.@footnote{You should not suspend the shell process. | |
851 | Suspending a subjob of the shell is a completely different matter---that | |
852 | is normal practice, but you must use the shell to continue the subjob; | |
853 | this command won't do it.} | |
854 | ||
855 | @item M-x comint-strip-ctrl-m | |
856 | @findex comint-strip-ctrl-m | |
857 | Discard all control-M characters from the current group of shell output. | |
858 | The most convenient way to use this command is to make it run | |
859 | automatically when you get output from the subshell. To do that, | |
860 | evaluate this Lisp expression: | |
861 | ||
862 | @example | |
863 | (add-hook 'comint-output-filter-functions | |
864 | 'comint-strip-ctrl-m) | |
865 | @end example | |
866 | ||
867 | @item M-x comint-truncate-buffer | |
868 | @findex comint-truncate-buffer | |
869 | This command truncates the shell buffer to a certain maximum number of | |
870 | lines, specified by the variable @code{comint-buffer-maximum-size}. | |
871 | Here's how to do this automatically each time you get output from the | |
872 | subshell: | |
873 | ||
874 | @example | |
875 | (add-hook 'comint-output-filter-functions | |
876 | 'comint-truncate-buffer) | |
877 | @end example | |
878 | @end table | |
879 | ||
6bf7aab6 DL |
880 | @cindex Comint mode |
881 | @cindex mode, Comint | |
882 | Shell mode is a derivative of Comint mode, a general-purpose mode for | |
883 | communicating with interactive subprocesses. Most of the features of | |
884 | Shell mode actually come from Comint mode, as you can see from the | |
bd9e9287 MB |
885 | command names listed above. The special features of Shell mode include |
886 | the directory tracking feature, and a few user commands. | |
6bf7aab6 DL |
887 | |
888 | Other Emacs features that use variants of Comint mode include GUD | |
889 | (@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). | |
890 | ||
891 | @findex comint-run | |
892 | You can use @kbd{M-x comint-run} to execute any program of your choice | |
893 | in a subprocess using unmodified Comint mode---without the | |
894 | specializations of Shell mode. | |
895 | ||
e51d6b23 LT |
896 | @node Shell Prompts |
897 | @subsection Shell Prompts | |
898 | ||
899 | @vindex shell-prompt-pattern | |
900 | @vindex comint-prompt-regexp | |
901 | @vindex comint-use-prompt-regexp | |
902 | @cindex prompt, shell | |
903 | A prompt is text output by a program to show that it is ready to | |
904 | accept new user input. Normally, Comint mode (and thus Shell mode) | |
905 | considers the prompt to be any text output by a program at the | |
906 | beginning of an input line. However, if the variable | |
907 | @code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode | |
908 | uses a regular expression to recognize prompts. In Shell mode, | |
909 | @code{shell-prompt-pattern} specifies the regular expression. | |
910 | ||
911 | The value of @code{comint-use-prompt-regexp} also affects many | |
912 | motion and paragraph commands. If the value is non-@code{nil}, the | |
913 | general Emacs motion commands behave as they normally do in buffers | |
914 | without special text properties. However, if the value is @code{nil}, | |
915 | the default, then Comint mode divides the buffer into two types of | |
916 | ``fields'' (ranges of consecutive characters having the same | |
917 | @code{field} text property): input and output. Prompts are part of | |
918 | the output. Most Emacs motion commands do not cross field boundaries, | |
919 | unless they move over multiple lines. For instance, when point is in | |
920 | input on the same line as a prompt, @kbd{C-a} puts point at the | |
921 | beginning of the input if @code{comint-use-prompt-regexp} is | |
922 | @code{nil} and at the beginning of the line otherwise. | |
923 | ||
924 | In Shell mode, only shell prompts start new paragraphs. Thus, a | |
925 | paragraph consists of a prompt and the input and output that follow | |
926 | it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the | |
927 | default, most paragraph commands do not cross field boundaries. This | |
928 | means that prompts, ranges of input, and ranges of non-prompt output | |
929 | behave mostly like separate paragraphs; with this setting, numeric | |
930 | arguments to most paragraph commands yield essentially undefined | |
931 | behavior. For the purpose of finding paragraph boundaries, Shell mode | |
932 | uses @code{shell-prompt-pattern}, regardless of | |
933 | @code{comint-use-prompt-regexp}. | |
934 | ||
6bf7aab6 DL |
935 | @node Shell History |
936 | @subsection Shell Command History | |
937 | ||
938 | Shell buffers support three ways of repeating earlier commands. You | |
982dcb1b RS |
939 | can use keys like those used for the minibuffer history; these work |
940 | much as they do in the minibuffer, inserting text from prior commands | |
941 | while point remains always at the end of the buffer. You can move | |
942 | through the buffer to previous inputs in their original place, then | |
943 | resubmit them or copy them to the end. Or you can use a | |
944 | @samp{!}-style history reference. | |
6bf7aab6 DL |
945 | |
946 | @menu | |
947 | * Ring: Shell Ring. Fetching commands from the history list. | |
948 | * Copy: Shell History Copying. Moving to a command and then copying it. | |
949 | * History References:: Expanding @samp{!}-style history references. | |
950 | @end menu | |
951 | ||
952 | @node Shell Ring | |
953 | @subsubsection Shell History Ring | |
954 | ||
955 | @table @kbd | |
956 | @findex comint-previous-input | |
957 | @kindex M-p @r{(Shell mode)} | |
958 | @item M-p | |
982dcb1b | 959 | @itemx C-@key{UP} |
6bf7aab6 DL |
960 | Fetch the next earlier old shell command. |
961 | ||
962 | @kindex M-n @r{(Shell mode)} | |
963 | @findex comint-next-input | |
964 | @item M-n | |
982dcb1b | 965 | @itemx C-@key{DOWN} |
6bf7aab6 DL |
966 | Fetch the next later old shell command. |
967 | ||
968 | @kindex M-r @r{(Shell mode)} | |
f2608df3 CY |
969 | @findex comint-history-isearch-backward-regexp |
970 | @item M-r | |
971 | Begin an incremental regexp search of old shell commands. | |
6bf7aab6 | 972 | |
2a4a9af9 NR |
973 | @item C-c C-x |
974 | @kindex C-c C-x @r{(Shell mode)} | |
6bf7aab6 DL |
975 | @findex comint-get-next-from-history |
976 | Fetch the next subsequent command from the history. | |
91179e97 | 977 | |
2a4a9af9 NR |
978 | @item C-c . |
979 | @kindex C-c . @r{(Shell mode)} | |
91179e97 RS |
980 | @findex comint-input-previous-argument |
981 | Fetch one argument from an old shell command. | |
2a4a9af9 NR |
982 | |
983 | @item C-c C-l | |
984 | @kindex C-c C-l @r{(Shell mode)} | |
985 | @findex comint-dynamic-list-input-ring | |
986 | Display the buffer's history of shell commands in another window | |
987 | (@code{comint-dynamic-list-input-ring}). | |
6bf7aab6 DL |
988 | @end table |
989 | ||
990 | Shell buffers provide a history of previously entered shell commands. To | |
991 | reuse shell commands from the history, use the editing commands @kbd{M-p}, | |
992 | @kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer | |
993 | history commands except that they operate on the text at the end of the | |
994 | shell buffer, where you would normally insert text to send to the shell. | |
995 | ||
982dcb1b RS |
996 | @kbd{M-p} fetches an earlier shell command to the end of the shell |
997 | buffer. Successive use of @kbd{M-p} fetches successively earlier | |
998 | shell commands, each replacing any text that was already present as | |
999 | potential shell input. @kbd{M-n} does likewise except that it finds | |
1000 | successively more recent shell commands from the buffer. | |
1001 | @kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like | |
1002 | @kbd{M-n}. | |
6bf7aab6 | 1003 | |
f2608df3 CY |
1004 | The history search command @kbd{M-r} begins an incremental regular |
1005 | expression search of previous shell commands. After typing @kbd{M-r}, | |
1006 | start typing the desired string or regular expression; the last | |
1007 | matching shell command will be displayed in the current line. | |
1008 | Incremental search commands have their usual effects---for instance, | |
1009 | @kbd{C-s} and @kbd{C-r} search forward and backward for the next match | |
1010 | (@pxref{Incremental Search}). When you find the desired input, type | |
1011 | @key{RET} to terminate the search. This puts the input in the command | |
1012 | line. Any partial input you were composing before navigating the | |
74600a6f S |
1013 | history list is restored when you go to the beginning or end of the |
1014 | history ring. | |
6bf7aab6 DL |
1015 | |
1016 | Often it is useful to reexecute several successive shell commands that | |
1017 | were previously executed in sequence. To do this, first find and | |
1018 | reexecute the first command of the sequence. Then type @kbd{C-c C-x}; | |
1019 | that will fetch the following command---the one that follows the command | |
1020 | you just repeated. Then type @key{RET} to reexecute this command. You | |
1021 | can reexecute several successive commands by typing @kbd{C-c C-x | |
1022 | @key{RET}} over and over. | |
1023 | ||
91179e97 RS |
1024 | The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) |
1025 | copies an individual argument from a previous command, like @kbd{ESC | |
1026 | .} in Bash. The simplest use copies the last argument from the | |
1027 | previous shell command. With a prefix argument @var{n}, it copies the | |
1028 | @var{n}th argument instead. Repeating @kbd{C-c .} copies from an | |
1029 | earlier shell command instead, always using the same value of @var{n} | |
1030 | (don't give a prefix argument when you repeat the @kbd{C-c .} | |
1031 | command). | |
1032 | ||
6bf7aab6 DL |
1033 | These commands get the text of previous shell commands from a special |
1034 | history list, not from the shell buffer itself. Thus, editing the shell | |
1035 | buffer, or even killing large parts of it, does not affect the history | |
1036 | that these commands access. | |
1037 | ||
1038 | @vindex shell-input-ring-file-name | |
1039 | Some shells store their command histories in files so that you can | |
e51d6b23 | 1040 | refer to commands from previous shell sessions. Emacs reads |
6bf7aab6 DL |
1041 | the command history file for your chosen shell, to initialize its own |
1042 | command history. The file name is @file{~/.bash_history} for bash, | |
1043 | @file{~/.sh_history} for ksh, and @file{~/.history} for other shells. | |
1044 | ||
1045 | @node Shell History Copying | |
1046 | @subsubsection Shell History Copying | |
1047 | ||
1048 | @table @kbd | |
1049 | @kindex C-c C-p @r{(Shell mode)} | |
1050 | @findex comint-previous-prompt | |
1051 | @item C-c C-p | |
1052 | Move point to the previous prompt (@code{comint-previous-prompt}). | |
1053 | ||
1054 | @kindex C-c C-n @r{(Shell mode)} | |
1055 | @findex comint-next-prompt | |
1056 | @item C-c C-n | |
1057 | Move point to the following prompt (@code{comint-next-prompt}). | |
1058 | ||
1059 | @kindex C-c RET @r{(Shell mode)} | |
55f62691 | 1060 | @findex comint-copy-old-input |
6bf7aab6 | 1061 | @item C-c @key{RET} |
932fd020 CY |
1062 | Copy the input command at point, inserting the copy at the end of the |
1063 | buffer (@code{comint-copy-old-input}). This is useful if you move | |
1064 | point back to a previous command. After you copy the command, you can | |
1065 | submit the copy as input with @key{RET}. If you wish, you can edit | |
1066 | the copy before resubmitting it. If you use this command on an output | |
1067 | line, it copies that line to the end of the buffer. | |
2a4a9af9 NR |
1068 | |
1069 | @item Mouse-2 | |
55f62691 LT |
1070 | If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy |
1071 | the old input command that you click on, inserting the copy at the end | |
1072 | of the buffer (@code{comint-insert-input}). If | |
1073 | @code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is | |
1074 | not over old input, just yank as usual. | |
6bf7aab6 DL |
1075 | @end table |
1076 | ||
1077 | Moving to a previous input and then copying it with @kbd{C-c | |
2a4a9af9 NR |
1078 | @key{RET}} or @kbd{Mouse-2} produces the same results---the same |
1079 | buffer contents---that you would get by using @kbd{M-p} enough times | |
1080 | to fetch that previous input from the history list. However, @kbd{C-c | |
1081 | @key{RET}} copies the text from the buffer, which can be different | |
1082 | from what is in the history list if you edit the input text in the | |
1083 | buffer after it has been sent. | |
6bf7aab6 DL |
1084 | |
1085 | @node History References | |
1086 | @subsubsection Shell History References | |
1087 | @cindex history reference | |
1088 | ||
df9d7630 RS |
1089 | Various shells including csh and bash support @dfn{history |
1090 | references} that begin with @samp{!} and @samp{^}. Shell mode | |
1091 | recognizes these constructs, and can perform the history substitution | |
1092 | for you. | |
1093 | ||
1094 | If you insert a history reference and type @key{TAB}, this searches | |
1095 | the input history for a matching command, performs substitution if | |
1096 | necessary, and places the result in the buffer in place of the history | |
1097 | reference. For example, you can fetch the most recent command | |
1098 | beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the | |
1099 | command if you wish, and then resubmit the command to the shell by | |
1100 | typing @key{RET}. | |
1101 | ||
1102 | @vindex comint-input-autoexpand | |
1103 | @findex comint-magic-space | |
1104 | Shell mode can optionally expand history references in the buffer | |
1105 | when you send them to the shell. To request this, set the variable | |
1106 | @code{comint-input-autoexpand} to @code{input}. You can make | |
1107 | @key{SPC} perform history expansion by binding @key{SPC} to the | |
1108 | command @code{comint-magic-space}. | |
6bf7aab6 | 1109 | |
df9d7630 | 1110 | Shell mode recognizes history references when they follow a prompt. |
e51d6b23 | 1111 | @xref{Shell Prompts}, for how Shell mode recognizes prompts. |
df9d7630 RS |
1112 | |
1113 | @node Directory Tracking | |
1114 | @subsection Directory Tracking | |
1115 | @cindex directory tracking | |
6bf7aab6 | 1116 | |
df9d7630 RS |
1117 | @vindex shell-pushd-regexp |
1118 | @vindex shell-popd-regexp | |
1119 | @vindex shell-cd-regexp | |
1120 | Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} | |
1121 | commands given to the inferior shell, so it can keep the | |
1122 | @samp{*shell*} buffer's default directory the same as the shell's | |
1123 | working directory. It recognizes these commands syntactically, by | |
1124 | examining lines of input that are sent. | |
6bf7aab6 | 1125 | |
df9d7630 RS |
1126 | If you use aliases for these commands, you can tell Emacs to |
1127 | recognize them also. For example, if the value of the variable | |
1128 | @code{shell-pushd-regexp} matches the beginning of a shell command | |
1129 | line, that line is regarded as a @code{pushd} command. Change this | |
1130 | variable when you add aliases for @samp{pushd}. Likewise, | |
1131 | @code{shell-popd-regexp} and @code{shell-cd-regexp} are used to | |
1132 | recognize commands with the meaning of @samp{popd} and @samp{cd}. | |
1133 | These commands are recognized only at the beginning of a shell command | |
1134 | line. | |
1135 | ||
fc98b4ba | 1136 | @ignore @c This seems to have been deleted long ago. |
df9d7630 RS |
1137 | @vindex shell-set-directory-error-hook |
1138 | If Emacs gets an error while trying to handle what it believes is a | |
1139 | @samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook | |
1140 | @code{shell-set-directory-error-hook} (@pxref{Hooks}). | |
fc98b4ba | 1141 | @end ignore |
df9d7630 RS |
1142 | |
1143 | @findex dirs | |
1144 | If Emacs gets confused about changes in the current directory of the | |
1145 | subshell, use the command @kbd{M-x dirs} to ask the shell what its | |
1146 | current directory is. This command works for shells that support the | |
1147 | most common command syntax; it may not work for unusual shells. | |
1148 | ||
1149 | @findex dirtrack-mode | |
1150 | You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an | |
db8446b8 GM |
1151 | alternative method of tracking changes in the current directory. This |
1152 | method relies on your shell prompt containing the full current working | |
1153 | directory at all times. | |
6bf7aab6 DL |
1154 | |
1155 | @node Shell Options | |
1156 | @subsection Shell Mode Options | |
1157 | ||
1158 | @vindex comint-scroll-to-bottom-on-input | |
1159 | If the variable @code{comint-scroll-to-bottom-on-input} is | |
1160 | non-@code{nil}, insertion and yank commands scroll the selected window | |
67cf9997 | 1161 | to the bottom before inserting. The default is @code{nil}. |
6bf7aab6 DL |
1162 | |
1163 | @vindex comint-scroll-show-maximum-output | |
1164 | If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then | |
e59d2bef RS |
1165 | arrival of output when point is at the end tries to scroll the last |
1166 | line of text to the bottom line of the window, showing as much useful | |
67cf9997 CY |
1167 | text as possible. (This mimics the scrolling behavior of most |
1168 | terminals.) The default is @code{t}. | |
6bf7aab6 | 1169 | |
fcc91da6 RS |
1170 | @vindex comint-move-point-for-output |
1171 | By setting @code{comint-move-point-for-output}, you can opt for | |
6bf7aab6 DL |
1172 | having point jump to the end of the buffer whenever output arrives---no |
1173 | matter where in the buffer point was before. If the value is | |
1174 | @code{this}, point jumps in the selected window. If the value is | |
021037cb | 1175 | @code{all}, point jumps in each window that shows the Comint buffer. If |
6bf7aab6 DL |
1176 | the value is @code{other}, point jumps in all nonselected windows that |
1177 | show the current buffer. The default value is @code{nil}, which means | |
1178 | point does not jump to the end. | |
1179 | ||
982dcb1b RS |
1180 | @vindex comint-prompt-read-only |
1181 | If you set @code{comint-prompt-read-only}, the prompts in the Comint | |
66dd6a00 | 1182 | buffer are read-only. |
982dcb1b | 1183 | |
6bf7aab6 DL |
1184 | @vindex comint-input-ignoredups |
1185 | The variable @code{comint-input-ignoredups} controls whether successive | |
1186 | identical inputs are stored in the input history. A non-@code{nil} | |
1187 | value means to omit an input that is the same as the previous input. | |
1188 | The default is @code{nil}, which means to store each input even if it is | |
1189 | equal to the previous input. | |
1190 | ||
1191 | @vindex comint-completion-addsuffix | |
1192 | @vindex comint-completion-recexact | |
1193 | @vindex comint-completion-autolist | |
1194 | Three variables customize file name completion. The variable | |
1195 | @code{comint-completion-addsuffix} controls whether completion inserts a | |
1196 | space or a slash to indicate a fully completed file or directory name | |
1197 | (non-@code{nil} means do insert a space or slash). | |
1198 | @code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} | |
1199 | to choose the shortest possible completion if the usual Emacs completion | |
1200 | algorithm cannot add even a single character. | |
1201 | @code{comint-completion-autolist}, if non-@code{nil}, says to list all | |
1202 | the possible completions whenever completion is not exact. | |
1203 | ||
fc98b4ba | 1204 | @vindex shell-completion-execonly |
6bf7aab6 | 1205 | Command completion normally considers only executable files. |
fc98b4ba | 1206 | If you set @code{shell-completion-execonly} to @code{nil}, |
6bf7aab6 DL |
1207 | it considers nonexecutable files as well. |
1208 | ||
1209 | @findex shell-pushd-tohome | |
1210 | @findex shell-pushd-dextract | |
1211 | @findex shell-pushd-dunique | |
1212 | You can configure the behavior of @samp{pushd}. Variables control | |
1213 | whether @samp{pushd} behaves like @samp{cd} if no argument is given | |
1214 | (@code{shell-pushd-tohome}), pop rather than rotate with a numeric | |
1215 | argument (@code{shell-pushd-dextract}), and only add directories to the | |
1216 | directory stack if they are not already on it | |
1217 | (@code{shell-pushd-dunique}). The values you choose should match the | |
1218 | underlying shell, of course. | |
1219 | ||
3b65ce47 | 1220 | @node Terminal emulator |
df9d7630 | 1221 | @subsection Emacs Terminal Emulator |
3b65ce47 DL |
1222 | @findex term |
1223 | ||
932fd020 CY |
1224 | To run a subshell in a terminal emulator, use @kbd{M-x term}. This |
1225 | creates (or reuses) a buffer named @samp{*terminal*}, and runs a | |
1226 | subshell with input coming from your keyboard, and output going to | |
1227 | that buffer. | |
df9d7630 RS |
1228 | |
1229 | The terminal emulator uses Term mode, which has two input modes. In | |
1230 | line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. | |
3b65ce47 | 1231 | |
df9d7630 RS |
1232 | In char mode, each character is sent directly to the inferior |
1233 | subshell, as ``terminal input.'' Any ``echoing'' of your input is the | |
1234 | responsibility of the subshell. The sole exception is the terminal | |
1235 | escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). | |
3b65ce47 DL |
1236 | Any ``terminal output'' from the subshell goes into the buffer, |
1237 | advancing point. | |
1238 | ||
df9d7630 RS |
1239 | Some programs (such as Emacs itself) need to control the appearance |
1240 | on the terminal screen in detail. They do this by sending special | |
1241 | control codes. The exact control codes needed vary from terminal to | |
1242 | terminal, but nowadays most terminals and terminal emulators | |
1243 | (including @code{xterm}) understand the ANSI-standard (VT100-style) | |
1244 | escape sequences. Term mode recognizes these escape sequences, and | |
1245 | handles each one appropriately, changing the buffer so that the | |
1246 | appearance of the window matches what it would be on a real terminal. | |
1247 | You can actually run Emacs inside an Emacs Term window. | |
1248 | ||
37e5d54a | 1249 | You can use Term mode to communicate with a device connected to a |
932fd020 | 1250 | serial port of your computer. @xref{Serial Terminal}. |
37e5d54a GM |
1251 | |
1252 | The file name used to load the subshell is determined the same way | |
df9d7630 | 1253 | as for Shell mode. To make multiple terminal emulators, rename the |
fc98b4ba | 1254 | buffer @samp{*terminal*} to something different using @kbd{M-x |
df9d7630 RS |
1255 | rename-uniquely}, just as with Shell mode. |
1256 | ||
1257 | Unlike Shell mode, Term mode does not track the current directory by | |
1258 | examining your input. But some shells can tell Term what the current | |
1259 | directory is. This is done automatically by @code{bash} version 1.15 | |
1260 | and later. | |
3b65ce47 DL |
1261 | |
1262 | @node Term Mode | |
1263 | @subsection Term Mode | |
1264 | @cindex Term mode | |
1265 | @cindex mode, Term | |
1266 | ||
df9d7630 RS |
1267 | The terminal emulator uses Term mode, which has two input modes. In |
1268 | line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. | |
1269 | In char mode, each character is sent directly to the inferior | |
1270 | subshell, except for the Term escape character, normally @kbd{C-c}. | |
1271 | ||
1272 | To switch between line and char mode, use these commands: | |
3b65ce47 | 1273 | |
3b65ce47 | 1274 | @table @kbd |
91179e97 | 1275 | @kindex C-c C-j @r{(Term mode)} |
3b65ce47 | 1276 | @findex term-char-mode |
91179e97 | 1277 | @item C-c C-j |
3b65ce47 DL |
1278 | Switch to line mode. Do nothing if already in line mode. |
1279 | ||
91179e97 | 1280 | @kindex C-c C-k @r{(Term mode)} |
3b65ce47 | 1281 | @findex term-line-mode |
91179e97 | 1282 | @item C-c C-k |
3b65ce47 DL |
1283 | Switch to char mode. Do nothing if already in char mode. |
1284 | @end table | |
1285 | ||
df9d7630 RS |
1286 | The following commands are only available in char mode: |
1287 | ||
3b65ce47 DL |
1288 | @table @kbd |
1289 | @item C-c C-c | |
1290 | Send a literal @key{C-c} to the sub-shell. | |
1291 | ||
6f8ca5e4 RS |
1292 | @item C-c @var{char} |
1293 | This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For | |
1294 | example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which | |
1295 | is normally @samp{other-window}. | |
3b65ce47 DL |
1296 | @end table |
1297 | ||
1298 | @node Paging in Term | |
df9d7630 RS |
1299 | @subsection Page-At-A-Time Output |
1300 | @cindex page-at-a-time | |
3b65ce47 | 1301 | |
df9d7630 RS |
1302 | Term mode has a page-at-a-time feature. When enabled it makes |
1303 | output pause at the end of each screenful. | |
3b65ce47 DL |
1304 | |
1305 | @table @kbd | |
1306 | @kindex C-c C-q @r{(Term mode)} | |
1307 | @findex term-pager-toggle | |
1308 | @item C-c C-q | |
df9d7630 RS |
1309 | Toggle the page-at-a-time feature. This command works in both line |
1310 | and char modes. When page-at-a-time is enabled, the mode-line | |
1311 | displays the word @samp{page}. | |
3b65ce47 DL |
1312 | @end table |
1313 | ||
df9d7630 RS |
1314 | With page-at-a-time enabled, whenever Term receives more than a |
1315 | screenful of output since your last input, it pauses, displaying | |
1316 | @samp{**MORE**} in the mode-line. Type @key{SPC} to display the next | |
1317 | screenful of output. Type @kbd{?} to see your other options. The | |
892c6176 | 1318 | interface is similar to the @code{more} program. |
3b65ce47 | 1319 | |
6bf7aab6 DL |
1320 | @node Remote Host |
1321 | @subsection Remote Host Shell | |
1322 | @cindex remote host | |
1323 | @cindex connecting to remote host | |
1324 | @cindex Telnet | |
1325 | @cindex Rlogin | |
1326 | ||
3b65ce47 DL |
1327 | You can login to a remote computer, using whatever commands you |
1328 | would from a regular terminal (e.g.@: using the @code{telnet} or | |
1329 | @code{rlogin} commands), from a Term window. | |
1330 | ||
df9d7630 RS |
1331 | A program that asks you for a password will normally suppress |
1332 | echoing of the password, so the password will not show up in the | |
1333 | buffer. This will happen just as if you were using a real terminal, | |
1334 | if the buffer is in char mode. If it is in line mode, the password is | |
1335 | temporarily visible, but will be erased when you hit return. (This | |
1336 | happens automatically; there is no special password processing.) | |
3b65ce47 | 1337 | |
df9d7630 | 1338 | When you log in to a different machine, you need to specify the type |
e51d6b23 LT |
1339 | of terminal you're using, by setting the @env{TERM} environment |
1340 | variable in the environment for the remote login command. (If you use | |
1341 | bash, you do that by writing the variable assignment before the remote | |
1342 | login command, without separating comma.) Terminal types @samp{ansi} | |
1343 | or @samp{vt100} will work on most systems. | |
3b65ce47 DL |
1344 | |
1345 | @c If you are talking to a Bourne-compatible | |
60a96371 | 1346 | @c shell, and your system understands the @env{TERMCAP} variable, |
3b65ce47 DL |
1347 | @c you can use the command @kbd{M-x shell-send-termcap}, which |
1348 | @c sends a string specifying the terminal type and size. | |
1349 | @c (This command is also useful after the window has changed size.) | |
1350 | ||
1351 | @c You can of course run @samp{gdb} on that remote computer. One useful | |
1352 | @c trick: If you invoke gdb with the @code{--fullname} option, | |
1353 | @c it will send special commands to Emacs that will cause Emacs to | |
1354 | @c pop up the source files you're debugging. This will work | |
1355 | @c whether or not gdb is running on a different computer than Emacs, | |
1356 | @c as long as Emacs can access the source files specified by gdb. | |
1357 | ||
df9d7630 | 1358 | @ignore |
021037cb | 1359 | You cannot log in to a remote computer using the Shell mode. |
3b65ce47 DL |
1360 | @c (This will change when Shell is re-written to use Term.) |
1361 | Instead, Emacs provides two commands for logging in to another computer | |
df9d7630 | 1362 | and communicating with it through an Emacs buffer using Comint mode: |
6bf7aab6 DL |
1363 | |
1364 | @table @kbd | |
1365 | @item M-x telnet @key{RET} @var{hostname} @key{RET} | |
1366 | Set up a Telnet connection to the computer named @var{hostname}. | |
1367 | @item M-x rlogin @key{RET} @var{hostname} @key{RET} | |
1368 | Set up an Rlogin connection to the computer named @var{hostname}. | |
1369 | @end table | |
1370 | ||
1371 | @findex telnet | |
1372 | Use @kbd{M-x telnet} to set up a Telnet connection to another | |
1373 | computer. (Telnet is the standard Internet protocol for remote login.) | |
1374 | It reads the host name of the other computer as an argument with the | |
1375 | minibuffer. Once the connection is established, talking to the other | |
1376 | computer works like talking to a subshell: you can edit input with the | |
1377 | usual Emacs commands, and send it a line at a time by typing @key{RET}. | |
1378 | The output is inserted in the Telnet buffer interspersed with the input. | |
1379 | ||
1380 | @findex rlogin | |
1381 | @vindex rlogin-explicit-args | |
1382 | Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is | |
1383 | another remote login communication protocol, essentially much like the | |
1384 | Telnet protocol but incompatible with it, and supported only by certain | |
1385 | systems. Rlogin's advantages are that you can arrange not to have to | |
1386 | give your user name and password when communicating between two machines | |
1387 | you frequently use, and that you can make an 8-bit-clean connection. | |
1388 | (To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} | |
1389 | before you run Rlogin.) | |
1390 | ||
1391 | @kbd{M-x rlogin} sets up the default file directory of the Emacs | |
1392 | buffer to access the remote host via FTP (@pxref{File Names}), and it | |
1393 | tracks the shell commands that change the current directory, just like | |
1394 | Shell mode. | |
1395 | ||
1396 | @findex rlogin-directory-tracking-mode | |
1397 | There are two ways of doing directory tracking in an Rlogin | |
1398 | buffer---either with remote directory names | |
1399 | @file{/@var{host}:@var{dir}/} or with local names (that works if the | |
1400 | ``remote'' machine shares file systems with your machine of origin). | |
1401 | You can use the command @code{rlogin-directory-tracking-mode} to switch | |
1402 | modes. No argument means use remote directory names, a positive | |
1403 | argument means use local names, and a negative argument means turn | |
1404 | off directory tracking. | |
1405 | ||
df9d7630 RS |
1406 | @end ignore |
1407 | ||
37e5d54a GM |
1408 | @node Serial Terminal |
1409 | @subsection Serial Terminal | |
1410 | @cindex terminal, serial | |
1411 | @findex serial-term | |
1412 | ||
1413 | If you have a device connected to a serial port of your computer, | |
1414 | you can use Emacs to communicate with it. @kbd{M-x serial-term} will | |
1415 | ask you for a serial port name and speed and will then open a new | |
1416 | window in @ref{Term Mode}. | |
1417 | ||
1418 | The speed of the serial port is measured in bits per second. The | |
1419 | most common speed is 9600 bits per second. You can change the speed | |
1420 | interactively by clicking on the mode line. | |
1421 | ||
1422 | A serial port can be configured even more by clicking on ``8N1'' in | |
1423 | the mode line. By default, a serial port is configured as ``8N1'', | |
1424 | which means that each byte consists of 8 data bits, No parity check | |
1425 | bit, and 1 stopbit. | |
1426 | ||
1427 | When you have opened the serial port connection, you will see output | |
1428 | from the device in the window. Also, what you type in the window is | |
1429 | sent to the device. | |
1430 | ||
1431 | If the speed or the configuration is wrong, you cannot communicate | |
1432 | with your device and will probably only see garbage output in the | |
1433 | window. | |
1434 | ||
66bb4d9a | 1435 | @node Emacs Server, Printing, Shell, Top |
6bf7aab6 DL |
1436 | @section Using Emacs as a Server |
1437 | @pindex emacsclient | |
1438 | @cindex Emacs as a server | |
1439 | @cindex server, using Emacs as | |
60a96371 | 1440 | @cindex @env{EDITOR} environment variable |
6bf7aab6 | 1441 | |
8cec98c0 CY |
1442 | Various programs such as @command{mail} can invoke your choice of |
1443 | editor to edit a particular piece of text, such as a message that you | |
1444 | are sending. By convention, most of these programs use the | |
1445 | environment variable @env{EDITOR} to specify which editor to run. If | |
1446 | you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an | |
1447 | inconvenient way, by starting a new Emacs process. This is | |
1448 | inconvenient because the new Emacs process doesn't share buffers, a | |
1449 | command history, or other kinds of information with any existing Emacs | |
1450 | process. | |
1451 | ||
1452 | You can solve this problem by setting up Emacs as an @dfn{edit | |
1453 | server}, so that it ``listens'' for external edit requests and acts | |
1454 | accordingly. There are two ways to start an Emacs server: | |
6bf7aab6 | 1455 | |
d9d81805 | 1456 | @findex server-start |
8cec98c0 CY |
1457 | The first is to run the command @code{server-start} in an existing |
1458 | Emacs process: either type @kbd{M-x server-start}, or put the | |
1459 | expression @code{(server-start)} in your initialization file | |
1460 | (@pxref{Init File}). The existing Emacs process is the server; when | |
1461 | you exit Emacs, the server dies with the Emacs process. | |
1462 | ||
1463 | @cindex daemon, Emacs | |
1464 | The second way to start an Emacs server is to run Emacs as a | |
1465 | @dfn{daemon}, using the @samp{--daemon} command-line option. | |
1466 | @xref{Initial Options}. When Emacs is started this way, it calls | |
1467 | @code{server-start} after initialization, and returns control to the | |
1468 | calling terminal instead of opening an initial frame; it then waits in | |
1469 | the background, listening for edit requests. | |
df9d7630 | 1470 | |
8cec98c0 CY |
1471 | @cindex @env{TEXEDIT} environment variable |
1472 | Once an Emacs server is set up, you can use a shell command called | |
1473 | @command{emacsclient} to connect to the existing Emacs process and | |
1474 | tell it to visit a file. If you set the @env{EDITOR} environment | |
1475 | variable to @samp{emacsclient}, programs such as @command{mail} will | |
1476 | use the existing Emacs process for editing.@footnote{Some programs use | |
1477 | a different environment variable; for example, to make @TeX{} use | |
1478 | @samp{emacsclient}, set the @env{TEXEDIT} environment variable to | |
1479 | @samp{emacsclient +%d %s}.} | |
6bf7aab6 | 1480 | |
82b9073d RS |
1481 | @vindex server-name |
1482 | You can run multiple Emacs servers on the same machine by giving | |
1483 | each one a unique ``server name'', using the variable | |
4f256c8e RS |
1484 | @code{server-name}. For example, @kbd{M-x set-variable @key{RET} |
1485 | server-name @key{RET} foo @key{RET}} sets the server name to | |
d9d81805 | 1486 | @samp{foo}. The @code{emacsclient} program can specify a server by |
8cec98c0 | 1487 | name, using the @samp{-s} option (@pxref{emacsclient Options}). |
82b9073d | 1488 | |
8cec98c0 CY |
1489 | @menu |
1490 | * Invoking emacsclient:: Connecting to the Emacs server. | |
1491 | * emacsclient Options:: Emacs client startup options. | |
1492 | @end menu | |
6bf7aab6 | 1493 | |
8cec98c0 CY |
1494 | @node Invoking emacsclient |
1495 | @subsection Invoking @code{emacsclient} | |
1496 | @cindex @code{emacsclient} invocation | |
1497 | ||
1498 | The simplest way to use the @command{emacsclient} program is to run | |
1499 | the shell command @samp{emacsclient @var{file}}, where @var{file} is a | |
1500 | file name. This connects to an Emacs server, and tells that Emacs | |
1501 | process to visit @var{file} in one of its existing frames---either a | |
1502 | graphical frame, or one in a text-only terminal (@pxref{Frames}). You | |
a568b1f9 | 1503 | can then select that frame to begin editing. |
8cec98c0 CY |
1504 | |
1505 | If there is no Emacs server, the @command{emacsclient} program halts | |
1506 | with an error message. If the Emacs process has no existing | |
1507 | frame---which can happen if it was started as a daemon (@pxref{Emacs | |
8b72835c | 1508 | Server})---then Emacs opens a frame on the terminal in which you |
6a5ca7c8 CY |
1509 | called @command{emacsclient}. |
1510 | ||
1511 | You can also force @command{emacsclient} to open a new frame on a | |
1512 | graphical display, or on a text-only terminal, using the @samp{-c} and | |
1513 | @samp{-t} options. @xref{emacsclient Options}. | |
1514 | ||
1515 | If you are running on a single text-only terminal, you can switch | |
1516 | between @command{emacsclient}'s shell and the Emacs server using one | |
1517 | of two methods: (i) run the Emacs server and @command{emacsclient} on | |
1518 | different virtual terminals, and switch to the Emacs server's virtual | |
1519 | terminal after calling @command{emacsclient}; or (ii) call | |
1520 | @command{emacsclient} from within the Emacs server itself, using Shell | |
1521 | mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode}); | |
1522 | @code{emacsclient} blocks only the subshell under Emacs, and you can | |
1523 | still use Emacs to edit the file. | |
a568b1f9 | 1524 | |
8cec98c0 CY |
1525 | @kindex C-x # |
1526 | @findex server-edit | |
a568b1f9 CY |
1527 | When you finish editing @var{file} in the Emacs server, type |
1528 | @kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file | |
1529 | and sends a message back to the @command{emacsclient} program, telling | |
1530 | it to exit. Programs that use @env{EDITOR} usually wait for the | |
da0bbbc4 | 1531 | ``editor''---in this case @command{emacsclient}---to exit before doing |
a568b1f9 | 1532 | something else. |
8cec98c0 CY |
1533 | |
1534 | You can also call @command{emacsclient} with multiple file name | |
1535 | arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the | |
1536 | Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs | |
1537 | selects the buffer visiting @var{file1}, and buries the other buffers | |
1538 | at the bottom of the buffer list (@pxref{Buffers}). The | |
1539 | @command{emacsclient} program exits once all the specified files are | |
1540 | finished (i.e., once you have typed @kbd{C-x #} in each server | |
1541 | buffer). | |
6bf7aab6 | 1542 | |
8cec98c0 CY |
1543 | @vindex server-kill-new-buffers |
1544 | @vindex server-temp-file-regexp | |
1545 | Finishing with a server buffer also kills the buffer, unless it | |
1546 | already existed in the Emacs session before the server was asked to | |
1547 | create it. However, if you set @code{server-kill-new-buffers} to | |
1548 | @code{nil}, then a different criterion is used: finishing with a | |
1549 | server buffer kills it if the file name matches the regular expression | |
1550 | @code{server-temp-file-regexp}. This is set up to distinguish certain | |
1551 | ``temporary'' files. | |
7448f7a2 | 1552 | |
8cec98c0 CY |
1553 | Each @kbd{C-x #} checks for other pending external requests to edit |
1554 | various files, and selects the next such file. You can switch to a | |
1555 | server buffer manually if you wish; you don't have to arrive at it | |
1556 | with @kbd{C-x #}. But @kbd{C-x #} is the way to tell | |
1557 | @command{emacsclient} that you are finished. | |
b1a92ebf | 1558 | |
8cec98c0 | 1559 | @vindex server-window |
6a5ca7c8 CY |
1560 | If you set the value of the variable @code{server-window} to a |
1561 | window or a frame, @kbd{C-x #} always displays the next server buffer | |
1562 | in that window or in that frame. | |
6bf7aab6 | 1563 | |
8cec98c0 CY |
1564 | @node emacsclient Options |
1565 | @subsection @code{emacsclient} Options | |
1566 | @cindex @code{emacsclient} options | |
6bf7aab6 | 1567 | |
8cec98c0 CY |
1568 | You can pass some optional arguments to the @command{emacsclient} |
1569 | program, such as: | |
6bf7aab6 DL |
1570 | |
1571 | @example | |
8cec98c0 | 1572 | emacsclient -c +12 @var{file1} +4:3 @var{file2} |
6bf7aab6 DL |
1573 | @end example |
1574 | ||
df9d7630 | 1575 | @noindent |
78b6d6d2 CY |
1576 | The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments |
1577 | specify line numbers, or line and column numbers, for the next file | |
1578 | argument. These behave like the command line arguments for Emacs | |
1579 | itself. @xref{Action Arguments}. | |
8cec98c0 CY |
1580 | |
1581 | The other optional arguments recognized by @command{emacsclient} are | |
1582 | listed below: | |
1583 | ||
1584 | @table @samp | |
1585 | @item -a @var{command} | |
1586 | @itemx --alternate-editor=@var{command} | |
1587 | Specify a command to run if @code{emacsclient} fails to contact Emacs. | |
932fd020 CY |
1588 | This is useful when running @code{emacsclient} in a script. For |
1589 | example, the following setting for the @env{EDITOR} environment | |
1590 | variable will always give you an editor, even if no Emacs server is | |
1591 | running: | |
6bf7aab6 | 1592 | |
df9d7630 | 1593 | @example |
982dcb1b | 1594 | EDITOR="emacsclient --alternate-editor emacs +%d %s" |
df9d7630 | 1595 | @end example |
6bf7aab6 | 1596 | |
df9d7630 | 1597 | @noindent |
932fd020 CY |
1598 | As a special exception, if @var{command} is the empty string, then |
1599 | @code{emacsclient} starts Emacs in daemon mode and then tries | |
1600 | connecting again. | |
1601 | ||
d9d81805 | 1602 | @cindex @env{ALTERNATE_EDITOR} environment variable |
932fd020 CY |
1603 | The environment variable @env{ALTERNATE_EDITOR} has the same effect as |
1604 | the @samp{-a} option. If both are present, the latter takes | |
8cec98c0 CY |
1605 | precedence. |
1606 | ||
1607 | @item -c | |
1608 | Create a new graphical frame, instead of using an existing Emacs | |
78b6d6d2 CY |
1609 | frame. Emacs 23 can create a graphical frame even if it was started |
1610 | in a text-only terminal, provided it is able to connect to a graphical | |
1611 | display. If no graphical display is available, Emacs creates a new | |
1612 | text-only terminal frame (@pxref{Frames}). If you omit a filename | |
1613 | argument while supplying the @samp{-c} option, the new frame displays | |
1614 | the @samp{*scratch*} buffer (@pxref{Buffers}). | |
8cec98c0 CY |
1615 | |
1616 | @item -d @var{display} | |
1617 | @itemx --display=@var{display} | |
1618 | Tell Emacs to open the given files on the X display @var{display} | |
1619 | (assuming there is more than one X display available). | |
1620 | ||
1621 | @item -e | |
1622 | @itemx --eval | |
1623 | Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some | |
1624 | files. When this option is given, the arguments to | |
1625 | @command{emacsclient} are interpreted as a list of expressions to | |
1626 | evaluate, @emph{not} as a list of files to visit. | |
1627 | ||
1628 | @item -f @var{server-file} | |
1629 | @itemx --server-file=@var{server-file} | |
d9d81805 | 1630 | @cindex @env{EMACS_SERVER_FILE} environment variable |
8cec98c0 | 1631 | @cindex server file |
01bfa900 CY |
1632 | @vindex server-use-tcp |
1633 | @vindex server-host | |
8cec98c0 CY |
1634 | Specify a @dfn{server file} for connecting to an Emacs server via TCP. |
1635 | ||
01bfa900 | 1636 | An Emacs server usually uses an operating system feature called a |
8cec98c0 CY |
1637 | ``local socket'' to listen for connections. Some operating systems, |
1638 | such as Microsoft Windows, do not support local sockets; in that case, | |
01bfa900 CY |
1639 | Emacs uses TCP instead. When you start the Emacs server, Emacs |
1640 | creates a server file containing some TCP information that | |
1641 | @command{emacsclient} needs for making the connection. By default, | |
1642 | the server file is in @file{~/.emacs.d/server/}. On Microsoft | |
1643 | Windows, if @command{emacsclient} does not find the server file there, | |
1644 | it looks in the @file{.emacs.d/server/} subdirectory of the directory | |
1645 | pointed to by the @env{APPDATA} environment variable. You can tell | |
1646 | @command{emacsclient} to use a specific server file with the @samp{-f} | |
1647 | or @samp{--server-file} option, or by setting the | |
1648 | @env{EMACS_SERVER_FILE} environment variable. | |
1649 | ||
1650 | Even if local sockets are available, you can tell Emacs to use TCP by | |
1651 | setting the variable @code{server-use-tcp} to @code{t}. One advantage | |
1652 | of TCP is that the server can accept connections from remote machines. | |
1653 | For this to work, you must (i) set the variable @code{server-host} to | |
1654 | the hostname or IP address of the machine on which the Emacs server | |
1655 | runs, and (ii) provide @command{emacsclient} with the server file. | |
1656 | (One convenient way to do the latter is to put the server file on a | |
1657 | networked file system such as NFS.) | |
5b8b9fa7 | 1658 | |
8cec98c0 CY |
1659 | @item -n |
1660 | @itemx --no-wait | |
1661 | Let @command{emacsclient} exit immediately, instead of waiting until | |
1662 | all server buffers are finished. You can take as long as you like to | |
1663 | edit the server buffers within Emacs, and they are @emph{not} killed | |
1664 | when you type @kbd{C-x #} in them. | |
1665 | ||
1666 | @item -s @var{server-name} | |
1667 | @itemx --socket-name=@var{server-name} | |
1668 | Connect to the Emacs server named @var{server-name}. The server name | |
1669 | is given by the variable @code{server-name} on the Emacs server. If | |
1670 | this option is omitted, @command{emacsclient} connects to the first | |
1671 | server it finds. (This option is not supported on MS-Windows.) | |
1672 | ||
1673 | @item -t | |
1674 | @itemx --tty | |
1675 | @itemx -nw | |
1676 | Create a new Emacs frame on the current text-only terminal, instead of | |
78b6d6d2 CY |
1677 | using an existing Emacs frame. Emacs 23 can open a text-only terminal |
1678 | even if it was started in another text-only terminal, or on a | |
1679 | graphical display. If you omit a filename argument while supplying | |
1680 | this option, the new frame displays the @samp{*scratch*} buffer. | |
1681 | @xref{Buffers}. | |
8cec98c0 CY |
1682 | @end table |
1683 | ||
1684 | If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an | |
1685 | Emacs frame created with @command{emacsclient}, via the @samp{-c} or | |
1686 | @samp{-t} options, Emacs deletes the frame instead of killing the | |
1687 | Emacs process itself. On a text-only terminal frame created with the | |
1688 | @samp{-t} option, this returns control to the terminal. Emacs also | |
1689 | marks all the server buffers for the client as finished, as though you | |
1690 | had typed @kbd{C-x #} in all of them. | |
1691 | ||
1692 | When Emacs is started as a daemon, all frames are considered client | |
1693 | frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs | |
1694 | process, type @kbd{M-x kill-emacs}. | |
1695 | ||
66bb4d9a EZ |
1696 | @node Printing, Sorting, Emacs Server, Top |
1697 | @section Printing Hard Copies | |
6bf7aab6 | 1698 | @cindex hardcopy |
66bb4d9a | 1699 | @cindex printing |
6bf7aab6 | 1700 | |
66bb4d9a EZ |
1701 | Emacs provides commands for printing hard copies of either an entire |
1702 | buffer or just part of one, with or without page headers. You can | |
1703 | invoke the printing commands directly, as detailed in the following | |
eb5ed549 CY |
1704 | section, or using the @samp{File} menu on the menu bar. |
1705 | ||
1706 | @findex htmlfontify-buffer | |
1707 | Aside from the commands described in this section, you can also | |
1708 | ``print'' an Emacs buffer to HTML with @kbd{M-x htmlfontify-buffer}. | |
1709 | This command converts the current buffer to a HTML file, replacing | |
1710 | Emacs faces with CSS-based markup. In addition, see the hardcopy | |
1711 | commands of Dired (@pxref{Misc File Ops}) and the diary | |
66bb4d9a | 1712 | (@pxref{Displaying the Diary}). |
6bf7aab6 DL |
1713 | |
1714 | @table @kbd | |
1715 | @item M-x print-buffer | |
1716 | Print hardcopy of current buffer with page headings containing the file | |
1717 | name and page number. | |
1718 | @item M-x lpr-buffer | |
1719 | Print hardcopy of current buffer without page headings. | |
1720 | @item M-x print-region | |
1721 | Like @code{print-buffer} but print only the current region. | |
1722 | @item M-x lpr-region | |
1723 | Like @code{lpr-buffer} but print only the current region. | |
1724 | @end table | |
1725 | ||
1726 | @findex print-buffer | |
1727 | @findex print-region | |
1728 | @findex lpr-buffer | |
1729 | @findex lpr-region | |
1730 | @vindex lpr-switches | |
891c0674 | 1731 | The hardcopy commands (aside from the PostScript commands) pass extra |
6bf7aab6 DL |
1732 | switches to the @code{lpr} program based on the value of the variable |
1733 | @code{lpr-switches}. Its value should be a list of strings, each string | |
1734 | an option starting with @samp{-}. For example, to specify a line width | |
1735 | of 80 columns for all the printing you do in Emacs, set | |
1736 | @code{lpr-switches} like this: | |
1737 | ||
1738 | @example | |
1739 | (setq lpr-switches '("-w80")) | |
1740 | @end example | |
1741 | ||
1742 | @vindex printer-name | |
1743 | You can specify the printer to use by setting the variable | |
1744 | @code{printer-name}. | |
1745 | ||
1746 | @vindex lpr-headers-switches | |
1747 | @vindex lpr-commands | |
1748 | @vindex lpr-add-switches | |
1749 | The variable @code{lpr-command} specifies the name of the printer | |
1750 | program to run; the default value depends on your operating system type. | |
1751 | On most systems, the default is @code{"lpr"}. The variable | |
1752 | @code{lpr-headers-switches} similarly specifies the extra switches to | |
1753 | use to make page headers. The variable @code{lpr-add-switches} controls | |
1754 | whether to supply @samp{-T} and @samp{-J} options (suitable for | |
1755 | @code{lpr}) to the printer program: @code{nil} means don't add them. | |
1756 | @code{lpr-add-switches} should be @code{nil} if your printer program is | |
1757 | not compatible with @code{lpr}. | |
1758 | ||
66bb4d9a | 1759 | @menu |
8838673e | 1760 | * PostScript:: Printing buffers or regions as PostScript. |
66bb4d9a EZ |
1761 | * PostScript Variables:: Customizing the PostScript printing commands. |
1762 | * Printing Package:: An optional advanced printing interface. | |
1763 | @end menu | |
1764 | ||
1765 | @node PostScript, PostScript Variables,, Printing | |
3b65ce47 | 1766 | @section PostScript Hardcopy |
6bf7aab6 | 1767 | |
3b65ce47 | 1768 | These commands convert buffer contents to PostScript, |
6bf7aab6 DL |
1769 | either printing it or leaving it in another Emacs buffer. |
1770 | ||
1771 | @table @kbd | |
1772 | @item M-x ps-print-buffer | |
3b65ce47 | 1773 | Print hardcopy of the current buffer in PostScript form. |
6bf7aab6 | 1774 | @item M-x ps-print-region |
3b65ce47 | 1775 | Print hardcopy of the current region in PostScript form. |
6bf7aab6 | 1776 | @item M-x ps-print-buffer-with-faces |
3b65ce47 DL |
1777 | Print hardcopy of the current buffer in PostScript form, showing the |
1778 | faces used in the text by means of PostScript features. | |
6bf7aab6 | 1779 | @item M-x ps-print-region-with-faces |
3b65ce47 | 1780 | Print hardcopy of the current region in PostScript form, showing the |
6bf7aab6 DL |
1781 | faces used in the text. |
1782 | @item M-x ps-spool-buffer | |
2f298da2 | 1783 | Generate and spool a PostScript image for the current buffer text. |
6bf7aab6 | 1784 | @item M-x ps-spool-region |
2f298da2 | 1785 | Generate and spool a PostScript image for the current region. |
6bf7aab6 | 1786 | @item M-x ps-spool-buffer-with-faces |
2f298da2 | 1787 | Generate and spool a PostScript image for the current buffer, showing the faces used. |
6bf7aab6 | 1788 | @item M-x ps-spool-region-with-faces |
2f298da2 VJL |
1789 | Generate and spool a PostScript image for the current region, showing the faces used. |
1790 | @item M-x ps-despool | |
1791 | Send the spooled PostScript to the printer. | |
3b65ce47 | 1792 | @item M-x handwrite |
2f298da2 | 1793 | Generate/print PostScript for the current buffer as if handwritten. |
6bf7aab6 DL |
1794 | @end table |
1795 | ||
1796 | @findex ps-print-region | |
1797 | @findex ps-print-buffer | |
1798 | @findex ps-print-region-with-faces | |
1799 | @findex ps-print-buffer-with-faces | |
3b65ce47 DL |
1800 | The PostScript commands, @code{ps-print-buffer} and |
1801 | @code{ps-print-region}, print buffer contents in PostScript form. One | |
6bf7aab6 DL |
1802 | command prints the entire buffer; the other, just the region. The |
1803 | corresponding @samp{-with-faces} commands, | |
1804 | @code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces}, | |
3b65ce47 | 1805 | use PostScript features to show the faces (fonts and colors) in the text |
2f298da2 VJL |
1806 | properties of the text being printed. The @samp{-with-faces} commands only |
1807 | work if they are used in a window system, so it has a way to determine color | |
1808 | values. | |
1809 | ||
1810 | Interactively, when you use a prefix argument (@kbd{C-u}), the command | |
1811 | prompts the user for a file name, and saves the PostScript image in that file | |
1812 | instead of sending it to the printer. | |
1813 | ||
1814 | Noninteractively, the argument @var{filename} is treated as follows: if it is | |
1815 | @code{nil}, send the image to the printer. If @var{filename} is a string, save | |
1816 | the PostScript image in a file with that name. | |
6bf7aab6 DL |
1817 | |
1818 | If you are using a color display, you can print a buffer of program | |
1819 | code with color highlighting by turning on Font-Lock mode in that | |
1820 | buffer, and using @code{ps-print-buffer-with-faces}. | |
1821 | ||
1822 | @findex ps-spool-region | |
1823 | @findex ps-spool-buffer | |
1824 | @findex ps-spool-region-with-faces | |
1825 | @findex ps-spool-buffer-with-faces | |
2f298da2 | 1826 | The commands whose names have @samp{spool} instead of @samp{print}, |
3b65ce47 | 1827 | generate the PostScript output in an Emacs buffer instead of sending |
6bf7aab6 DL |
1828 | it to the printer. |
1829 | ||
2f298da2 VJL |
1830 | Use the command @code{ps-despool} to send the spooled images to the printer. |
1831 | ||
1832 | @findex ps-despool | |
1833 | This command sends the PostScript generated by @samp{-spool-} commands (see | |
1834 | commands above) to the printer. | |
1835 | ||
1836 | Interactively, when you use a prefix argument (@kbd{C-u}), the command | |
1837 | prompts the user for a file name, and saves the spooled PostScript image in | |
1838 | that file instead of sending it to the printer. | |
1839 | ||
1840 | Noninteractively, the argument @var{filename} is treated as follows: if it is | |
1841 | @code{nil}, send the image to the printer. If @var{filename} is a string, save | |
1842 | the PostScript image in a file with that name. | |
1843 | ||
3b65ce47 DL |
1844 | @findex handwrite |
1845 | @cindex handwriting | |
1846 | @kbd{M-x handwrite} is more frivolous. It generates a PostScript | |
1847 | rendition of the current buffer as a cursive handwritten document. It | |
fc98b4ba RS |
1848 | can be customized in group @code{handwrite}. This function only |
1849 | supports ISO 8859-1 characters. | |
3b65ce47 | 1850 | |
d3ea5f55 | 1851 | @ifnottex |
6bf7aab6 | 1852 | The following section describes variables for customizing these commands. |
d3ea5f55 | 1853 | @end ifnottex |
6bf7aab6 | 1854 | |
66bb4d9a | 1855 | @node PostScript Variables, Printing Package, PostScript, Printing |
3b65ce47 | 1856 | @section Variables for PostScript Hardcopy |
6bf7aab6 DL |
1857 | |
1858 | @vindex ps-lpr-command | |
1859 | @vindex ps-lpr-switches | |
1860 | @vindex ps-printer-name | |
3b65ce47 | 1861 | All the PostScript hardcopy commands use the variables |
6bf7aab6 DL |
1862 | @code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print |
1863 | the output. @code{ps-lpr-command} specifies the command name to run, | |
1864 | @code{ps-lpr-switches} specifies command line options to use, and | |
1865 | @code{ps-printer-name} specifies the printer. If you don't set the | |
1866 | first two variables yourself, they take their initial values from | |
1867 | @code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} | |
1868 | is @code{nil}, @code{printer-name} is used. | |
1869 | ||
1870 | @vindex ps-print-header | |
6bf7aab6 DL |
1871 | The variable @code{ps-print-header} controls whether these commands |
1872 | add header lines to each page---set it to @code{nil} to turn headers | |
550135d1 EZ |
1873 | off. |
1874 | ||
1875 | @cindex color emulation on black-and-white printers | |
1876 | @vindex ps-print-color-p | |
1877 | If your printer doesn't support colors, you should turn off color | |
1878 | processing by setting @code{ps-print-color-p} to @code{nil}. By | |
1879 | default, if the display supports colors, Emacs produces hardcopy output | |
1880 | with color information; on black-and-white printers, colors are emulated | |
1881 | with shades of gray. This might produce illegible output, even if your | |
1882 | screen colors only use shades of gray. | |
1883 | ||
2f298da2 VJL |
1884 | Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to |
1885 | print colors on black/white printers. | |
1886 | ||
550135d1 | 1887 | @vindex ps-use-face-background |
df9d7630 RS |
1888 | By default, PostScript printing ignores the background colors of the |
1889 | faces, unless the variable @code{ps-use-face-background} is | |
1890 | non-@code{nil}. This is to avoid unwanted interference with the zebra | |
1891 | stripes and background image/text. | |
6bf7aab6 DL |
1892 | |
1893 | @vindex ps-paper-type | |
1894 | @vindex ps-page-dimensions-database | |
1895 | The variable @code{ps-paper-type} specifies which size of paper to | |
1896 | format for; legitimate values include @code{a4}, @code{a3}, | |
1897 | @code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, | |
1898 | @code{legal}, @code{letter}, @code{letter-small}, @code{statement}, | |
1899 | @code{tabloid}. The default is @code{letter}. You can define | |
1900 | additional paper sizes by changing the variable | |
1901 | @code{ps-page-dimensions-database}. | |
1902 | ||
1903 | @vindex ps-landscape-mode | |
1904 | The variable @code{ps-landscape-mode} specifies the orientation of | |
1905 | printing on the page. The default is @code{nil}, which stands for | |
1906 | ``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' | |
1907 | mode. | |
1908 | ||
1909 | @vindex ps-number-of-columns | |
1910 | The variable @code{ps-number-of-columns} specifies the number of | |
1911 | columns; it takes effect in both landscape and portrait mode. The | |
1912 | default is 1. | |
1913 | ||
1914 | @vindex ps-font-family | |
1915 | @vindex ps-font-size | |
1916 | @vindex ps-font-info-database | |
1917 | The variable @code{ps-font-family} specifies which font family to use | |
1918 | for printing ordinary text. Legitimate values include @code{Courier}, | |
1919 | @code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and | |
1920 | @code{Times}. The variable @code{ps-font-size} specifies the size of | |
1921 | the font for ordinary text. It defaults to 8.5 points. | |
1922 | ||
adee28ff EZ |
1923 | @vindex ps-multibyte-buffer |
1924 | @cindex Intlfonts for PostScript printing | |
1925 | @cindex fonts for PostScript printing | |
1926 | Emacs supports more scripts and characters than a typical PostScript | |
1927 | printer. Thus, some of the characters in your buffer might not be | |
1928 | printable using the fonts built into your printer. You can augment | |
1929 | the fonts supplied with the printer with those from the GNU Intlfonts | |
1930 | package, or you can instruct Emacs to use Intlfonts exclusively. The | |
1931 | variable @code{ps-multibyte-buffer} controls this: the default value, | |
76dd3692 | 1932 | @code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 |
adee28ff | 1933 | characters; a value of @code{non-latin-printer} is for printers which |
76dd3692 | 1934 | have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean |
adee28ff EZ |
1935 | characters built into them. A value of @code{bdf-font} arranges for |
1936 | the BDF fonts from the Intlfonts package to be used for @emph{all} | |
1937 | characters. Finally, a value of @code{bdf-font-except-latin} | |
76dd3692 | 1938 | instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 |
adee28ff EZ |
1939 | characters, and Intlfonts BDF fonts for the rest. |
1940 | ||
1941 | @vindex bdf-directory-list | |
021037cb | 1942 | To be able to use the BDF fonts, Emacs needs to know where to find |
adee28ff EZ |
1943 | them. The variable @code{bdf-directory-list} holds the list of |
1944 | directories where Emacs should look for the fonts; the default value | |
1945 | includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. | |
1946 | ||
6bf7aab6 | 1947 | Many other customization variables for these commands are defined and |
adee28ff | 1948 | described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. |
6bf7aab6 | 1949 | |
66bb4d9a EZ |
1950 | @node Printing Package,, PostScript Variables, Printing |
1951 | @section Printing Package | |
1952 | @cindex Printing package | |
1953 | ||
1954 | The basic Emacs facilities for printing hardcopy can be extended | |
1955 | using the Printing package. This provides an easy-to-use interface | |
1956 | for choosing what to print, previewing PostScript files before | |
1957 | printing, and setting various printing options such as print headers, | |
1958 | landscape or portrait modes, duplex modes, and so forth. On GNU/Linux | |
1959 | or Unix systems, the Printing package relies on the @file{gs} and | |
1960 | @file{gv} utilities, which are distributed as part of the GhostScript | |
1961 | program. On MS-Windows, the @file{gstools} port of Ghostscript can be | |
1962 | used. | |
1963 | ||
1964 | @findex pr-interface | |
1965 | To use the Printing package, add @code{(require 'printing)} to your | |
aada47fc RS |
1966 | init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. |
1967 | This function replaces the usual printing commands in the menu bar | |
1968 | with a @samp{Printing} submenu that contains various printing options. | |
1969 | You can also type @kbd{M-x pr-interface RET}; this creates a | |
1970 | @samp{*Printing Interface*} buffer, similar to a customization buffer, | |
1971 | where you can set the printing options. After selecting what and how | |
1972 | to print, you start the print job using the @samp{Print} button (click | |
1973 | @kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For | |
1974 | further information on the various options, use the @samp{Interface | |
1975 | Help} button. | |
66bb4d9a EZ |
1976 | |
1977 | @node Sorting, Narrowing, Printing, Top | |
6bf7aab6 DL |
1978 | @section Sorting Text |
1979 | @cindex sorting | |
1980 | ||
1981 | Emacs provides several commands for sorting text in the buffer. All | |
982dcb1b RS |
1982 | operate on the contents of the region. |
1983 | They divide the text of the region into many @dfn{sort records}, | |
6bf7aab6 DL |
1984 | identify a @dfn{sort key} for each record, and then reorder the records |
1985 | into the order determined by the sort keys. The records are ordered so | |
1986 | that their keys are in alphabetical order, or, for numeric sorting, in | |
1987 | numeric order. In alphabetic sorting, all upper-case letters `A' through | |
76dd3692 | 1988 | `Z' come before lower-case `a', in accord with the @acronym{ASCII} character |
6bf7aab6 DL |
1989 | sequence. |
1990 | ||
1991 | The various sort commands differ in how they divide the text into sort | |
1992 | records and in which part of each record is used as the sort key. Most of | |
1993 | the commands make each line a separate sort record, but some commands use | |
1994 | paragraphs or pages as sort records. Most of the sort commands use each | |
1995 | entire sort record as its own sort key, but some use only a portion of the | |
1996 | record as the sort key. | |
1997 | ||
1998 | @findex sort-lines | |
1999 | @findex sort-paragraphs | |
2000 | @findex sort-pages | |
2001 | @findex sort-fields | |
2002 | @findex sort-numeric-fields | |
efd68b8a | 2003 | @vindex sort-numeric-base |
6bf7aab6 DL |
2004 | @table @kbd |
2005 | @item M-x sort-lines | |
2006 | Divide the region into lines, and sort by comparing the entire | |
2007 | text of a line. A numeric argument means sort into descending order. | |
2008 | ||
2009 | @item M-x sort-paragraphs | |
2010 | Divide the region into paragraphs, and sort by comparing the entire | |
2011 | text of a paragraph (except for leading blank lines). A numeric | |
2012 | argument means sort into descending order. | |
2013 | ||
2014 | @item M-x sort-pages | |
2015 | Divide the region into pages, and sort by comparing the entire | |
2016 | text of a page (except for leading blank lines). A numeric | |
2017 | argument means sort into descending order. | |
2018 | ||
2019 | @item M-x sort-fields | |
2020 | Divide the region into lines, and sort by comparing the contents of | |
2021 | one field in each line. Fields are defined as separated by | |
2022 | whitespace, so the first run of consecutive non-whitespace characters | |
2023 | in a line constitutes field 1, the second such run constitutes field | |
2024 | 2, etc. | |
2025 | ||
2026 | Specify which field to sort by with a numeric argument: 1 to sort by | |
2027 | field 1, etc. A negative argument means count fields from the right | |
2028 | instead of from the left; thus, minus 1 means sort by the last field. | |
2029 | If several lines have identical contents in the field being sorted, they | |
021037cb | 2030 | keep the same relative order that they had in the original buffer. |
6bf7aab6 DL |
2031 | |
2032 | @item M-x sort-numeric-fields | |
2033 | Like @kbd{M-x sort-fields} except the specified field is converted | |
2034 | to an integer for each line, and the numbers are compared. @samp{10} | |
2035 | comes before @samp{2} when considered as text, but after it when | |
efd68b8a GM |
2036 | considered as a number. By default, numbers are interpreted according |
2037 | to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or | |
2038 | @samp{0} are interpreted as hexadecimal and octal, respectively. | |
6bf7aab6 DL |
2039 | |
2040 | @item M-x sort-columns | |
2041 | Like @kbd{M-x sort-fields} except that the text within each line | |
2042 | used for comparison comes from a fixed range of columns. See below | |
2043 | for an explanation. | |
2044 | ||
2045 | @item M-x reverse-region | |
2046 | Reverse the order of the lines in the region. This is useful for | |
2047 | sorting into descending order by fields or columns, since those sort | |
2048 | commands do not have a feature for doing that. | |
2049 | @end table | |
2050 | ||
2051 | For example, if the buffer contains this: | |
2052 | ||
2053 | @smallexample | |
2054 | On systems where clash detection (locking of files being edited) is | |
2055 | implemented, Emacs also checks the first time you modify a buffer | |
2056 | whether the file has changed on disk since it was last visited or | |
2057 | saved. If it has, you are asked to confirm that you want to change | |
2058 | the buffer. | |
2059 | @end smallexample | |
2060 | ||
2061 | @noindent | |
2062 | applying @kbd{M-x sort-lines} to the entire buffer produces this: | |
2063 | ||
2064 | @smallexample | |
2065 | On systems where clash detection (locking of files being edited) is | |
2066 | implemented, Emacs also checks the first time you modify a buffer | |
2067 | saved. If it has, you are asked to confirm that you want to change | |
2068 | the buffer. | |
2069 | whether the file has changed on disk since it was last visited or | |
2070 | @end smallexample | |
2071 | ||
2072 | @noindent | |
2073 | where the upper-case @samp{O} sorts before all lower-case letters. If | |
2074 | you use @kbd{C-u 2 M-x sort-fields} instead, you get this: | |
2075 | ||
2076 | @smallexample | |
2077 | implemented, Emacs also checks the first time you modify a buffer | |
2078 | saved. If it has, you are asked to confirm that you want to change | |
2079 | the buffer. | |
2080 | On systems where clash detection (locking of files being edited) is | |
2081 | whether the file has changed on disk since it was last visited or | |
2082 | @end smallexample | |
2083 | ||
2084 | @noindent | |
2085 | where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, | |
2086 | @samp{systems} and @samp{the}. | |
2087 | ||
2088 | @findex sort-columns | |
2089 | @kbd{M-x sort-columns} requires more explanation. You specify the | |
2090 | columns by putting point at one of the columns and the mark at the other | |
2091 | column. Because this means you cannot put point or the mark at the | |
2092 | beginning of the first line of the text you want to sort, this command | |
2684ed46 | 2093 | uses an unusual definition of ``region'': all of the line point is in is |
6bf7aab6 DL |
2094 | considered part of the region, and so is all of the line the mark is in, |
2095 | as well as all the lines in between. | |
2096 | ||
2097 | For example, to sort a table by information found in columns 10 to 15, | |
2098 | you could put the mark on column 10 in the first line of the table, and | |
2099 | point on column 15 in the last line of the table, and then run | |
2100 | @code{sort-columns}. Equivalently, you could run it with the mark on | |
2101 | column 15 in the first line and point on column 10 in the last line. | |
2102 | ||
2103 | This can be thought of as sorting the rectangle specified by point and | |
2104 | the mark, except that the text on each line to the left or right of the | |
2105 | rectangle moves along with the text inside the rectangle. | |
2106 | @xref{Rectangles}. | |
2107 | ||
2108 | @vindex sort-fold-case | |
2109 | Many of the sort commands ignore case differences when comparing, if | |
2110 | @code{sort-fold-case} is non-@code{nil}. | |
2111 | ||
379e8670 | 2112 | @node Narrowing, Two-Column, Sorting, Top |
6bf7aab6 DL |
2113 | @section Narrowing |
2114 | @cindex widening | |
2115 | @cindex restriction | |
2116 | @cindex narrowing | |
2117 | @cindex accessible portion | |
2118 | ||
2119 | @dfn{Narrowing} means focusing in on some portion of the buffer, | |
2120 | making the rest temporarily inaccessible. The portion which you can | |
2121 | still get to is called the @dfn{accessible portion}. Canceling the | |
2122 | narrowing, which makes the entire buffer once again accessible, is | |
d40afceb RS |
2123 | called @dfn{widening}. The bounds of narrowing in effect in a buffer |
2124 | are called the buffer's @dfn{restriction}. | |
6bf7aab6 DL |
2125 | |
2126 | Narrowing can make it easier to concentrate on a single subroutine or | |
d40afceb | 2127 | paragraph by eliminating clutter. It can also be used to limit the |
6bf7aab6 DL |
2128 | range of operation of a replace command or repeating keyboard macro. |
2129 | ||
6bf7aab6 DL |
2130 | @table @kbd |
2131 | @item C-x n n | |
2132 | Narrow down to between point and mark (@code{narrow-to-region}). | |
2133 | @item C-x n w | |
2134 | Widen to make the entire buffer accessible again (@code{widen}). | |
2135 | @item C-x n p | |
2136 | Narrow down to the current page (@code{narrow-to-page}). | |
2137 | @item C-x n d | |
2138 | Narrow down to the current defun (@code{narrow-to-defun}). | |
2139 | @end table | |
2140 | ||
2141 | When you have narrowed down to a part of the buffer, that part appears | |
2142 | to be all there is. You can't see the rest, you can't move into it | |
2143 | (motion commands won't go outside the accessible part), you can't change | |
2144 | it in any way. However, it is not gone, and if you save the file all | |
2145 | the inaccessible text will be saved. The word @samp{Narrow} appears in | |
2146 | the mode line whenever narrowing is in effect. | |
2147 | ||
2148 | @kindex C-x n n | |
2149 | @findex narrow-to-region | |
2150 | The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). | |
2151 | It sets the current buffer's restrictions so that the text in the current | |
021037cb EZ |
2152 | region remains accessible, but all text before the region or after the |
2153 | region is inaccessible. Point and mark do not change. | |
6bf7aab6 DL |
2154 | |
2155 | @kindex C-x n p | |
2156 | @findex narrow-to-page | |
2157 | @kindex C-x n d | |
2158 | @findex narrow-to-defun | |
2159 | Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow | |
2160 | down to the current page. @xref{Pages}, for the definition of a page. | |
2161 | @kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun | |
2162 | containing point (@pxref{Defuns}). | |
2163 | ||
2164 | @kindex C-x n w | |
2165 | @findex widen | |
2166 | The way to cancel narrowing is to widen with @kbd{C-x n w} | |
2167 | (@code{widen}). This makes all text in the buffer accessible again. | |
2168 | ||
2169 | You can get information on what part of the buffer you are narrowed down | |
2170 | to using the @kbd{C-x =} command. @xref{Position Info}. | |
2171 | ||
2172 | Because narrowing can easily confuse users who do not understand it, | |
2173 | @code{narrow-to-region} is normally a disabled command. Attempting to use | |
2174 | this command asks for confirmation and gives you the option of enabling it; | |
2175 | if you enable the command, confirmation will no longer be required for | |
2176 | it. @xref{Disabling}. | |
2177 | ||
379e8670 | 2178 | @node Two-Column, Editing Binary Files, Narrowing, Top |
6bf7aab6 DL |
2179 | @section Two-Column Editing |
2180 | @cindex two-column editing | |
2181 | @cindex splitting columns | |
2182 | @cindex columns, splitting | |
2183 | ||
2184 | Two-column mode lets you conveniently edit two side-by-side columns of | |
2185 | text. It uses two side-by-side windows, each showing its own | |
2186 | buffer. | |
2187 | ||
2188 | There are three ways to enter two-column mode: | |
2189 | ||
2190 | @table @asis | |
2191 | @item @kbd{@key{F2} 2} or @kbd{C-x 6 2} | |
2192 | @kindex F2 2 | |
2193 | @kindex C-x 6 2 | |
2194 | @findex 2C-two-columns | |
2195 | Enter two-column mode with the current buffer on the left, and on the | |
2196 | right, a buffer whose name is based on the current buffer's name | |
2197 | (@code{2C-two-columns}). If the right-hand buffer doesn't already | |
2198 | exist, it starts out empty; the current buffer's contents are not | |
2199 | changed. | |
2200 | ||
2201 | This command is appropriate when the current buffer is empty or contains | |
2202 | just one column and you want to add another column. | |
2203 | ||
2204 | @item @kbd{@key{F2} s} or @kbd{C-x 6 s} | |
2205 | @kindex F2 s | |
2206 | @kindex C-x 6 s | |
2207 | @findex 2C-split | |
2208 | Split the current buffer, which contains two-column text, into two | |
2209 | buffers, and display them side by side (@code{2C-split}). The current | |
2210 | buffer becomes the left-hand buffer, but the text in the right-hand | |
2211 | column is moved into the right-hand buffer. The current column | |
2212 | specifies the split point. Splitting starts with the current line and | |
2213 | continues to the end of the buffer. | |
2214 | ||
2215 | This command is appropriate when you have a buffer that already contains | |
2216 | two-column text, and you wish to separate the columns temporarily. | |
2217 | ||
2218 | @item @kbd{@key{F2} b @var{buffer} @key{RET}} | |
2219 | @itemx @kbd{C-x 6 b @var{buffer} @key{RET}} | |
2220 | @kindex F2 b | |
2221 | @kindex C-x 6 b | |
2222 | @findex 2C-associate-buffer | |
2223 | Enter two-column mode using the current buffer as the left-hand buffer, | |
2224 | and using buffer @var{buffer} as the right-hand buffer | |
2225 | (@code{2C-associate-buffer}). | |
2226 | @end table | |
2227 | ||
2228 | @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which | |
2229 | is a string that appears on each line between the two columns. You can | |
2230 | specify the width of the separator with a numeric argument to | |
2231 | @kbd{@key{F2} s}; that many characters, before point, constitute the | |
2232 | separator string. By default, the width is 1, so the column separator | |
2233 | is the character before point. | |
2234 | ||
2235 | When a line has the separator at the proper place, @kbd{@key{F2} s} | |
2236 | puts the text after the separator into the right-hand buffer, and | |
2237 | deletes the separator. Lines that don't have the column separator at | |
2238 | the proper place remain unsplit; they stay in the left-hand buffer, and | |
2239 | the right-hand buffer gets an empty line to correspond. (This is the | |
2240 | way to write a line that ``spans both columns while in two-column | |
2241 | mode'': write it in the left-hand buffer, and put an empty line in the | |
2242 | right-hand buffer.) | |
2243 | ||
2244 | @kindex F2 RET | |
2245 | @kindex C-x 6 RET | |
2246 | @findex 2C-newline | |
2247 | The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} | |
2248 | (@code{2C-newline}) inserts a newline in each of the two buffers at | |
2249 | corresponding positions. This is the easiest way to add a new line to | |
2250 | the two-column text while editing it in split buffers. | |
2251 | ||
2252 | @kindex F2 1 | |
2253 | @kindex C-x 6 1 | |
2254 | @findex 2C-merge | |
2255 | When you have edited both buffers as you wish, merge them with | |
2256 | @kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the | |
2257 | text from the right-hand buffer as a second column in the other buffer. | |
2258 | To go back to two-column editing, use @kbd{@key{F2} s}. | |
2259 | ||
2260 | @kindex F2 d | |
2261 | @kindex C-x 6 d | |
2262 | @findex 2C-dissociate | |
2263 | Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, | |
2264 | leaving each as it stands (@code{2C-dissociate}). If the other buffer, | |
2265 | the one not current when you type @kbd{@key{F2} d}, is empty, | |
2266 | @kbd{@key{F2} d} kills it. | |
2267 | ||
2268 | @node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top | |
2269 | @section Editing Binary Files | |
2270 | ||
2271 | @cindex Hexl mode | |
2272 | @cindex mode, Hexl | |
2273 | @cindex editing binary files | |
c965d0ac | 2274 | @cindex hex editing |
6bf7aab6 DL |
2275 | There is a special major mode for editing binary files: Hexl mode. To |
2276 | use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit | |
2277 | the file. This command converts the file's contents to hexadecimal and | |
2278 | lets you edit the translation. When you save the file, it is converted | |
2279 | automatically back to binary. | |
2280 | ||
2281 | You can also use @kbd{M-x hexl-mode} to translate an existing buffer | |
2282 | into hex. This is useful if you visit a file normally and then discover | |
2283 | it is a binary file. | |
2284 | ||
2285 | Ordinary text characters overwrite in Hexl mode. This is to reduce | |
2286 | the risk of accidentally spoiling the alignment of data in the file. | |
2287 | There are special commands for insertion. Here is a list of the | |
2288 | commands of Hexl mode: | |
2289 | ||
2290 | @c I don't think individual index entries for these commands are useful--RMS. | |
2291 | @table @kbd | |
2292 | @item C-M-d | |
2293 | Insert a byte with a code typed in decimal. | |
2294 | ||
2295 | @item C-M-o | |
2296 | Insert a byte with a code typed in octal. | |
2297 | ||
2298 | @item C-M-x | |
2299 | Insert a byte with a code typed in hex. | |
2300 | ||
2301 | @item C-x [ | |
2302 | Move to the beginning of a 1k-byte ``page.'' | |
2303 | ||
2304 | @item C-x ] | |
2305 | Move to the end of a 1k-byte ``page.'' | |
2306 | ||
2307 | @item M-g | |
2308 | Move to an address specified in hex. | |
2309 | ||
2310 | @item M-j | |
2311 | Move to an address specified in decimal. | |
2312 | ||
2313 | @item C-c C-c | |
2314 | Leave Hexl mode, going back to the major mode this buffer had before you | |
2315 | invoked @code{hexl-mode}. | |
2316 | @end table | |
2317 | ||
c965d0ac | 2318 | @noindent |
fc98b4ba | 2319 | Other Hexl commands let you insert strings (sequences) of binary |
021037cb EZ |
2320 | bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a |
2321 | hexl-@key{RET}} for details. | |
c965d0ac EZ |
2322 | |
2323 | ||
6bf7aab6 DL |
2324 | @node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top |
2325 | @section Saving Emacs Sessions | |
2326 | @cindex saving sessions | |
24cd2514 EZ |
2327 | @cindex restore session |
2328 | @cindex remember editing session | |
2329 | @cindex reload files | |
6bf7aab6 DL |
2330 | @cindex desktop |
2331 | ||
6a51fedc RS |
2332 | Use the desktop library to save the state of Emacs from one session |
2333 | to another. Once you save the Emacs @dfn{desktop}---the buffers, | |
2334 | their file names, major modes, buffer positions, and so on---then | |
2335 | subsequent Emacs sessions reload the saved desktop. | |
6bf7aab6 | 2336 | |
6a51fedc | 2337 | @findex desktop-save |
080e83d1 | 2338 | @vindex desktop-save-mode |
6a51fedc | 2339 | You can save the desktop manually with the command @kbd{M-x |
1096b4a0 RS |
2340 | desktop-save}. You can also enable automatic saving of the desktop |
2341 | when you exit Emacs, and automatic restoration of the last saved | |
2342 | desktop when Emacs starts: use the Customization buffer (@pxref{Easy | |
2343 | Customization}) to set @code{desktop-save-mode} to @code{t} for future | |
932fd020 | 2344 | sessions, or add this line in your init file (@pxref{Init File}): |
6bf7aab6 DL |
2345 | |
2346 | @example | |
080e83d1 | 2347 | (desktop-save-mode 1) |
6bf7aab6 DL |
2348 | @end example |
2349 | ||
080e83d1 LH |
2350 | @findex desktop-change-dir |
2351 | @findex desktop-revert | |
e4a0188a | 2352 | @vindex desktop-path |
932fd020 CY |
2353 | If you turn on @code{desktop-save-mode} in your init file, then when |
2354 | Emacs starts, it looks for a saved desktop in the current directory. | |
e4a0188a GM |
2355 | (More precisely, it looks in the directories specified by |
2356 | @var{desktop-path}, and uses the first desktop it finds.) | |
932fd020 CY |
2357 | Thus, you can have separate saved desktops in different directories, |
2358 | and the starting directory determines which one Emacs reloads. You | |
2359 | can save the current desktop and reload one saved in another directory | |
2360 | by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x | |
2361 | desktop-revert} reverts to the desktop previously reloaded. | |
080e83d1 | 2362 | |
6a51fedc | 2363 | Specify the option @samp{--no-desktop} on the command line when you |
b9ed2fa6 | 2364 | don't want it to reload any saved desktop. This turns off |
5bfef96c EZ |
2365 | @code{desktop-save-mode} for the current session. Starting Emacs with |
2366 | the @samp{--no-init-file} option also disables desktop reloading, | |
932fd020 CY |
2367 | since it bypasses the init file, where @code{desktop-save-mode} is |
2368 | usually turned on. | |
6bf7aab6 | 2369 | |
a3f7375f RS |
2370 | @vindex desktop-restore-eager |
2371 | By default, all the buffers in the desktop are restored at one go. | |
2372 | However, this may be slow if there are a lot of buffers in the | |
2373 | desktop. You can specify the maximum number of buffers to restore | |
2374 | immediately with the variable @code{desktop-restore-eager}; the | |
2375 | remaining buffers are restored ``lazily,'' when Emacs is idle. | |
2376 | ||
080e83d1 | 2377 | @findex desktop-clear |
080e83d1 LH |
2378 | @vindex desktop-globals-to-clear |
2379 | @vindex desktop-clear-preserve-buffers-regexp | |
6a51fedc RS |
2380 | Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills |
2381 | all buffers except for internal ones, and clears the global variables | |
2382 | listed in @code{desktop-globals-to-clear}. If you want this to | |
080e83d1 | 2383 | preserve certain buffers, customize the variable |
6a51fedc RS |
2384 | @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular |
2385 | expression matching the names of buffers not to kill. | |
17a4f5ec | 2386 | |
89b5d9ab RS |
2387 | If you want to save minibuffer history from one session to |
2388 | another, use the @code{savehist} library. | |
2389 | ||
6bf7aab6 DL |
2390 | @node Recursive Edit, Emulation, Saving Emacs Sessions, Top |
2391 | @section Recursive Editing Levels | |
2392 | @cindex recursive editing level | |
2393 | @cindex editing level, recursive | |
2394 | ||
2395 | A @dfn{recursive edit} is a situation in which you are using Emacs | |
2396 | commands to perform arbitrary editing while in the middle of another | |
2397 | Emacs command. For example, when you type @kbd{C-r} inside of a | |
2398 | @code{query-replace}, you enter a recursive edit in which you can change | |
2399 | the current buffer. On exiting from the recursive edit, you go back to | |
2400 | the @code{query-replace}. | |
2401 | ||
2402 | @kindex C-M-c | |
2403 | @findex exit-recursive-edit | |
2404 | @cindex exiting recursive edit | |
2405 | @dfn{Exiting} the recursive edit means returning to the unfinished | |
2406 | command, which continues execution. The command to exit is @kbd{C-M-c} | |
2407 | (@code{exit-recursive-edit}). | |
2408 | ||
2409 | You can also @dfn{abort} the recursive edit. This is like exiting, | |
2410 | but also quits the unfinished command immediately. Use the command | |
2411 | @kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. | |
2412 | ||
2413 | The mode line shows you when you are in a recursive edit by displaying | |
2414 | square brackets around the parentheses that always surround the major and | |
021037cb | 2415 | minor mode names. Every window's mode line shows this in the same way, |
6bf7aab6 DL |
2416 | since being in a recursive edit is true of Emacs as a whole rather than |
2417 | any particular window or buffer. | |
2418 | ||
2419 | It is possible to be in recursive edits within recursive edits. For | |
2420 | example, after typing @kbd{C-r} in a @code{query-replace}, you may type a | |
2421 | command that enters the debugger. This begins a recursive editing level | |
2422 | for the debugger, within the recursive editing level for @kbd{C-r}. | |
2423 | Mode lines display a pair of square brackets for each recursive editing | |
2424 | level currently in progress. | |
2425 | ||
982dcb1b | 2426 | Exiting the inner recursive edit (such as with the debugger @kbd{c} |
6bf7aab6 DL |
2427 | command) resumes the command running in the next level up. When that |
2428 | command finishes, you can then use @kbd{C-M-c} to exit another recursive | |
2429 | editing level, and so on. Exiting applies to the innermost level only. | |
2430 | Aborting also gets out of only one level of recursive edit; it returns | |
2431 | immediately to the command level of the previous recursive edit. If you | |
2432 | wish, you can then abort the next recursive editing level. | |
2433 | ||
2434 | Alternatively, the command @kbd{M-x top-level} aborts all levels of | |
25ed034e CY |
2435 | recursive edits, returning immediately to the top-level command |
2436 | reader. It also exits the minibuffer, if it is active. | |
6bf7aab6 DL |
2437 | |
2438 | The text being edited inside the recursive edit need not be the same text | |
2439 | that you were editing at top level. It depends on what the recursive edit | |
2440 | is for. If the command that invokes the recursive edit selects a different | |
2441 | buffer first, that is the buffer you will edit recursively. In any case, | |
2442 | you can switch buffers within the recursive edit in the normal manner (as | |
2443 | long as the buffer-switching keys have not been rebound). You could | |
2444 | probably do all the rest of your editing inside the recursive edit, | |
2445 | visiting files and all. But this could have surprising effects (such as | |
2446 | stack overflow) from time to time. So remember to exit or abort the | |
2447 | recursive edit when you no longer need it. | |
2448 | ||
2449 | In general, we try to minimize the use of recursive editing levels in | |
2450 | GNU Emacs. This is because they constrain you to ``go back'' in a | |
2451 | particular order---from the innermost level toward the top level. When | |
2452 | possible, we present different activities in separate buffers so that | |
2453 | you can switch between them as you please. Some commands switch to a | |
2454 | new major mode which provides a command to switch back. These | |
2455 | approaches give you more flexibility to go back to unfinished tasks in | |
2456 | the order you choose. | |
2457 | ||
3f724e9a | 2458 | @node Emulation, Hyperlinking, Recursive Edit, Top |
6bf7aab6 DL |
2459 | @section Emulation |
2460 | @cindex emulating other editors | |
2461 | @cindex other editors | |
2462 | @cindex EDT | |
2463 | @cindex vi | |
d0960fb3 | 2464 | @cindex PC key bindings |
3b65ce47 | 2465 | @cindex scrolling all windows |
d0960fb3 RS |
2466 | @cindex PC selection |
2467 | @cindex Motif key bindings | |
2468 | @cindex Macintosh key bindings | |
3b65ce47 | 2469 | @cindex WordStar |
6bf7aab6 DL |
2470 | |
2471 | GNU Emacs can be programmed to emulate (more or less) most other | |
2472 | editors. Standard facilities can emulate these: | |
2473 | ||
2474 | @table @asis | |
3b65ce47 DL |
2475 | @item CRiSP/Brief (PC editor) |
2476 | @findex crisp-mode | |
2477 | @vindex crisp-override-meta-x | |
2478 | @findex scroll-all-mode | |
b1a92ebf DL |
2479 | @cindex CRiSP mode |
2480 | @cindex Brief emulation | |
4946337d | 2481 | @cindex emulation of Brief |
b1a92ebf | 2482 | @cindex mode, CRiSP |
d0960fb3 | 2483 | You can turn on key bindings to emulate the CRiSP/Brief editor with |
b1a92ebf | 2484 | @kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs |
19b2c4ca RS |
2485 | unless you set the variable @code{crisp-override-meta-x}. You can |
2486 | also use the command @kbd{M-x scroll-all-mode} or set the variable | |
b1a92ebf DL |
2487 | @code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature |
2488 | (scrolling all windows together). | |
3b65ce47 | 2489 | |
6bf7aab6 DL |
2490 | @item EDT (DEC VMS editor) |
2491 | @findex edt-emulation-on | |
2492 | @findex edt-emulation-off | |
df7593dd KB |
2493 | Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, |
2494 | while @kbd{M-x edt-emulation-off} restores normal Emacs command | |
2495 | bindings. | |
6bf7aab6 DL |
2496 | |
2497 | Most of the EDT emulation commands are keypad keys, and most standard | |
2498 | Emacs key bindings are still available. The EDT emulation rebindings | |
2499 | are done in the global keymap, so there is no problem switching | |
2500 | buffers or major modes while in EDT emulation. | |
2501 | ||
3f724e9a DL |
2502 | @item TPU (DEC VMS editor) |
2503 | @findex tpu-edt-on | |
2504 | @cindex TPU | |
2505 | @kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. | |
2506 | ||
6bf7aab6 DL |
2507 | @item vi (Berkeley editor) |
2508 | @findex viper-mode | |
2509 | Viper is the newest emulator for vi. It implements several levels of | |
2510 | emulation; level 1 is closest to vi itself, while level 5 departs | |
2511 | somewhat from strict emulation to take advantage of the capabilities of | |
2512 | Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you | |
2513 | the rest of the way and ask for the emulation level. @inforef{Top, | |
2514 | Viper, viper}. | |
2515 | ||
2516 | @item vi (another emulator) | |
2517 | @findex vi-mode | |
2518 | @kbd{M-x vi-mode} enters a major mode that replaces the previously | |
2519 | established major mode. All of the vi commands that, in real vi, enter | |
2520 | ``input'' mode are programmed instead to return to the previous major | |
2521 | mode. Thus, ordinary Emacs serves as vi's ``input'' mode. | |
2522 | ||
2523 | Because vi emulation works through major modes, it does not work | |
2524 | to switch buffers during emulation. Return to normal Emacs first. | |
2525 | ||
2526 | If you plan to use vi emulation much, you probably want to bind a key | |
2527 | to the @code{vi-mode} command. | |
2528 | ||
2529 | @item vi (alternate emulator) | |
2530 | @findex vip-mode | |
2531 | @kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi | |
2532 | more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator | |
2533 | is changed from ordinary Emacs so you can use @key{ESC} to go back to | |
2534 | emulated vi command mode. To get from emulated vi command mode back to | |
2535 | ordinary Emacs, type @kbd{C-z}. | |
2536 | ||
2537 | This emulation does not work through major modes, and it is possible | |
2538 | to switch buffers in various ways within the emulator. It is not | |
2539 | so necessary to assign a key to the command @code{vip-mode} as | |
2540 | it is with @code{vi-mode} because terminating insert mode does | |
2541 | not use it. | |
2542 | ||
2543 | @inforef{Top, VIP, vip}, for full information. | |
3b65ce47 DL |
2544 | |
2545 | @item WordStar (old wordprocessor) | |
2546 | @findex wordstar-mode | |
2547 | @kbd{M-x wordstar-mode} provides a major mode with WordStar-like | |
d0960fb3 | 2548 | key bindings. |
6bf7aab6 DL |
2549 | @end table |
2550 | ||
8e5220ef | 2551 | @node Hyperlinking, Dissociated Press, Emulation, Top |
3f724e9a DL |
2552 | @section Hyperlinking and Navigation Features |
2553 | ||
2554 | @cindex hyperlinking | |
3f724e9a | 2555 | @cindex navigation |
df9d7630 RS |
2556 | Various modes documented elsewhere have hypertext features so that |
2557 | you can follow links, usually by clicking @kbd{Mouse-2} on the link or | |
982dcb1b RS |
2558 | typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1} |
2559 | quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer | |
2560 | if you want to set point instead.) | |
2561 | ||
2562 | Info mode, Help mode and the Dired-like modes are examples of modes | |
2563 | that have links in the buffer. The Tags facility links between uses | |
2564 | and definitions in source files, see @ref{Tags}. Imenu provides | |
df9d7630 RS |
2565 | navigation amongst items indexed in the current buffer, see |
2566 | @ref{Imenu}. Info-lookup provides mode-specific lookup of definitions | |
2567 | in Info indexes, see @ref{Documentation}. Speedbar maintains a frame | |
2568 | in which links to files, and locations in files are displayed, see | |
2569 | @ref{Speedbar}. | |
2570 | ||
2571 | Other non-mode-specific facilities described in this section enable | |
2572 | following links from the current buffer in a context-sensitive | |
2573 | fashion. | |
3f724e9a | 2574 | |
b1a92ebf DL |
2575 | @menu |
2576 | * Browse-URL:: Following URLs. | |
39791e03 | 2577 | * Goto Address mode:: Activating URLs. |
b1a92ebf | 2578 | * FFAP:: Finding files etc. at point. |
b1a92ebf DL |
2579 | @end menu |
2580 | ||
2581 | @node Browse-URL | |
2582 | @subsection Following URLs | |
3f724e9a | 2583 | @cindex World Wide Web |
b1a92ebf | 2584 | @cindex Web |
3f724e9a DL |
2585 | @findex browse-url |
2586 | @findex browse-url-at-point | |
2587 | @findex browse-url-at-mouse | |
3f724e9a DL |
2588 | @cindex Browse-URL |
2589 | @cindex URLs | |
b1a92ebf DL |
2590 | |
2591 | @table @kbd | |
fc98b4ba | 2592 | @item M-x browse-url @key{RET} @var{url} @key{RET} |
b1a92ebf DL |
2593 | Load a URL into a Web browser. |
2594 | @end table | |
2595 | ||
3f724e9a DL |
2596 | The Browse-URL package provides facilities for following URLs specifying |
2597 | links on the World Wide Web. Usually this works by invoking a web | |
df9d7630 RS |
2598 | browser, but you can, for instance, arrange to invoke @code{compose-mail} |
2599 | from @samp{mailto:} URLs. | |
2600 | ||
2601 | The general way to use this feature is to type @kbd{M-x browse-url}, | |
2602 | which displays a specified URL. If point is located near a plausible | |
2603 | URL, that URL is used as the default. Other commands are available | |
2604 | which you might like to bind to keys, such as | |
b1a92ebf | 2605 | @code{browse-url-at-point} and @code{browse-url-at-mouse}. |
3f724e9a | 2606 | |
b1a92ebf | 2607 | @vindex browse-url-browser-function |
39cf6a8d | 2608 | You can customize Browse-URL's behavior via various options in the |
b1a92ebf | 2609 | @code{browse-url} Customize group, particularly |
df9d7630 RS |
2610 | @code{browse-url-browser-function}. You can invoke actions dependent |
2611 | on the type of URL by defining @code{browse-url-browser-function} as | |
2612 | an association list. The package's commentary available via @kbd{C-h | |
23c9ed48 JL |
2613 | p} under the @samp{hypermedia} keyword provides more information. |
2614 | Packages with facilities for following URLs should always go through | |
2615 | Browse-URL, so that the customization options for Browse-URL will | |
2616 | affect all browsing in Emacs. | |
3f724e9a | 2617 | |
39791e03 | 2618 | @node Goto Address mode |
b1a92ebf | 2619 | @subsection Activating URLs |
39791e03 CY |
2620 | @findex goto-address-mode |
2621 | @cindex Goto Address mode | |
3f724e9a | 2622 | @cindex URLs, activating |
b1a92ebf DL |
2623 | |
2624 | @table @kbd | |
39791e03 | 2625 | @item M-x goto-address-mode |
b1a92ebf DL |
2626 | Activate URLs and e-mail addresses in the current buffer. |
2627 | @end table | |
2628 | ||
df9d7630 | 2629 | You can make URLs in the current buffer active with @kbd{M-x |
39791e03 CY |
2630 | goto-address-mode}. This minor mode finds all the URLs in the buffer, |
2631 | highlights them, and turns them into @dfn{buttons}: if you click on a | |
2632 | URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or | |
2633 | move to the URL and type @kbd{C-c @key{RET}}, that displays the web | |
2634 | page that the URL specifies. For a @samp{mailto} URL, it sends mail | |
2635 | instead, using your selected mail-composition method (@pxref{Mail | |
2636 | Methods}). | |
2637 | ||
2638 | It can be useful to add @code{goto-address-mode} to mode hooks and | |
2639 | the hooks used to display an incoming message (e.g., | |
2640 | @code{rmail-show-message-hook} for Rmail, and @code{mh-show-mode-hook} | |
2641 | for MH-E). This is not needed for Gnus, which has a similar feature | |
2642 | of its own. | |
3f724e9a | 2643 | |
b1a92ebf DL |
2644 | @node FFAP |
2645 | @subsection Finding Files and URLs at Point | |
3f724e9a DL |
2646 | @findex find-file-at-point |
2647 | @findex ffap | |
37ed0ee5 | 2648 | @findex dired-at-point |
b1a92ebf DL |
2649 | @findex ffap-next |
2650 | @findex ffap-menu | |
b1a92ebf DL |
2651 | @cindex finding file at point |
2652 | ||
df9d7630 RS |
2653 | FFAP mode replaces certain key bindings for finding files, including |
2654 | @kbd{C-x C-f}, with commands that provide more sensitive defaults. | |
2655 | These commands behave like the ordinary ones when given a prefix | |
2656 | argument. Otherwise, they get the default file name or URL from the | |
2657 | text around point. If what is found in the buffer has the form of a | |
2658 | URL rather than a file name, the commands use @code{browse-url} to | |
2659 | view it. | |
b1a92ebf | 2660 | |
df9d7630 RS |
2661 | This feature is useful for following references in mail or news |
2662 | buffers, @file{README} files, @file{MANIFEST} files, and so on. The | |
23c9ed48 JL |
2663 | @samp{ffap} package's commentary available via @kbd{C-h p} under the |
2664 | @samp{files} keyword and the @code{ffap} Custom group provide details. | |
b1a92ebf DL |
2665 | |
2666 | @cindex FFAP minor mode | |
2667 | @findex ffap-mode | |
23c9ed48 JL |
2668 | You can turn on FFAP minor mode by calling @code{ffap-bindings} to |
2669 | make the following key bindings and to install hooks for using | |
2670 | @code{ffap} in Rmail, Gnus and VM article buffers. | |
b1a92ebf DL |
2671 | |
2672 | @table @kbd | |
df9d7630 | 2673 | @item C-x C-f @var{filename} @key{RET} |
b1a92ebf | 2674 | @kindex C-x C-f @r{(FFAP)} |
df9d7630 RS |
2675 | Find @var{filename}, guessing a default from text around point |
2676 | (@code{find-file-at-point}). | |
b79529b7 JL |
2677 | @item C-x C-r |
2678 | @kindex C-x C-r @r{(FFAP)} | |
2679 | @code{ffap-read-only}, analogous to @code{find-file-read-only}. | |
2680 | @item C-x C-v | |
2681 | @kindex C-x C-v @r{(FFAP)} | |
2682 | @code{ffap-alternate-file}, analogous to @code{find-alternate-file}. | |
2683 | @item C-x d @var{directory} @key{RET} | |
2684 | @kindex C-x d @r{(FFAP)} | |
2685 | Start Dired on @var{directory}, defaulting to the directory name at | |
37ed0ee5 | 2686 | point (@code{dired-at-point}). |
b79529b7 JL |
2687 | @item C-x C-d |
2688 | @code{ffap-list-directory}, analogous to @code{list-directory}. | |
b1a92ebf DL |
2689 | @item C-x 4 f |
2690 | @kindex C-x 4 f @r{(FFAP)} | |
df9d7630 | 2691 | @code{ffap-other-window}, analogous to @code{find-file-other-window}. |
b79529b7 JL |
2692 | @item C-x 4 r |
2693 | @code{ffap-read-only-other-window}, analogous to | |
2694 | @code{find-file-read-only-other-window}. | |
2695 | @item C-x 4 d | |
2696 | @code{ffap-dired-other-window}, analogous to @code{dired-other-window}. | |
b1a92ebf DL |
2697 | @item C-x 5 f |
2698 | @kindex C-x 5 f @r{(FFAP)} | |
df9d7630 | 2699 | @code{ffap-other-frame}, analogous to @code{find-file-other-frame}. |
b79529b7 JL |
2700 | @item C-x 5 r |
2701 | @code{ffap-read-only-other-frame}, analogous to | |
2702 | @code{find-file-read-only-other-frame}. | |
2703 | @item C-x 5 d | |
2704 | @code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. | |
df9d7630 RS |
2705 | @item M-x ffap-next |
2706 | Search buffer for next file name or URL, then find that file or URL. | |
df9d7630 RS |
2707 | @item S-Mouse-3 |
2708 | @kindex S-Mouse-3 @r{(FFAP)} | |
b1a92ebf | 2709 | @code{ffap-at-mouse} finds the file guessed from text around the position |
df9d7630 RS |
2710 | of a mouse click. |
2711 | @item C-S-Mouse-3 | |
2712 | @kindex C-S-Mouse-3 @r{(FFAP)} | |
2713 | Display a menu of files and URLs mentioned in current buffer, then | |
2714 | find the one you select (@code{ffap-menu}). | |
b1a92ebf DL |
2715 | @end table |
2716 | ||
8e5220ef | 2717 | @node Dissociated Press, Amusements, Hyperlinking, Top |
6bf7aab6 DL |
2718 | @section Dissociated Press |
2719 | ||
2720 | @findex dissociated-press | |
2721 | @kbd{M-x dissociated-press} is a command for scrambling a file of text | |
2722 | either word by word or character by character. Starting from a buffer of | |
2723 | straight English, it produces extremely amusing output. The input comes | |
2724 | from the current Emacs buffer. Dissociated Press writes its output in a | |
2725 | buffer named @samp{*Dissociation*}, and redisplays that buffer after every | |
2726 | couple of lines (approximately) so you can read the output as it comes out. | |
2727 | ||
2728 | Dissociated Press asks every so often whether to continue generating | |
2729 | output. Answer @kbd{n} to stop it. You can also stop at any time by | |
2730 | typing @kbd{C-g}. The dissociation output remains in the | |
2731 | @samp{*Dissociation*} buffer for you to copy elsewhere if you wish. | |
2732 | ||
2733 | @cindex presidentagon | |
890800b1 CY |
2734 | Dissociated Press operates by jumping at random from one point in |
2735 | the buffer to another. In order to produce plausible output rather | |
2736 | than gibberish, it insists on a certain amount of overlap between the | |
2737 | end of one run of consecutive words or characters and the start of the | |
2738 | next. That is, if it has just output `president' and then decides to | |
2739 | jump to a different point in the buffer, it might spot the `ent' in | |
2740 | `pentagon' and continue from there, producing `presidentagon'. Long | |
2741 | sample texts produce the best results. | |
6bf7aab6 DL |
2742 | |
2743 | @cindex againformation | |
2744 | A positive argument to @kbd{M-x dissociated-press} tells it to operate | |
2745 | character by character, and specifies the number of overlap characters. A | |
ab192107 | 2746 | negative argument tells it to operate word by word, and specifies the number |
6bf7aab6 DL |
2747 | of overlap words. In this mode, whole words are treated as the elements to |
2748 | be permuted, rather than characters. No argument is equivalent to an | |
2749 | argument of two. For your againformation, the output goes only into the | |
2750 | buffer @samp{*Dissociation*}. The buffer you start with is not changed. | |
2751 | ||
2752 | @cindex Markov chain | |
2753 | @cindex ignoriginal | |
2754 | @cindex techniquitous | |
ab192107 RS |
2755 | Dissociated Press produces results fairly like those of a Markov |
2756 | chain based on a frequency table constructed from the sample text. It | |
2757 | is, however, an independent, ignoriginal invention. Dissociated Press | |
6bf7aab6 | 2758 | techniquitously copies several consecutive characters from the sample |
43b978db RS |
2759 | text between random jumps, unlike a Markov chain which would jump |
2760 | randomly after each word or character. This makes for more plausible | |
2761 | sounding results, and runs faster. | |
6bf7aab6 DL |
2762 | |
2763 | @cindex outragedy | |
2764 | @cindex buggestion | |
2765 | @cindex properbose | |
2766 | @cindex mustatement | |
2767 | @cindex developediment | |
2768 | @cindex userenced | |
2769 | It is a mustatement that too much use of Dissociated Press can be a | |
ab192107 | 2770 | developediment to your real work, sometimes to the point of outragedy. |
6bf7aab6 DL |
2771 | And keep dissociwords out of your documentation, if you want it to be well |
2772 | userenced and properbose. Have fun. Your buggestions are welcome. | |
2773 | ||
2774 | @node Amusements, Customization, Dissociated Press, Top | |
2775 | @section Other Amusements | |
2776 | @cindex boredom | |
2777 | @findex hanoi | |
2778 | @findex yow | |
2779 | @findex gomoku | |
6bf7aab6 DL |
2780 | @cindex tower of Hanoi |
2781 | ||
2782 | If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are | |
ffe4b4e3 | 2783 | considerably bored, give it a numeric argument. If you are very, very |
6bf7aab6 DL |
2784 | bored, try an argument of 9. Sit back and watch. |
2785 | ||
2786 | @cindex Go Moku | |
2787 | If you want a little more personal involvement, try @kbd{M-x gomoku}, | |
2788 | which plays the game Go Moku with you. | |
2789 | ||
50dd7bc6 GM |
2790 | @findex bubbles |
2791 | @kbd{M-x bubbles} is a game in which the object is to remove as many | |
2792 | bubbles as you can in the smallest number of moves. | |
2793 | ||
6bf7aab6 DL |
2794 | @findex blackbox |
2795 | @findex mpuz | |
3b65ce47 | 2796 | @findex 5x5 |
6bf7aab6 | 2797 | @cindex puzzles |
ab192107 | 2798 | @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. |
6bf7aab6 DL |
2799 | @code{blackbox} challenges you to determine the location of objects |
2800 | inside a box by tomography. @code{mpuz} displays a multiplication | |
2801 | puzzle with letters standing for digits in a code that you must | |
2802 | guess---to guess a value, type a letter and then the digit you think it | |
3b65ce47 | 2803 | stands for. The aim of @code{5x5} is to fill in all the squares. |
6bf7aab6 | 2804 | |
b1a92ebf DL |
2805 | @findex decipher |
2806 | @cindex ciphers | |
2807 | @cindex cryptanalysis | |
2808 | @kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted | |
2809 | in a simple monoalphabetic substitution cipher. | |
2810 | ||
6bf7aab6 DL |
2811 | @findex dunnet |
2812 | @kbd{M-x dunnet} runs an adventure-style exploration game, which is | |
2813 | a bigger sort of puzzle. | |
2814 | ||
3b65ce47 DL |
2815 | @findex lm |
2816 | @cindex landmark game | |
2817 | @kbd{M-x lm} runs a relatively non-participatory game in which a robot | |
2818 | attempts to maneuver towards a tree at the center of the window based on | |
2819 | unique olfactory cues from each of the four directions. | |
2820 | ||
2821 | @findex life | |
2822 | @cindex Life | |
2684ed46 | 2823 | @kbd{M-x life} runs Conway's ``Life'' cellular automaton. |
3b65ce47 | 2824 | |
b1a92ebf DL |
2825 | @findex morse-region |
2826 | @findex unmorse-region | |
2827 | @cindex Morse code | |
2828 | @cindex --/---/.-./.../. | |
2829 | @kbd{M-x morse-region} converts text in a region to Morse code and | |
2830 | @kbd{M-x unmorse-region} converts it back. No cause for remorse. | |
2831 | ||
2832 | @findex pong | |
2833 | @cindex Pong game | |
df9d7630 RS |
2834 | @kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing |
2835 | bats. | |
b1a92ebf | 2836 | |
3b65ce47 DL |
2837 | @findex solitaire |
2838 | @cindex solitaire | |
2839 | @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs | |
2840 | across other pegs. | |
2841 | ||
50dd7bc6 GM |
2842 | @findex animate-birthday-present |
2843 | @cindex animate | |
2844 | The @code{animate} package makes text dance. For an example, try | |
2845 | @kbd{M-x animate-birthday-present}. | |
2846 | ||
b1a92ebf DL |
2847 | @findex studlify-region |
2848 | @cindex StudlyCaps | |
df9d7630 RS |
2849 | @kbd{M-x studlify-region} studlify-cases the region, producing |
2850 | text like this: | |
b1a92ebf DL |
2851 | |
2852 | @example | |
2853 | M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region. | |
2854 | @end example | |
2855 | ||
3b65ce47 DL |
2856 | @findex tetris |
2857 | @cindex Tetris | |
3b65ce47 DL |
2858 | @findex snake |
2859 | @cindex Snake | |
df9d7630 | 2860 | @kbd{M-x tetris} runs an implementation of the well-known Tetris game. |
3b65ce47 DL |
2861 | Likewise, @kbd{M-x snake} provides an implementation of Snake. |
2862 | ||
6bf7aab6 DL |
2863 | When you are frustrated, try the famous Eliza program. Just do |
2864 | @kbd{M-x doctor}. End each input by typing @key{RET} twice. | |
2865 | ||
2866 | @cindex Zippy | |
2867 | When you are feeling strange, type @kbd{M-x yow}. | |
834d56ed DL |
2868 | |
2869 | @findex zone | |
2870 | The command @kbd{M-x zone} plays games with the display when Emacs is | |
2871 | idle. | |
ab5796a9 | 2872 | |
2e7cfad6 LT |
2873 | @ifnottex |
2874 | @lowersections | |
2875 | @end ifnottex | |
2876 | ||
ab5796a9 MB |
2877 | @ignore |
2878 | arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474 | |
2879 | @end ignore |