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