1@c This is part of the Emacs manual. 2@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2021 Free Software 3@c 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 9else: reading Usenet news, host and network security, 10viewing PDFs and other such documents, web 11browsing, running shell commands and shell subprocesses, using a 12single shared Emacs for utilities that expect to run an editor as a 13subprocess, printing, sorting text, editing binary files, saving an 14Emacs session for later resumption, recursive editing level, following 15hyperlinks, and various diversions and amusements. 16 17@end iftex 18 19@ifnottex 20@raisesections 21@end ifnottex 22 23@node Gnus 24@section Email and Usenet News with Gnus 25@cindex Gnus 26@cindex Usenet news 27@cindex newsreader 28 29 Gnus is an Emacs package primarily designed for reading and posting 30Usenet news. It can also be used to read and respond to messages from 31a number of other sources---email, remote directories, digests, and so 32on. Here we introduce Gnus and describe several basic features. 33@ifnottex 34For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. 35@end ifnottex 36@iftex 37For full details on Gnus, type @kbd{C-h i} and then select the Gnus 38manual. 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 52commands. The three most commonly-used Gnus buffers are the 53@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article 54buffer}. 55 56 The @dfn{group buffer} contains a list of article sources (e.g., 57newsgroups and email inboxes), which are collectively referred to as 58@dfn{groups}. This is the first buffer Gnus displays when it starts 59up. It normally displays only the groups to which you subscribe and 60that contain unread articles. From this buffer, you can select a 61group to read. 62 63 The @dfn{summary buffer} lists the articles in a single group, 64showing one article per line. By default, it displays each article's 65author, subject, and line 66@iftex 67number. 68@end iftex 69@ifnottex 70number, but this is customizable; @xref{Summary Buffer Format,,, gnus, 71The Gnus Manual}. 72@end ifnottex 73The summary buffer is created when you select a group in the group 74buffer, and is killed when you exit the group. 75 76 From the summary buffer, you can choose an article to view. The 77article is displayed in the @dfn{article buffer}. In normal Gnus 78usage, you view this buffer but do not select it---all useful Gnus 79commands can be invoked from the summary buffer. But you can select 80the 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 88started with Gnus is easy---just type @kbd{M-x gnus}. 89 90 On starting up, Gnus reads your @dfn{news initialization file}: a 91file named @file{.newsrc} in your home directory which lists your 92Usenet newsgroups and subscriptions (this file is not unique to Gnus; 93it is used by many other newsreader programs). It then tries to 94contact the system's default news server, which is typically specified 95by the @env{NNTPSERVER} environment variable. 96 97 If your system does not have a default news server, or if you wish 98to use Gnus for reading email, then before invoking @kbd{M-x gnus} you 99need to tell Gnus where to get news and/or mail. To do this, 100customize the variables @code{gnus-select-method} and/or 101@code{gnus-secondary-select-methods}. 102@iftex 103See 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, 110the group buffer shows only a small number of @dfn{subscribed groups}. 111Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or 112@dfn{zombie}---are hidden. The first time you start Gnus, any group 113to which you are not subscribed is made into a killed group; any group 114that 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 117summary buffer for that group; then, select an article in the summary 118buffer to view its article buffer in a separate window. The following 119sections 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 122records your group statuses in the files @file{.newsrc} and 123@file{.newsrc.eld}, so that they take effect in subsequent Gnus 124sessions. 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} 135Switch to the summary buffer for the group on the current line 136(@code{gnus-group-read-group}). 137 138@kindex l @r{(Gnus Group mode)} 139@kindex A s @r{(Gnus Group mode)} 140@findex gnus-group-list-groups 141@item l 142@itemx A s 143In the group buffer, list only the groups to which you subscribe and 144which contain unread articles (@code{gnus-group-list-groups}; this is 145the default listing). 146 147@kindex L @r{(Gnus Group mode)} 148@kindex A u @r{(Gnus Group mode)} 149@findex gnus-group-list-all-groups 150@item L 151@itemx A u 152List all subscribed and unsubscribed groups, but not killed or zombie 153groups (@code{gnus-group-list-all-groups}). 154 155@kindex A k @r{(Gnus Group mode)} 156@findex gnus-group-list-killed 157@item A k 158List killed groups (@code{gnus-group-list-killed}). 159 160@kindex A z @r{(Gnus Group mode)} 161@findex gnus-group-list-zombies 162@item A z 163List zombie groups (@code{gnus-group-list-zombies}). 164 165@kindex u @r{(Gnus Group mode)} 166@findex gnus-group-toggle-subscription 167@cindex subscribe groups 168@cindex unsubscribe groups 169@item u 170Toggle the subscription status of the group 171(@code{gnus-group-toggle-subscription}) on the current line. 172Invoking this on a killed or zombie group turns it into an 173unsubscribed group. 174 175@kindex C-k @r{(Gnus Group mode)} 176@findex gnus-group-kill-group 177@item C-k 178Kill the group on the current line (@code{gnus-group-kill-group}). 179Killed groups are not recorded in the @file{.newsrc} file, and they 180are not shown in the @kbd{l} or @kbd{L} listings. 181 182@kindex DEL @r{(Gnus Group mode)} 183@item @key{DEL} 184Move point to the previous group containing unread articles 185(@code{gnus-group-prev-unread-group}). 186 187@kindex n @r{(Gnus Group mode)} 188@findex gnus-group-next-unread-group 189@item n 190Move point to the next unread group 191(@code{gnus-group-next-unread-group}). 192 193@kindex p @r{(Gnus Group mode)} 194@findex gnus-group-prev-unread-group 195@item p 196Move point to the previous unread group 197(@code{gnus-group-prev-unread-group}). 198 199@kindex q @r{(Gnus Group mode)} 200@findex gnus-group-exit 201@item q 202Update your Gnus settings, and quit Gnus (@code{gnus-group-exit}). 203@end table 204 205@node Gnus Summary Buffer 206@subsection Using the Gnus Summary Buffer 207 208 The following commands are available in the Gnus summary buffer: 209 210@table @kbd 211@kindex SPC @r{(Gnus Summary mode)} 212@findex gnus-summary-next-page 213@item @key{SPC} 214If there is no article selected, select the article on the current 215line and display its article buffer. Otherwise, try scrolling the 216selected article buffer in its window; on reaching the end of the 217buffer, select the next unread article (@code{gnus-summary-next-page}). 218 219Thus, you can read through all articles by repeatedly typing 220@key{SPC}. 221 222@kindex DEL @r{(Gnus Summary mode)} 223@findex gnus-summary-prev-page 224@item @key{DEL} 225Scroll the text of the article backwards 226(@code{gnus-summary-prev-page}). 227 228@kindex n @r{(Gnus Summary mode)} 229@findex gnus-summary-next-unread-article 230@item n 231Select the next unread article 232(@code{gnus-summary-next-unread-article}). 233 234@kindex p @r{(Gnus Summary mode)} 235@findex gnus-summary-prev-unread-article 236@item p 237Select the previous unread article 238(@code{gnus-summary-prev-unread-article}). 239 240@kindex s @r{(Gnus Summary mode)} 241@findex gnus-summary-isearch-article 242@item s 243Do an incremental search on the selected article buffer 244(@code{gnus-summary-isearch-article}), as if you switched to the 245buffer and typed @kbd{C-s} (@pxref{Incremental Search}). 246 247@kindex M-s M-s @r{(Gnus Summary mode)} 248@findex gnus-summary-search-article-forward 249@item M-s @var{regexp} @key{RET} 250Search forward for articles containing a match for @var{regexp} 251(@code{gnus-summary-search-article-forward}). 252 253@kindex M-s M-r @r{(Gnus Summary mode)} 254@findex gnus-summary-search-article-backward 255@item M-r @var{regexp} @key{RET} 256Search back for articles containing a match for @var{regexp} 257(@code{gnus-summary-search-article-backward}). 258 259@kindex q @r{(Gnus Summary mode)} 260@item q 261Exit the summary buffer and return to the group buffer 262(@code{gnus-summary-exit}). 263@end table 264 265@node Host Security 266@section Host Security 267@cindex security 268 269Emacs runs inside an operating system such as GNU/Linux, and relies on 270the operating system to check security constraints such as accesses to 271files. The default settings for Emacs are designed for typical use; 272they may require some tailoring in environments where security is more 273of a concern, or less of a concern, than usual. For example, 274file-local variables can be risky, and you can set the variable 275@code{enable-local-variables} to @code{:safe} or (even more 276conservatively) to @code{nil}; conversely, if your files can all be 277trusted and the default checking for these variables is irritating, 278you can set @code{enable-local-variables} to @code{:all}. @xref{Safe 279File Variables}. 280 281@xref{Security Considerations,,, elisp, The Emacs Lisp Reference 282Manual}, for more information about security considerations when using 283Emacs as part of a larger application. 284 285@node Network Security 286@section Network Security 287@cindex network security manager 288@cindex NSM 289@cindex encryption 290@cindex SSL 291@cindex TLS 292@cindex Transport Layer Security 293@cindex STARTTLS 294 295Whenever Emacs establishes any network connection, it passes the 296established connection to the @dfn{Network Security Manager} 297(@acronym{NSM}). @acronym{NSM} is responsible for enforcing the 298network security under your control. Currently, this works by using 299the Transport Layer Security (@acronym{TLS}) features. 300 301@vindex network-security-level 302The @code{network-security-level} variable determines the security 303level that @acronym{NSM} enforces. If its value is @code{low}, no 304security checks are performed. This is not recommended, and will 305basically mean that your network connections can't be trusted. 306However, the setting can be useful in limited circumstances, as when 307testing network issues. 308 309If this variable is @code{medium} (which is the default), a number of 310checks will be performed. If as result @acronym{NSM} determines that 311the network connection might not be trustworthy, it will make you 312aware of that, and will ask you what to do about the network 313connection. 314 315You can decide to register a permanent security exception for an 316unverified connection, a temporary exception, or refuse the connection 317entirely. 318 319@vindex network-security-protocol-checks 320In addition to the basic certificate correctness checks, several 321@acronym{TLS} algorithm checks are available. Some encryption 322technologies that were previously thought to be secure have shown 323themselves to be fragile, so Emacs (by default) warns you about some 324of these problems. 325 326The protocol network checks is controlled via the 327@code{network-security-protocol-checks} variable. 328 329It's an alist where the first element of each association is the name 330of the check, and the second element is the security level where the 331check should be used. 332 333An element like @code{(rc4 medium)} will result in the function 334@code{nsm-protocol-check--rc4} being called like thus: 335@w{@code{(nsm-protocol-check--rc4 host port status settings)}}. 336The function should return non-@code{nil} if the connection should 337proceed and @code{nil} otherwise. 338 339Below is a list of the checks done on the default @code{medium} level. 340 341@table @asis 342 343@item unable to verify a @acronym{TLS} certificate 344If the connection is a @acronym{TLS}, @acronym{SSL} or 345@acronym{STARTTLS} connection, @acronym{NSM} will check whether 346the certificate used to establish the identity of the server we're 347connecting to can be verified. 348 349While an invalid certificate is often the cause for concern (there 350could be a Man-in-the-Middle hijacking your network connection and 351stealing your password), there may be valid reasons for going ahead 352with the connection anyway. For instance, the server may be using a 353self-signed certificate, or the certificate may have expired. It's up 354to you to determine whether it's acceptable to continue with the 355connection. 356 357@item a self-signed certificate has changed 358If you've previously accepted a self-signed certificate, but it has 359now changed, that could mean that the server has just changed the 360certificate, but it might also mean that the network connection has 361been hijacked. 362 363@item previously encrypted connection now unencrypted 364If the connection is unencrypted, but it was encrypted in previous 365sessions, this might mean that there is a proxy between you and the 366server that strips away @acronym{STARTTLS} announcements, leaving the 367connection unencrypted. This is usually very suspicious. 368 369@item talking to an unencrypted service when sending a password 370When connecting to an @acronym{IMAP} or @acronym{POP3} server, these 371should usually be encrypted, because it's common to send passwords 372over these connections. Similarly, if you're sending email via 373@acronym{SMTP} that requires a password, you usually want that 374connection to be encrypted. If the connection isn't encrypted, 375@acronym{NSM} will warn you. 376 377@item Diffie-Hellman low prime bits 378When doing the public key exchange, the number of prime bits should be 379high enough to ensure that the channel can't be eavesdropped on by third 380parties. If this number is too low, Emacs will warn you. (This is the 381@code{diffie-hellman-prime-bits} check in 382@code{network-security-protocol-checks}). 383 384@item @acronym{RC4} stream cipher 385The @acronym{RC4} stream cipher is believed to be of low quality and 386may allow eavesdropping by third parties. (This is the @code{rc4} 387check in @code{network-security-protocol-checks}). 388 389@item @acronym{SHA1} in the host certificate or in intermediate certificates 390It is believed that if an intermediate certificate uses the 391@acronym{SHA1} hashing algorithm, then third parties can issue 392certificates pretending to be that issuing instance. These 393connections are therefore vulnerable to man-in-the-middle attacks. 394(These are the @code{signature-sha1} and @code{intermediate-sha1} 395checks in @code{network-security-protocol-checks}). 396 397@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} 398The protocols older than @acronym{TLS1.0} are believed to be 399vulnerable to a variety of attacks, and you may want to avoid using 400these if what you're doing requires higher security. (This is the 401@code{ssl} check in @code{network-security-protocol-checks}). 402 403@end table 404 405If @code{network-security-level} is @code{high}, the following checks 406will be made, in addition to the above: 407 408@table @asis 409@item @acronym{3DES} cipher 410The @acronym{3DES} stream cipher provides at most 112 bits of 411effective security, which is considered to be towards the low end. 412(This is the @code{3des} check in 413@code{network-security-protocol-checks}). 414 415@item a validated certificate changes the public key 416Servers change their keys occasionally, and that is normally nothing 417to be concerned about. However, if you are worried that your network 418connections are being hijacked by agencies who have access to pliable 419Certificate Authorities which issue new certificates for third-party 420services, you may want to keep track of these changes. 421 422@end table 423 424Finally, if @code{network-security-level} is @code{paranoid}, you will 425also be notified the first time @acronym{NSM} sees any new 426certificate. This will allow you to inspect all the certificates from 427all the connections that Emacs makes. 428 429The following additional variables can be used to control details of 430@acronym{NSM} operation: 431 432@table @code 433@item nsm-settings-file 434@vindex nsm-settings-file 435This is the file where @acronym{NSM} stores details about connections. 436It defaults to @file{~/.emacs.d/network-security.data}. 437 438@item nsm-save-host-names 439@vindex nsm-save-host-names 440By default, host names will not be saved for non-@code{STARTTLS} 441connections. Instead a host/port hash is used to identify connections. 442This means that one can't casually read the settings file to see what 443servers the user has connected to. If this variable is @code{t}, 444@acronym{NSM} will also save host names in the 445@code{nsm-settings-file}. 446 447@end table 448 449 450@node Document View 451@section Document Viewing 452@cindex DVI file 453@cindex PDF file 454@cindex PS file 455@cindex PostScript file 456@cindex OpenDocument file 457@cindex Microsoft Office file 458@cindex DocView mode 459@cindex mode, DocView 460@cindex document viewer (DocView) 461@findex doc-view-mode 462 463 DocView mode is a major mode for viewing DVI, PostScript (PS), PDF, 464OpenDocument, and Microsoft Office documents. It provides features 465such as slicing, zooming, and searching inside documents. It works by 466converting the document to a set of images using the @command{gs} 467(GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands 468and other external tools @footnote{For PostScript files, GhostScript 469is a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} 470is needed. For OpenDocument and Microsoft Office documents, the 471@code{unoconv} tool is needed.}, and displaying those images. 472 473@findex doc-view-toggle-display 474@findex doc-view-minor-mode 475 When you visit a document file that can be displayed with DocView 476mode, Emacs automatically uses that mode @footnote{The needed 477external tools for the document type must be available, and Emacs must 478be running in a graphical frame and have PNG image support. If these 479requirements is not fulfilled, Emacs falls back to another major 480mode.}. As an exception, when you visit a PostScript file, Emacs 481switches to PS mode, a major mode for editing PostScript files as 482text; however, it also enables DocView minor mode, so you can type 483@kbd{C-c C-c} to view the document with DocView. In either DocView 484mode or DocView minor mode, repeating @kbd{C-c C-c} 485(@code{doc-view-toggle-display}) toggles between DocView and the 486underlying file contents. 487 488@findex doc-view-open-text 489 When you visit a file which would normally be handled by DocView 490mode but some requirement is not met (e.g., you operate in a terminal 491frame or Emacs has no PNG support), you are queried if you want to 492view the document's contents as plain text. If you confirm, the 493buffer is put in text mode and DocView minor mode is activated. Thus, 494by typing @kbd{C-c C-c} you switch to the fallback mode. With another 495@kbd{C-c C-c} you return to DocView mode. The plain text contents can 496also be displayed from within DocView mode by typing @kbd{C-c C-t} 497(@code{doc-view-open-text}). 498 499 You can explicitly enable DocView mode with the command @kbd{M-x 500doc-view-mode}. You can toggle DocView minor mode with @kbd{M-x 501doc-view-minor-mode}. 502 503 When DocView mode starts, it displays a welcome screen and begins 504formatting the file, page by page. It displays the first page once 505that has been formatted. 506 507 To kill the DocView buffer, type @kbd{k} 508(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} 509(@code{quit-window}). 510 511@menu 512* Navigation: DocView Navigation. Navigating DocView buffers. 513* Searching: DocView Searching. Searching inside documents. 514* Slicing: DocView Slicing. Specifying which part of a page is displayed. 515* Conversion: DocView Conversion. Influencing and triggering conversion. 516@end menu 517 518@node DocView Navigation 519@subsection DocView Navigation 520 521 In DocView mode, you can scroll the current page using the usual 522Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and 523the arrow keys. 524 525@vindex doc-view-continuous 526 By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop 527scrolling at the beginning and end of the current page, respectively. 528However, if you change the variable @code{doc-view-continuous} to a 529non-@code{nil} value, then @kbd{C-p} displays the previous page if you 530are already at the beginning of the current page, and @kbd{C-n} 531displays the next page if you are at the end of the current page. 532 533@findex doc-view-next-page 534@findex doc-view-previous-page 535@kindex n @r{(DocView mode)} 536@kindex p @r{(DocView mode)} 537@kindex PageDown @r{(DocView mode)} 538@kindex PageUp @r{(DocView mode)} 539@kindex next @r{(DocView mode)} 540@kindex prior @r{(DocView mode)} 541@kindex C-x ] @r{(DocView mode)} 542@kindex C-x [ @r{(DocView mode)} 543 You can also display the next page by typing @kbd{n}, 544@key{PageDown}, @key{next} or @kbd{C-x ]} (@code{doc-view-next-page}). 545To display the previous page, type @kbd{p}, @key{PageUp}, @key{prior} 546or @kbd{C-x [} (@code{doc-view-previous-page}). 547 548@findex doc-view-scroll-up-or-next-page 549@findex doc-view-scroll-down-or-previous-page 550@kindex SPC @r{(DocView mode)} 551@kindex DEL @r{(DocView mode)} 552 @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient 553way to advance through the document. It scrolls within the current 554page or advances to the next. @key{DEL} moves backwards in a similar 555way (@code{doc-view-scroll-down-or-previous-page}). 556 557@findex doc-view-first-page 558@findex doc-view-last-page 559@findex doc-view-goto-page 560@kindex M-< @r{(DocView mode)} 561@kindex M-> @r{(DocView mode)} 562 To go to the first page, type @kbd{M-<} 563(@code{doc-view-first-page}); to go to the last one, type @kbd{M->} 564(@code{doc-view-last-page}). To jump to a page by its number, type 565@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). 566 567@findex doc-view-enlarge 568@findex doc-view-shrink 569@vindex doc-view-resolution 570@vindex doc-view-scale-internally 571@kindex + @r{(DocView mode)} 572@kindex - @r{(DocView mode)} 573 You can enlarge or shrink the document with @kbd{+} 574(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). By 575default, these commands just rescale the already-rendered image. If 576you instead want the image to be re-rendered at the new size, set 577@code{doc-view-scale-internally} to @code{nil}. To specify the 578default size for DocView, customize the variable 579@code{doc-view-resolution}. 580 581@node DocView Searching 582@subsection DocView Searching 583 584 In DocView mode, you can search the file's text for a regular 585expression (@pxref{Regexps}). The interface for searching is inspired 586by @code{isearch} (@pxref{Incremental Search}). 587 588@findex doc-view-search 589@findex doc-view-search-backward 590@findex doc-view-show-tooltip 591 To begin a search, type @kbd{C-s} (@code{doc-view-search}) or 592@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular 593expression using a minibuffer, then echoes the number of matches found 594within the document. You can move forward and back among the matches 595by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show 596the match inside the page image; instead, it displays a tooltip (at 597the mouse position) listing all matching lines in the current page. 598To force display of this tooltip, type @kbd{C-t} 599(@code{doc-view-show-tooltip}). 600 601 To start a new search, use the search command with a prefix 602argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} 603for a backward search. 604 605@node DocView Slicing 606@subsection DocView Slicing 607 608Documents often have wide margins for printing. They are annoying 609when reading the document on the screen, because they use up screen 610space and can cause inconvenient scrolling. 611 612@findex doc-view-set-slice 613@findex doc-view-set-slice-using-mouse 614 With DocView you can hide these margins by selecting a @dfn{slice} 615of pages to display. A slice is a rectangle within the page area; 616once you specify a slice in DocView, it applies to whichever page you 617look at. 618 619 To specify the slice numerically, type @kbd{c s} 620(@code{doc-view-set-slice}); then enter the top left pixel position 621and the slice's width and height. 622@c ??? how does this work? 623 624 A more convenient graphical way to specify the slice is with @kbd{c 625m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to 626select the slice. Simply press and hold the left mouse button at the 627upper-left corner of the region you want to have in the slice, then 628move the mouse pointer to the lower-right corner and release the 629button. 630 631 The most convenient way is to set the optimal slice by using 632BoundingBox information automatically determined from the document by 633typing @kbd{c b} (@code{doc-view-set-slice-from-bounding-box}). 634 635@findex doc-view-reset-slice 636 To cancel the selected slice, type @kbd{c r} 637(@code{doc-view-reset-slice}). Then DocView shows the entire page 638including its entire margins. 639 640@node DocView Conversion 641@subsection DocView Conversion 642 643@vindex doc-view-cache-directory 644@findex doc-view-clear-cache 645 For efficiency, DocView caches the images produced by @command{gs}. 646The name of the directory where it caches images is given by the variable 647@code{doc-view-cache-directory}. You can clear the cache directory by 648typing @kbd{M-x doc-view-clear-cache}. 649 650@findex doc-view-kill-proc 651@findex doc-view-kill-proc-and-buffer 652 To force reconversion of the currently viewed document, type @kbd{r} 653or @kbd{g} (@code{revert-buffer}). To kill the converter process 654associated with the current buffer, type @kbd{K} 655(@code{doc-view-kill-proc}). The command @kbd{k} 656(@code{doc-view-kill-proc-and-buffer}) kills the converter process and 657the DocView buffer. 658 659@node Shell 660@section Running Shell Commands from Emacs 661@cindex subshell 662@cindex shell commands 663 664 Emacs has commands for passing single command lines to shell 665subprocesses, and for running a shell interactively with input and 666output to an Emacs buffer, and for running a shell in a terminal 667emulator window. 668 669@table @kbd 670@item M-! @var{cmd} @key{RET} 671Run the shell command @var{cmd} and display the output 672(@code{shell-command}). 673@item M-| @var{cmd} @key{RET} 674Run the shell command @var{cmd} with region contents as input; 675optionally replace the region with the output 676(@code{shell-command-on-region}). 677@item M-& @var{cmd} @key{RET} 678Run the shell command @var{cmd} asynchronously, and display the output 679(@code{async-shell-command}). 680@item M-x shell 681Run a subshell with input and output through an Emacs buffer. You can 682then give commands interactively. 683@item M-x term 684Run a subshell with input and output through an Emacs buffer. You can 685then give commands interactively. Full terminal emulation is 686available. 687@end table 688 689@vindex exec-path 690 Whenever you specify a relative file name for an executable program 691(either in the @var{cmd} argument to one of the above commands, or in 692other contexts), Emacs searches for the program in the directories 693specified by the variable @code{exec-path}. The value of this 694variable must be a list of directories; the default value is 695initialized from the environment variable @env{PATH} when Emacs is 696started (@pxref{General Variables}). 697 698 @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It 699is documented in its own manual. 700@ifnottex 701@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. 702@end ifnottex 703@iftex 704See the Eshell Info manual, which is distributed with Emacs. 705@end iftex 706 707@menu 708* Single Shell:: How to run one shell command and return. 709* Interactive Shell:: Permanent shell taking input via Emacs. 710* Shell Mode:: Special Emacs commands used with permanent shell. 711* Shell Prompts:: Two ways to recognize shell prompts. 712* History: Shell History. Repeating previous commands in a shell buffer. 713* Directory Tracking:: Keeping track when the subshell changes directory. 714* Options: Shell Options. Options for customizing Shell mode. 715* Terminal emulator:: An Emacs window as a terminal emulator. 716* Term Mode:: Special Emacs commands used in Term mode. 717* Remote Host:: Connecting to another computer. 718* Serial Terminal:: Connecting to a serial port. 719@end menu 720 721@node Single Shell 722@subsection Single Shell Commands 723 724@kindex M-! 725@findex shell-command 726@vindex shell-command-buffer-name 727 @kbd{M-!} (@code{shell-command}) reads a line of text using the 728minibuffer and executes it as a shell command, in a subshell made just 729for that command. Standard input for the command comes from the null 730device. If the shell command produces any output, the output appears 731either in the echo area (if it is short), or in the @samp{"*Shell 732Command Output*"} (@code{shell-command-buffer-name}) buffer (if the 733output is long). The variables @code{resize-mini-windows} and 734@code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when 735Emacs should consider the output to be too long for the echo area. 736 737 For instance, one way to decompress a file named @file{foo.gz} is to 738type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally 739creates the file @file{foo} and produces no terminal output. 740 741 A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!}, 742causes it to insert terminal output into the current buffer instead of 743a separate buffer. By default, it puts point before the output, and 744sets the mark after the output (but a non-default value of 745@code{shell-command-dont-erase-buffer} can change that, see below). 746For instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the 747uncompressed form of the file @file{foo.gz} into the current buffer. 748 749 Provided the specified shell command does not end with @samp{&}, it 750runs @dfn{synchronously}, and you must wait for it to exit before 751continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit; 752this sends a @code{SIGINT} signal to terminate the shell command (this 753is the same signal that @kbd{C-c} normally generates in the shell). 754Emacs then waits until the command actually terminates. If the shell 755command doesn't stop (because it ignores the @code{SIGINT} signal), 756type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal, 757which is impossible to ignore. 758 759@kindex M-& 760@findex async-shell-command 761@vindex shell-command-buffer-name-async 762 A shell command that ends in @samp{&} is executed 763@dfn{asynchronously}, and you can continue to use Emacs as it runs. 764You can also type @kbd{M-&} (@code{async-shell-command}) to execute a 765shell command asynchronously; this is exactly like calling @kbd{M-!} 766with a trailing @samp{&}, except that you do not need the @samp{&}. 767The output from asynchronous shell commands, by default, goes into the 768@samp{"*Async Shell Command*"} buffer 769(@code{shell-command-buffer-name-async}). Emacs inserts the output 770into this buffer as it comes in, whether or not the buffer is visible 771in a window. 772 773@vindex async-shell-command-buffer 774 If you want to run more than one asynchronous shell command at the 775same time, they could end up competing for the output buffer. The 776option @code{async-shell-command-buffer} specifies what to do about 777this; e.g., whether to rename the pre-existing output buffer, or to 778use a different buffer for the new command. Consult the variable's 779documentation for more possibilities. 780 781@vindex async-shell-command-display-buffer 782 If you want the output buffer for asynchronous shell commands to be 783displayed only when the command generates output, set 784@code{async-shell-command-display-buffer} to @code{nil}. 785 786@vindex async-shell-command-width 787 The option @code{async-shell-command-width} defines the number of display 788columns available for output of asynchronous shell commands. 789A positive integer tells the shell to use that number of columns for 790command output. The default value is @code{nil} that means to use 791the same number of columns as provided by the shell. 792 793@vindex shell-command-prompt-show-cwd 794 To make the above commands show the current directory in their 795prompts, customize the variable @code{shell-command-prompt-show-cwd} 796to a non-@code{nil} value. 797 798@kindex M-| 799@findex shell-command-on-region 800 @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but 801passes the contents of the region as the standard input to the shell 802command, instead of no input. With a numeric argument, it deletes the 803old region and replaces it with the output from the shell command. 804 805 For example, you can use @kbd{M-|} with the @command{gpg} program to 806see what keys are in the buffer. If the buffer contains a GnuPG key, 807type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents 808to @command{gpg}. This will output the list of keys to the 809buffer whose name is the value of @code{shell-command-buffer-name}. 810 811@vindex shell-file-name 812@cindex @env{SHELL} environment variable 813 The above commands use the shell specified by the variable 814@code{shell-file-name}. Its default value is determined by the 815@env{SHELL} environment variable when Emacs is started. If the file 816name is relative, Emacs searches the directories listed in 817@code{exec-path} (@pxref{Shell}). 818 819 If the default directory is remote (@pxref{Remote Files}), the 820default value is @file{/bin/sh}. This can be changed by declaring 821@code{shell-file-name} connection-local (@pxref{Connection Variables}). 822 823 To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command 824@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. 825 826@vindex shell-command-default-error-buffer 827 By default, error output is intermixed with the regular output in 828the output buffer. But if you change the value of the variable 829@code{shell-command-default-error-buffer} to a string, error output is 830inserted into a buffer of that name. 831 832@vindex shell-command-dont-erase-buffer 833 By default, the output buffer is erased between shell commands, except 834when the output goes to the current buffer. If you change the value 835of the option @code{shell-command-dont-erase-buffer} to @code{erase}, 836then the output buffer is always erased. Other non-@code{nil} values 837prevent erasing of the output buffer, and---if the output buffer is 838not the current buffer---also control where to put point after 839inserting the output of the shell command: 840 841@table @code 842@item beg-last-out 843Puts point at the beginning of the last shell-command output. 844@item end-last-out 845Puts point at the end of the last shell-command output, i.e.@: at the 846end of the output buffer. 847@item save-point 848Restores the position of point as it was before inserting the 849shell-command output. 850@end table 851 852@node Interactive Shell 853@subsection Interactive Subshell 854 855@findex shell 856 To run a subshell interactively, type @kbd{M-x shell}. This creates 857(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess 858with input coming from and output going to that buffer. That is to 859say, any terminal output from the subshell goes into the buffer, 860advancing point, and any terminal input for the subshell comes from 861text in the buffer. To give input to the subshell, go to the end of 862the buffer and type the input, terminated by @key{RET}. 863 864 By default, when the subshell is invoked interactively, the 865@file{*shell*} buffer is displayed in a new window, unless the current 866window already shows the @file{*shell*} buffer. This behavior can 867be customized via @code{display-buffer-alist} (@pxref{Window Choice}). 868 869 While the subshell is waiting or running a command, you can switch 870windows or buffers and perform other editing in Emacs. Emacs inserts 871the output from the subshell into the Shell buffer whenever it has 872time to process it (e.g., while waiting for keyboard input). 873 874@cindex @code{comint-highlight-input} face 875@cindex @code{comint-highlight-prompt} face 876 In the Shell buffer, prompts are displayed with the face 877@code{comint-highlight-prompt}, and submitted input lines are 878displayed with the face @code{comint-highlight-input}. This makes it 879easier to distinguish input lines from the shell output. 880@xref{Faces}. 881 882 To make multiple subshells, invoke @kbd{M-x shell} with a prefix 883argument (e.g., @kbd{C-u M-x shell}). Then the command will read a 884buffer name, and create (or reuse) a subshell in that buffer. You can 885also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely}, 886then create a new @file{*shell*} buffer using plain @kbd{M-x shell}. 887Subshells in different buffers run independently and in parallel. 888 889@vindex explicit-shell-file-name 890@cindex environment variables for subshells 891@cindex @env{ESHELL} environment variable 892 To specify the shell file name used by @kbd{M-x shell}, customize 893the variable @code{explicit-shell-file-name}. If this is @code{nil} 894(the default), Emacs uses the environment variable @env{ESHELL} if it 895exists. Otherwise, it usually uses the variable 896@code{shell-file-name} (@pxref{Single Shell}); but if the default 897directory is remote (@pxref{Remote Files}), it prompts you for the 898shell file name. @xref{Minibuffer File}, for hints how to type remote 899file names effectively. 900 901 Emacs sends the new shell the contents of the file 902@file{~/.emacs_@var{shellname}} as input, if it exists, where 903@var{shellname} is the name of the file that the shell was loaded 904from. For example, if you use bash, the file sent to it is 905@file{~/.emacs_bash}. If this file is not found, Emacs tries with 906@file{~/.emacs.d/init_@var{shellname}.sh}. 907 908 To specify a coding system for the shell, you can use the command 909@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can 910also change the coding system for a running subshell by typing 911@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication 912Coding}. 913 914@cindex @env{INSIDE_EMACS} environment variable 915 Emacs sets the environment variable @env{INSIDE_EMACS} in the 916subshell to @samp{@var{version},comint}, where @var{version} is the 917Emacs version (e.g., @samp{24.1}). Programs can check this variable 918to determine whether they are running inside an Emacs subshell. 919 920@node Shell Mode 921@subsection Shell Mode 922@cindex Shell mode 923@cindex mode, Shell 924 925 The major mode for Shell buffers is Shell mode. Many of its special 926commands are bound to the @kbd{C-c} prefix, and resemble the usual 927editing and job control characters present in ordinary shells, except 928that you must type @kbd{C-c} first. Here is a list of Shell mode 929commands: 930 931@table @kbd 932@item @key{RET} 933@kindex RET @r{(Shell mode)} 934@findex comint-send-input 935Send the current line as input to the subshell 936(@code{comint-send-input}). Any shell prompt at the beginning of the 937line is omitted (@pxref{Shell Prompts}). If point is at the end of 938buffer, this is like submitting the command line in an ordinary 939interactive shell. However, you can also invoke @key{RET} elsewhere 940in the shell buffer to submit the current line as input. 941 942@item @key{TAB} 943@kindex TAB @r{(Shell mode)} 944@findex completion-at-point@r{, in Shell Mode} 945@cindex shell completion 946Complete the command name or file name before point in the shell 947buffer (@code{completion-at-point}). This uses the usual Emacs 948completion rules (@pxref{Completion}), with the completion 949alternatives being file names, environment variable names, the shell 950command history, and history references (@pxref{History References}). 951For options controlling the completion, @pxref{Shell Options}. 952 953@item M-? 954@kindex M-? @r{(Shell mode)} 955@findex comint-dynamic-list-filename@dots{} 956Display temporarily a list of the possible completions of the file 957name before point (@code{comint-dynamic-list-filename-completions}). 958 959@item C-d 960@kindex C-d @r{(Shell mode)} 961@findex comint-delchar-or-maybe-eof 962Either delete a character or send @acronym{EOF} 963(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell 964buffer, this sends @acronym{EOF} to the subshell. Typed at any other 965position in the buffer, this deletes a character as usual. 966 967@item C-c C-a 968@kindex C-c C-a @r{(Shell mode)} 969@findex comint-bol-or-process-mark 970Move to the beginning of the line, but after the prompt if any 971(@code{comint-bol-or-process-mark}). If you repeat this command twice 972in a row, the second time it moves back to the process mark, which is 973the beginning of the input that you have not yet sent to the subshell. 974(Normally that is the same place---the end of the prompt on this 975line---but after @kbd{C-c @key{SPC}} the process mark may be in a 976previous line.) 977 978@item C-c @key{SPC} 979Accumulate multiple lines of input, then send them together 980(@code{comint-accumulate}). This command inserts a newline before 981point, but does not send the preceding text as input to the 982subshell---at least, not yet. Both lines, the one before this newline 983and the one after, will be sent together (along with the newline that 984separates them), when you type @key{RET}. 985 986@item C-c C-u 987@kindex C-c C-u @r{(Shell mode)} 988@findex comint-kill-input 989Kill all text pending at end of buffer to be sent as input 990(@code{comint-kill-input}). If point is not at end of buffer, 991this only kills the part of this text that precedes point. 992 993@item C-c C-w 994@kindex C-c C-w @r{(Shell mode)} 995Kill a word before point (@code{backward-kill-word}). 996 997@item C-c C-c 998@kindex C-c C-c @r{(Shell mode)} 999@findex comint-interrupt-subjob 1000Interrupt the shell or its current subjob if any 1001(@code{comint-interrupt-subjob}). This command also kills 1002any shell input pending in the shell buffer and not yet sent. 1003 1004@item C-c C-z 1005@kindex C-c C-z @r{(Shell mode)} 1006@findex comint-stop-subjob 1007Stop the shell or its current subjob if any (@code{comint-stop-subjob}). 1008This command also kills any shell input pending in the shell buffer and 1009not yet sent. 1010 1011@item C-c C-\ 1012@findex comint-quit-subjob 1013@kindex C-c C-\ @r{(Shell mode)} 1014Send quit signal to the shell or its current subjob if any 1015(@code{comint-quit-subjob}). This command also kills any shell input 1016pending in the shell buffer and not yet sent. 1017 1018@item C-c C-o 1019@kindex C-c C-o @r{(Shell mode)} 1020@findex comint-delete-output 1021Delete the last batch of output from a shell command 1022(@code{comint-delete-output}). This is useful if a shell command spews 1023out lots of output that just gets in the way. With a prefix argument, 1024this command saves the deleted text in the @code{kill-ring} 1025(@pxref{Kill Ring}), so that you could later yank it (@pxref{Yanking}) 1026elsewhere. 1027 1028@item C-c C-s 1029@kindex C-c C-s @r{(Shell mode)} 1030@findex comint-write-output 1031Write the last batch of output from a shell command to a file 1032(@code{comint-write-output}). With a prefix argument, the file is 1033appended to instead. Any prompt at the end of the output is not 1034written. 1035 1036@item C-c C-r 1037@itemx C-M-l 1038@kindex C-c C-r @r{(Shell mode)} 1039@kindex C-M-l @r{(Shell mode)} 1040@findex comint-show-output 1041Scroll to display the beginning of the last batch of output at the top 1042of the window; also move the cursor there (@code{comint-show-output}). 1043 1044@item C-c C-e 1045@kindex C-c C-e @r{(Shell mode)} 1046@findex comint-show-maximum-output 1047Scroll to put the last line of the buffer at the bottom of the window 1048(@code{comint-show-maximum-output}). 1049 1050@item C-c C-f 1051@kindex C-c C-f @r{(Shell mode)} 1052@findex shell-forward-command 1053@vindex shell-command-regexp 1054Move forward across one shell command, but not beyond the current line 1055(@code{shell-forward-command}). The variable @code{shell-command-regexp} 1056specifies how to recognize the end of a command. 1057 1058@item C-c C-b 1059@kindex C-c C-b @r{(Shell mode)} 1060@findex shell-backward-command 1061Move backward across one shell command, but not beyond the current line 1062(@code{shell-backward-command}). 1063 1064@item M-x dirs 1065Ask the shell for its working directory, and update the Shell buffer's 1066default directory. @xref{Directory Tracking}. 1067 1068@item M-x comint-send-invisible @key{RET} @var{text} @key{RET} 1069@findex comint-send-invisible 1070Send @var{text} as input to the shell, after reading it without 1071echoing. This is useful when a shell command runs a program that asks 1072for a password. 1073 1074Please note that Emacs will not echo passwords by default. If you 1075really want them to be echoed, evaluate (@pxref{Lisp Eval}) the 1076following Lisp expression: 1077 1078@example 1079(remove-hook 'comint-output-filter-functions 1080 'comint-watch-for-password-prompt) 1081@end example 1082 1083@item M-x comint-continue-subjob 1084@findex comint-continue-subjob 1085Continue the shell process. This is useful if you accidentally suspend 1086the shell process.@footnote{You should not suspend the shell process. 1087Suspending a subjob of the shell is a completely different matter---that 1088is normal practice, but you must use the shell to continue the subjob; 1089this command won't do it.} 1090 1091@item M-x comint-strip-ctrl-m 1092@findex comint-strip-ctrl-m 1093Discard all control-M characters from the current group of shell output. 1094The most convenient way to use this command is to make it run 1095automatically when you get output from the subshell. To do that, 1096evaluate this Lisp expression: 1097 1098@example 1099(add-hook 'comint-output-filter-functions 1100 'comint-strip-ctrl-m) 1101@end example 1102 1103@item M-x comint-truncate-buffer 1104@findex comint-truncate-buffer 1105This command truncates the shell buffer to a certain maximum number of 1106lines, specified by the variable @code{comint-buffer-maximum-size}. 1107Here's how to do this automatically each time you get output from the 1108subshell: 1109 1110@example 1111(add-hook 'comint-output-filter-functions 1112 'comint-truncate-buffer) 1113@end example 1114@end table 1115 1116By default, Shell mode handles common @acronym{ANSI} escape codes (for 1117instance, for changing the color of text). Emacs also optionally 1118supports some extend escape codes, like some of the @acronym{OSC} 1119(Operating System Codes) if you put the following in your init file: 1120 1121@lisp 1122(add-hook 'comint-output-filter-functions 'comint-osc-process-output) 1123@end lisp 1124 1125With this enabled, the output from, for instance, @code{ls 1126--hyperlink} will be made into clickable buttons in the Shell mode 1127buffer. 1128 1129@cindex Comint mode 1130@cindex mode, Comint 1131 Shell mode is a derivative of Comint mode, a general-purpose mode for 1132communicating with interactive subprocesses. Most of the features of 1133Shell mode actually come from Comint mode, as you can see from the 1134command names listed above. The special features of Shell mode include 1135the directory tracking feature, and a few user commands. 1136 1137 Other Emacs features that use variants of Comint mode include GUD 1138(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). 1139 1140@findex comint-run 1141 You can use @kbd{M-x comint-run} to execute any program of your choice 1142in a subprocess using unmodified Comint mode---without the 1143specializations of Shell mode. To pass arguments to the program, use 1144@kbd{C-u M-x comint-run}. 1145 1146@node Shell Prompts 1147@subsection Shell Prompts 1148 1149@cindex prompt, shell 1150 A prompt is text output by a program to show that it is ready to 1151accept new user input. Normally, Comint mode (and thus Shell mode) 1152automatically figures out which part of the buffer is a prompt, based 1153on the output of the subprocess. (Specifically, it assumes that any 1154received output line which doesn't end with a newline is a prompt.) 1155 1156 Comint mode divides the buffer into two types of @dfn{fields}: input 1157fields (where user input is typed) and output fields (everywhere 1158else). Prompts are part of the output fields. Most Emacs motion 1159commands do not cross field boundaries, unless they move over multiple 1160lines. For instance, when point is in the input field on a shell 1161command line, @kbd{C-a} puts point at the beginning of the input 1162field, after the prompt. Internally, the fields are implemented using 1163the @code{field} text property (@pxref{Text Properties,,, elisp, the 1164Emacs Lisp Reference Manual}). 1165 1166@vindex comint-use-prompt-regexp 1167@vindex shell-prompt-pattern 1168 If you change the variable @code{comint-use-prompt-regexp} to a 1169non-@code{nil} value, then Comint mode will recognize prompts using a 1170regular expression (@pxref{Regexps}). In Shell mode, the regular 1171expression is specified by the variable @code{shell-prompt-pattern}. 1172The default value of @code{comint-use-prompt-regexp} is @code{nil}, 1173because this method for recognizing prompts is unreliable, but you may 1174want to set it to a non-@code{nil} value in unusual circumstances. In 1175that case, Emacs does not divide the Comint buffer into fields, so the 1176general motion commands behave as they normally do in buffers without 1177special text properties. However, you can use the paragraph motion 1178commands to conveniently navigate the buffer (@pxref{Paragraphs}); in 1179Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph 1180boundaries. 1181 1182@node Shell History 1183@subsection Shell Command History 1184 1185 Shell buffers support three ways of repeating earlier commands. You 1186can use keys like those used for the minibuffer history; these work 1187much as they do in the minibuffer, inserting text from prior commands 1188while point remains always at the end of the buffer. You can move 1189through the buffer to previous inputs in their original place, then 1190resubmit them or copy them to the end. Or you can use a 1191@samp{!}-style history reference. 1192 1193@menu 1194* Ring: Shell Ring. Fetching commands from the history list. 1195* Copy: Shell History Copying. Moving to a command and then copying it. 1196* History References:: Expanding @samp{!}-style history references. 1197@end menu 1198 1199@node Shell Ring 1200@subsubsection Shell History Ring 1201 1202@table @kbd 1203@findex comint-previous-input 1204@kindex M-p @r{(Shell mode)} 1205@item M-p 1206@itemx C-@key{UP} 1207Fetch the next earlier old shell command 1208(@code{comint-previous-input}). 1209 1210@kindex M-n @r{(Shell mode)} 1211@findex comint-next-input 1212@item M-n 1213@itemx C-@key{DOWN} 1214Fetch the next later old shell command (@code{comint-next-input}). 1215 1216@kindex M-r @r{(Shell mode)} 1217@findex comint-history-isearch-backward-regexp 1218@item M-r 1219Begin an incremental regexp search of old shell commands 1220(@code{comint-history-isearch-backward-regexp}). 1221 1222@item C-c C-x 1223@kindex C-c C-x @r{(Shell mode)} 1224@findex comint-get-next-from-history 1225Fetch the next subsequent command from the history 1226(@code{comint-get-next-from-history}). 1227 1228@item C-c . 1229@kindex C-c . @r{(Shell mode)} 1230@findex comint-insert-previous-argument 1231Fetch one argument from an old shell command 1232(@code{comint-input-previous-argument}). 1233 1234@item C-c C-l 1235@kindex C-c C-l @r{(Shell mode)} 1236@findex comint-dynamic-list-input-ring 1237Display the buffer's history of shell commands in another window 1238(@code{comint-dynamic-list-input-ring}). 1239@end table 1240 1241 Shell buffers provide a history of previously entered shell 1242commands. To reuse shell commands from the history, use the editing 1243commands @kbd{M-p}, @kbd{M-n}, and @kbd{M-r}. These work 1244similar to the minibuffer history commands (@pxref{Minibuffer 1245History}), except that they operate within the Shell buffer rather 1246than the minibuffer, and @code{M-r} in a Shell buffer invokes 1247incremental search through shell command history. 1248 1249 @kbd{M-p} fetches an earlier shell command to the end of the shell 1250buffer. Successive use of @kbd{M-p} fetches successively earlier 1251shell commands, each replacing any text that was already present as 1252potential shell input. @kbd{M-n} does likewise except that it finds 1253successively more recent shell commands from the buffer. 1254@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like 1255@kbd{M-n}. 1256 1257 The history search command @kbd{M-r} begins an incremental regular 1258expression search of previous shell commands. After typing @kbd{M-r}, 1259start typing the desired string or regular expression; the last 1260matching shell command will be displayed in the current line. 1261Incremental search commands have their usual effects---for instance, 1262@kbd{C-s} and @kbd{C-r} search forward and backward for the next match 1263(@pxref{Incremental Search}). When you find the desired input, type 1264@key{RET} to terminate the search. This puts the input in the command 1265line. Any partial input you were composing before navigating the 1266history list is restored when you go to the beginning or end of the 1267history ring. 1268 1269 Often it is useful to reexecute several successive shell commands that 1270were previously executed in sequence. To do this, first find and 1271reexecute the first command of the sequence. Then type @kbd{C-c C-x}; 1272that will fetch the following command---the one that follows the command 1273you just repeated. Then type @key{RET} to reexecute this command. You 1274can reexecute several successive commands by typing @kbd{C-c C-x 1275@key{RET}} over and over. 1276 1277 The command @kbd{C-c .}@: (@code{comint-insert-previous-argument}) 1278copies an individual argument from a previous command, like 1279@kbd{@key{ESC} .}@: in Bash and @command{zsh}. The simplest use 1280copies the last argument from the previous shell command. With a 1281prefix argument @var{n}, it copies the @var{n}th argument instead. 1282Repeating @kbd{C-c .} copies from an earlier shell commands, always 1283using the same value of @var{n} (don't give a prefix argument when 1284you repeat the @kbd{C-c .} command). 1285 1286@vindex comint-insert-previous-argument-from-end 1287 If you set @code{comint-insert-previous-argument-from-end} to a 1288non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th 1289argument counting from the last one; this emulates @kbd{@key{ESC} .}@: 1290in @command{zsh}. 1291 1292 These commands get the text of previous shell commands from a special 1293history list, not from the shell buffer itself. Thus, editing the shell 1294buffer, or even killing large parts of it, does not affect the history 1295that these commands access. 1296 1297@vindex comint-input-ring-file-name 1298 Some shells store their command histories in files so that you can 1299refer to commands from previous shell sessions. Emacs reads 1300the command history file for your chosen shell, to initialize its own 1301command history. The file name is @file{~/.bash_history} for bash, 1302@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. 1303 1304@vindex tramp-histfile-override 1305 If you run the shell on a remote host, this setting might be 1306overwritten by the variable @code{tramp-histfile-override}. It is 1307recommended to set this variable to @code{nil}. 1308 1309@node Shell History Copying 1310@subsubsection Shell History Copying 1311 1312@table @kbd 1313@kindex C-c C-p @r{(Shell mode)} 1314@findex comint-previous-prompt 1315@item C-c C-p 1316Move point to the previous prompt (@code{comint-previous-prompt}). 1317 1318@kindex C-c C-n @r{(Shell mode)} 1319@findex comint-next-prompt 1320@item C-c C-n 1321Move point to the following prompt (@code{comint-next-prompt}). 1322 1323@kindex C-c RET @r{(Shell mode)} 1324@findex comint-copy-old-input 1325@item C-c @key{RET} 1326Copy the input command at point, inserting the copy at the end of the 1327buffer (@code{comint-copy-old-input}). This is useful if you move 1328point back to a previous command. After you copy the command, you can 1329submit the copy as input with @key{RET}. If you wish, you can edit 1330the copy before resubmitting it. If you use this command on an output 1331line, it copies that line to the end of the buffer. 1332 1333@item mouse-2 1334If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy 1335the old input command that you click on, inserting the copy at the end 1336of the buffer (@code{comint-insert-input}). If 1337@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is 1338not over old input, just yank as usual. 1339@end table 1340 1341 Moving to a previous input and then copying it with @kbd{C-c 1342@key{RET}} or @kbd{mouse-2} produces the same results---the same 1343buffer contents---that you would get by using @kbd{M-p} enough times 1344to fetch that previous input from the history list. However, @kbd{C-c 1345@key{RET}} copies the text from the buffer, which can be different 1346from what is in the history list if you edit the input text in the 1347buffer after it has been sent. 1348 1349@node History References 1350@subsubsection Shell History References 1351@cindex history reference 1352 1353 Various shells, including csh and bash, support @dfn{history 1354references} that begin with @samp{!} and @samp{^}. Shell mode 1355recognizes these constructs, and can perform the history substitution 1356for you. 1357 1358 If you insert a history reference and type @key{TAB}, this searches 1359the input history for a matching command, performs substitution if 1360necessary, and places the result in the buffer in place of the history 1361reference. For example, you can fetch the most recent command 1362beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the 1363command if you wish, and then resubmit the command to the shell by 1364typing @key{RET}. 1365 1366@vindex comint-input-autoexpand 1367@findex comint-magic-space 1368 Shell mode can optionally expand history references in the buffer 1369when you send them to the shell. To request this, set the variable 1370@code{comint-input-autoexpand} to @code{input}. You can make 1371@key{SPC} perform history expansion by binding @key{SPC} to the 1372command @code{comint-magic-space}. @xref{Rebinding}. 1373 1374 Shell mode recognizes history references when they follow a prompt. 1375@xref{Shell Prompts}, for how Shell mode recognizes prompts. 1376 1377@node Directory Tracking 1378@subsection Directory Tracking 1379@cindex directory tracking 1380 1381@vindex shell-pushd-regexp 1382@vindex shell-popd-regexp 1383@vindex shell-cd-regexp 1384 Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} 1385commands given to the subshell, in order to keep the Shell buffer's 1386default directory (@pxref{File Names}) the same as the shell's working 1387directory. It recognizes these commands by examining lines of input 1388that you send. 1389 1390 If you use aliases for these commands, you can tell Emacs to 1391recognize them also, by setting the variables 1392@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and 1393@code{shell-cd-regexp} to the appropriate regular expressions 1394(@pxref{Regexps}). For example, if @code{shell-pushd-regexp} matches 1395the beginning of a shell command line, that line is regarded as a 1396@code{pushd} command. These commands are recognized only at the 1397beginning of a shell command line. 1398 1399@findex dirs 1400 If Emacs gets confused about changes in the working directory of the 1401subshell, type @kbd{M-x dirs}. This command asks the shell for its 1402working directory and updates the default directory accordingly. It 1403works for shells that support the most common command syntax, but may 1404not work for unusual shells. 1405 1406@findex dirtrack-mode 1407@cindex Dirtrack mode 1408@cindex mode, Dirtrack 1409@vindex dirtrack-list 1410 You can also use Dirtrack mode, a buffer-local minor mode that 1411implements an alternative method of tracking the shell's working 1412directory. To use this method, your shell prompt must contain the 1413working directory at all times, and you must supply a regular 1414expression for recognizing which part of the prompt contains the 1415working directory; see the documentation of the variable 1416@code{dirtrack-list} for details. To use Dirtrack mode, type @kbd{M-x 1417dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to 1418@code{shell-mode-hook} (@pxref{Hooks}). 1419 1420@node Shell Options 1421@subsection Shell Mode Options 1422 1423@vindex comint-scroll-to-bottom-on-input 1424 If the variable @code{comint-scroll-to-bottom-on-input} is 1425non-@code{nil}, insertion and yank commands scroll the selected window 1426to the bottom before inserting. The default is @code{nil}. 1427 1428@vindex comint-scroll-show-maximum-output 1429 If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then 1430arrival of output when point is at the end tries to scroll the last 1431line of text to the bottom line of the window, showing as much useful 1432text as possible. (This mimics the scrolling behavior of most 1433terminals.) The default is @code{t}. 1434 1435@vindex comint-move-point-for-output 1436 By setting @code{comint-move-point-for-output}, you can opt for 1437having point jump to the end of the buffer whenever output arrives---no 1438matter where in the buffer point was before. If the value is 1439@code{this}, point jumps in the selected window. If the value is 1440@code{all}, point jumps in each window that shows the Comint buffer. If 1441the value is @code{other}, point jumps in all nonselected windows that 1442show the current buffer. The default value is @code{nil}, which means 1443point does not jump to the end. 1444 1445@vindex comint-prompt-read-only 1446 If you set @code{comint-prompt-read-only}, the prompts in the Comint 1447buffer are read-only. 1448 1449@vindex comint-input-ignoredups 1450 The variable @code{comint-input-ignoredups} controls whether successive 1451identical inputs are stored in the input history. A non-@code{nil} 1452value means to omit an input that is the same as the previous input. 1453The default is @code{nil}, which means to store each input even if it is 1454equal to the previous input. 1455 1456@vindex comint-completion-addsuffix 1457@vindex comint-completion-recexact 1458@vindex comint-completion-autolist 1459 Three variables customize file name completion. The variable 1460@code{comint-completion-addsuffix} controls whether completion inserts a 1461space or a slash to indicate a fully completed file or directory name 1462(non-@code{nil} means do insert a space or slash). 1463@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} 1464to choose the shortest possible completion if the usual Emacs completion 1465algorithm cannot add even a single character. 1466@code{comint-completion-autolist}, if non-@code{nil}, says to list all 1467the possible completions whenever completion is not exact. 1468 1469@vindex shell-completion-execonly 1470 Command completion normally considers only executable files. 1471If you set @code{shell-completion-execonly} to @code{nil}, 1472it considers nonexecutable files as well. 1473 1474@vindex shell-completion-fignore 1475@vindex comint-completion-fignore 1476The variable @code{shell-completion-fignore} specifies a list of file 1477name extensions to ignore in Shell mode completion. The default 1478setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to 1479ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other 1480related Comint modes use the variable @code{comint-completion-fignore} 1481instead. 1482 1483@findex shell-dynamic-complete-command 1484Some implementation details of the shell command completion may also be found 1485in the lisp documentation of the @code{shell-dynamic-complete-command} 1486function. 1487 1488@findex shell-pushd-tohome 1489@findex shell-pushd-dextract 1490@findex shell-pushd-dunique 1491 You can configure the behavior of @samp{pushd}. Variables control 1492whether @samp{pushd} behaves like @samp{cd} if no argument is given 1493(@code{shell-pushd-tohome}), pop rather than rotate with a numeric 1494argument (@code{shell-pushd-dextract}), and only add directories to the 1495directory stack if they are not already on it 1496(@code{shell-pushd-dunique}). The values you choose should match the 1497underlying shell, of course. 1498 1499@vindex comint-terminfo-terminal 1500@vindex system-uses-terminfo 1501@vindex TERM@r{, environment variable, in sub-shell} 1502Comint mode sets the @env{TERM} environment variable to a safe default 1503value, but this value disables some useful features. For example, 1504color is disabled in applications that use @env{TERM} to determine if 1505color is supported. Therefore, Emacs provides an option 1506@code{comint-terminfo-terminal} to let you choose a terminal with more 1507advanced features, as defined in your system's terminfo database. 1508Emacs will use this option as the value for @env{TERM} so long as 1509@code{system-uses-terminfo} is non-nil. 1510 1511Both @code{comint-terminfo-terminal} and @code{system-uses-terminfo} 1512can be declared as connection-local variables to adjust these options 1513to match what a remote system expects (@pxref{Connection Variables}). 1514 1515@node Terminal emulator 1516@subsection Emacs Terminal Emulator 1517@findex term 1518 1519 To run a subshell in a text terminal emulator, use @kbd{M-x term}. 1520This creates (or reuses) a buffer named @file{*terminal*}, and runs a 1521subshell with input coming from your keyboard, and output going to 1522that buffer. 1523 1524@cindex line mode @r{(terminal emulator)} 1525@cindex char mode @r{(terminal emulator)} 1526 The terminal emulator uses Term mode, which has two input modes. In 1527@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell 1528Mode}). In @dfn{char mode}, each character is sent directly to the 1529subshell, as terminal input; the sole exception is the terminal escape 1530character, which by default is @kbd{C-c} (@pxref{Term Mode}). Any 1531echoing of your input is the responsibility of the subshell; any 1532terminal output from the subshell goes into the buffer, advancing 1533point. 1534 1535 Some programs (such as Emacs itself) need to control the appearance 1536of the terminal screen in detail. They do this by emitting special 1537control codes. Term mode recognizes and handles ANSI-standard 1538VT100-style escape sequences, which are accepted by most modern 1539terminals, including @command{xterm}. (Hence, you can actually run 1540Emacs inside an Emacs Term window.) 1541 1542 The @code{term} face specifies the default appearance of text 1543in the terminal emulator (the default is the same appearance as the 1544@code{default} face). When terminal control codes are used to change 1545the appearance of text, these are represented in the terminal emulator 1546by the faces @code{term-color-black}, @code{term-color-red}, 1547@code{term-color-green}, @code{term-color-yellow} 1548@code{term-color-blue}, @code{term-color-magenta}, 1549@code{term-color-cyan}, @code{term-color-white}, 1550@code{term-color-underline}, and @code{term-color-bold}. 1551@xref{Faces}. 1552 1553 You can also use Term mode to communicate with a device connected to 1554a serial port. @xref{Serial Terminal}. 1555 1556 The file name used to load the subshell is determined the same way 1557as for Shell mode. To make multiple terminal emulators, rename the 1558buffer @file{*terminal*} to something different using @kbd{M-x 1559rename-uniquely}, just as with Shell mode. 1560 1561 Unlike Shell mode, Term mode does not track the current directory by 1562examining your input. But some shells can tell Term what the current 1563directory is. This is done automatically by @code{bash} version 1.15 1564and later. 1565 1566@node Term Mode 1567@subsection Term Mode 1568@cindex Term mode 1569@cindex mode, Term 1570 1571 To switch between line and char mode in Term mode, use these 1572commands: 1573 1574@table @kbd 1575@kindex C-c C-j @r{(Term mode)} 1576@findex term-line-mode 1577@item C-c C-j 1578Switch to line mode (@code{term-line-mode}). Do nothing if already in 1579line mode. 1580 1581@kindex C-c C-k @r{(Term mode)} 1582@findex term-char-mode 1583@item C-c C-k 1584Switch to char mode (@code{term-char-mode}). Do nothing if already in 1585char mode. 1586@end table 1587 1588 The following commands are only available in char mode: 1589 1590@table @kbd 1591@item C-c C-c 1592Send a literal @kbd{C-c} to the sub-shell 1593(@code{term-interrupt-subjob}). 1594 1595@item C-c @var{char} 1596This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For 1597example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which 1598is normally @samp{other-window}. 1599@end table 1600 1601@cindex paging in Term mode 1602 Term mode has a page-at-a-time feature. When enabled, it makes 1603output pause at the end of each screenful: 1604 1605@table @kbd 1606@kindex C-c C-q @r{(Term mode)} 1607@findex term-pager-toggle 1608@item C-c C-q 1609Toggle the page-at-a-time feature (@code{term-pager-toggle}). This 1610command works in both line and char modes. When the feature is 1611enabled, the mode-line displays the word @samp{page}, and each time 1612Term receives more than a screenful of output, it pauses and displays 1613@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next 1614screenful of output, or @kbd{?} to see your other options. The 1615interface is similar to the @code{more} program. 1616@end table 1617 1618@node Remote Host 1619@subsection Remote Host Shell 1620@cindex remote host 1621@cindex connecting to remote host 1622@cindex Telnet 1623@cindex Rlogin 1624 1625 You can login to a remote computer, using whatever commands you 1626would from a regular terminal (e.g., using the @command{ssh} or 1627@command{telnet} or @code{rlogin} commands), from a Term window. 1628 1629 A program that asks you for a password will normally suppress 1630echoing of the password, so the password will not show up in the 1631buffer. This will happen just as if you were using a real terminal, 1632if the buffer is in char mode. If it is in line mode, the password is 1633temporarily visible, but will be erased when you hit return. (This 1634happens automatically; there is no special password processing.) 1635 1636 When you log in to a different machine, you need to specify the type 1637of terminal you're using, by setting the @env{TERM} environment 1638variable in the environment for the remote login command. (If you use 1639bash, you do that by writing the variable assignment before the remote 1640login command, without a separating comma.) Terminal types 1641@samp{ansi} or @samp{vt100} will work on most systems. 1642 1643@node Serial Terminal 1644@subsection Serial Terminal 1645@cindex terminal, serial 1646@findex serial-term 1647 1648 If you have a device connected to a serial port of your computer, 1649you can communicate with it by typing @kbd{M-x serial-term}. This 1650command asks for a serial port name and speed, and switches to a new 1651Term mode buffer. Emacs communicates with the serial device through 1652this buffer just like it does with a terminal in ordinary Term mode. 1653 1654 The speed of the serial port is measured in bits per second. The 1655most common speed is 9600 bits per second. You can change the speed 1656interactively by clicking on the mode line. 1657 1658 A serial port can be configured even more by clicking on @samp{8N1} in 1659the mode line. By default, a serial port is configured as @samp{8N1}, 1660which means that each byte consists of 8 data bits, No parity check 1661bit, and 1 stopbit. 1662 1663 If the speed or the configuration is wrong, you cannot communicate 1664with your device and will probably only see garbage output in the 1665window. 1666 1667@node Emacs Server 1668@section Using Emacs as a Server 1669@pindex emacsclient 1670@cindex Emacs as a server 1671@cindex server, using Emacs as 1672@cindex @env{EDITOR} environment variable 1673 1674 Various programs can invoke your choice of editor to edit a 1675particular piece of text. For instance, version control programs 1676invoke an editor to enter version control logs (@pxref{Version 1677Control}), and the Unix @command{mail} utility invokes an editor to 1678enter a message to send. By convention, your choice of editor is 1679specified by the environment variable @env{EDITOR}. If you set 1680@env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an 1681inconvenient way---by starting a new Emacs process. This is 1682inconvenient because the new Emacs process doesn't share buffers, a 1683command history, or other kinds of information with any existing Emacs 1684process. 1685 1686 You can solve this problem by setting up Emacs as an @dfn{edit 1687server}, so that it ``listens'' for external edit requests and acts 1688accordingly. There are various ways to start an Emacs server: 1689 1690@itemize 1691@findex server-start 1692@item 1693Run the command @code{server-start} in an existing Emacs process: 1694either type @kbd{M-x server-start}, or put the expression 1695@code{(server-start)} in your init file (@pxref{Init File}). The 1696existing Emacs process is the server; when you exit Emacs, the server 1697dies with the Emacs process. 1698 1699@cindex daemon, Emacs 1700@item 1701Run Emacs as a @dfn{daemon}, using one of the @samp{--daemon} command-line 1702options. @xref{Initial Options}. When Emacs is started this way, it 1703calls @code{server-start} after initialization and does not open an 1704initial frame. It then waits for edit requests from clients. 1705 1706@item 1707Run the command @code{emacsclient} with the @samp{--alternate-editor=""} 1708command-line option. This starts an Emacs daemon only if no Emacs daemon 1709is already running. 1710 1711@cindex systemd unit file 1712@item 1713If your operating system uses @command{systemd} to manage startup, 1714you can automatically start Emacs in daemon mode when you login 1715using the supplied @dfn{systemd unit file}. To activate this: 1716@example 1717systemctl --user enable emacs 1718@end example 1719(If your Emacs was installed into a non-standard location, you may 1720need to copy the @file{emacs.service} file to a standard directory 1721such as @file{~/.config/systemd/user/}.) 1722 1723@cindex socket activation, systemd, Emacs 1724@item 1725An external process can invoke the Emacs server when a connection 1726event occurs upon a specified socket and pass the socket to the new 1727Emacs server process. An instance of this is the socket functionality 1728of @command{systemd}: the @command{systemd} service creates a socket and 1729listens for connections on it; when @command{emacsclient} connects to 1730it for the first time, @command{systemd} can launch the Emacs server 1731and hand over the socket to it for servicing @command{emacsclient} 1732connections. A setup to use this functionality could be: 1733 1734@file{~/.config/systemd/user/emacs.socket}: 1735@example 1736[Socket] 1737ListenStream=/path/to/.emacs.socket 1738DirectoryMode=0700 1739 1740[Install] 1741WantedBy=sockets.target 1742@end example 1743 1744(The @file{emacs.service} file described above must also be installed.) 1745 1746The @code{ListenStream} path will be the path that Emacs listens for 1747connections from @command{emacsclient}; this is a file of your choice. 1748@end itemize 1749 1750@cindex @env{TEXEDIT} environment variable 1751 Once an Emacs server is started, you can use a shell 1752command called @command{emacsclient} to connect to the Emacs process 1753and tell it to visit a file. You can then set the @env{EDITOR} 1754environment variable to @samp{emacsclient}, so that external programs 1755will use the existing Emacs process for editing.@footnote{Some 1756programs use a different environment variable; for example, to make 1757@TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment 1758variable to @samp{emacsclient +%d %s}.} 1759 1760@vindex server-name 1761 You can run multiple Emacs servers on the same machine by giving 1762each one a unique @dfn{server name}, using the variable 1763@code{server-name}. For example, @kbd{M-x set-variable @key{RET} 1764server-name @key{RET} "foo" @key{RET}} sets the server name to 1765@samp{foo}. The @code{emacsclient} program can specify a server by 1766name, using the @samp{-s} or the @samp{-f} option (@pxref{emacsclient 1767Options}), depending on whether or not the server uses a TCP socket 1768(@pxref{TCP Emacs server}). 1769 1770 If you want to run multiple Emacs daemons (@pxref{Initial Options}), 1771you can give each daemon its own server name like this: 1772 1773@example 1774 emacs --daemon=foo 1775@end example 1776 1777@findex server-stop-automatically 1778 The Emacs server can optionally be stopped automatically when 1779certain conditions are met. To do this, call the function 1780@code{server-stop-automatically} in your init file (@pxref{Init 1781File}), with one of the following arguments: 1782 1783@itemize 1784@item 1785With the argument @code{empty}, the server is stopped when it has no 1786clients, no unsaved file-visiting buffers and no running processes 1787anymore. 1788 1789@item 1790With the argument @code{delete-frame}, when the last client frame is 1791being closed, you are asked whether each unsaved file-visiting buffer 1792must be saved and each unfinished process can be stopped, and if so, 1793the server is stopped. 1794 1795@item 1796With the argument @code{kill-terminal}, when the last client frame is 1797being closed with @kbd{C-x C-c} (@code{save-buffers-kill-terminal}), 1798you are asked whether each unsaved file-visiting buffer must be saved 1799and each unfinished process can be stopped, and if so, the server is 1800stopped. 1801@end itemize 1802 1803@findex server-eval-at 1804 If you have defined a server by a unique server name, it is possible 1805to connect to the server from another Emacs instance and evaluate Lisp 1806expressions on the server, using the @code{server-eval-at} function. 1807For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the 1808expression @code{(+ 1 2)} on the @samp{foo} server, and returns 1809@code{3}. (If there is no server with that name, an error is 1810signaled.) Currently, this feature is mainly useful for developers. 1811 1812 If your operating system’s desktop environment is 1813@url{https://www.freedesktop.org/wiki/Specifications/,,freedesktop.org-compatible} 1814(which is true of most GNU/Linux and other recent Unix-like GUIs), you 1815may use the @samp{Emacs (Client)} menu entry to connect to an Emacs 1816server with @command{emacsclient}. The daemon starts if not 1817already running. 1818 1819@menu 1820* TCP Emacs server:: Listening to a TCP socket. 1821* Invoking emacsclient:: Connecting to the Emacs server. 1822* emacsclient Options:: Emacs client startup options. 1823@end menu 1824 1825@node TCP Emacs server 1826@subsection TCP Emacs server 1827@cindex TCP Emacs server 1828 1829@vindex server-use-tcp 1830 An Emacs server usually listens to connections on a local Unix 1831domain socket. Some operating systems, such as MS-Windows, do not 1832support local sockets; in that case, the server uses TCP sockets 1833instead. In some cases it is useful to have the server listen on a 1834TCP socket even if local sockets are supported, e.g., if you need to 1835contact the Emacs server from a remote machine. You can set 1836@code{server-use-tcp} to non-@code{nil} to have Emacs listen on a TCP 1837socket instead of a local socket. This is the default if your OS does 1838not support local sockets. 1839 1840@vindex server-host 1841@vindex server-port 1842 If the Emacs server is set to use TCP, it will by default listen on 1843a random port on the localhost interface. This can be changed to 1844another interface and/or a fixed port using the variables 1845@code{server-host} and @code{server-port}. 1846 1847@vindex server-auth-key 1848 A TCP socket is not subject to file system permissions. To retain 1849some control over which users can talk to an Emacs server over TCP 1850sockets, the @command{emacsclient} program must send an authorization 1851key to the server. This key is normally randomly generated by the 1852Emacs server. This is the recommended mode of operation. 1853 1854@findex server-generate-key 1855 If needed, you can set the authorization key to a static value by 1856setting the @code{server-auth-key} variable. The key must consist of 185764 ASCII printable characters except for space (this means characters 1858from @samp{!} to @samp{~}, or from decimal code 33 to 126). You can 1859use @kbd{M-x server-generate-key} to get a random key. 1860 1861@vindex server-auth-dir 1862@cindex server file 1863 When you start a TCP Emacs server, Emacs creates a @dfn{server file} 1864containing the TCP information to be used by @command{emacsclient} to 1865connect to the server. The variable @code{server-auth-dir} specifies 1866the default directory containing the server file; by default, this is 1867@file{~/.emacs.d/server/}. In the absence of a local socket with file 1868permissions, the permissions of this directory determine which users 1869can have their @command{emacsclient} processes talk to the Emacs 1870server. If @code{server-name} is an absolute file name, the server 1871file is created where specified by that file name. 1872 1873@vindex EMACS_SERVER_FILE@r{, environment variable} 1874 To tell @command{emacsclient} to connect to the server over TCP with 1875a specific server file, use the @samp{-f} or @samp{--server-file} 1876option, or set the @env{EMACS_SERVER_FILE} environment variable 1877(@pxref{emacsclient Options}). If @code{server-auth-dir} is set to a 1878non-standard value, or if @code{server-name} is set to an absolute 1879file name, @command{emacsclient} needs an absolute file name to the 1880server file, as the default @code{server-auth-dir} is hard-coded in 1881@command{emacsclient} to be used as the directory for resolving 1882relative filenames. 1883 1884@node Invoking emacsclient 1885@subsection Invoking @code{emacsclient} 1886@cindex @code{emacsclient} invocation 1887 1888 The simplest way to use the @command{emacsclient} program is to run 1889the shell command @samp{emacsclient @var{file}}, where @var{file} is a 1890file name. This connects to an Emacs server, and tells that Emacs 1891process to visit @var{file} in one of its existing frames---either a 1892graphical frame, or one in a text terminal (@pxref{Frames}). You 1893can then select that frame to begin editing. 1894 1895 If there is no Emacs server, the @command{emacsclient} program halts 1896with an error message (you can prevent this from happening by using 1897the @samp{--alternate-editor=""} option to @command{emacsclient}, 1898@pxref{emacsclient Options}). If the Emacs process has no existing 1899frame---which can happen if it was started as a daemon (@pxref{Emacs 1900Server})---then Emacs opens a frame on the terminal in which you 1901called @command{emacsclient}. 1902 1903 You can also force @command{emacsclient} to open a new frame on a 1904graphical display using the @samp{-c} option, or on a text terminal 1905using the @samp{-t} option. @xref{emacsclient Options}. 1906 1907 If you are running on a single text terminal, you can switch between 1908@command{emacsclient}'s shell and the Emacs server using one of two 1909methods: (i) run the Emacs server and @command{emacsclient} on 1910different virtual terminals, and switch to the Emacs server's virtual 1911terminal after calling @command{emacsclient}; or (ii) call 1912@command{emacsclient} from within the Emacs server itself, using Shell 1913mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode}); 1914@command{emacsclient} blocks only the subshell under Emacs, and you can 1915still use Emacs to edit the file. 1916 1917@kindex C-x # 1918@findex server-edit 1919 When you finish editing @var{file} in the Emacs server, type 1920@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file 1921and sends a message back to the @command{emacsclient} program, telling 1922it to exit. Programs that use @env{EDITOR} usually wait for the 1923editor---in this case @command{emacsclient}---to exit before doing 1924something else. 1925 1926@findex server-edit-abort 1927 If you want to abandon the edit instead, use the @w{@kbd{M-x 1928server-edit-abort}} command. This sends a message back to the 1929@command{emacsclient} program, telling it to exit with abnormal exit 1930status, and doesn't save any buffers. 1931 1932 You can also call @command{emacsclient} with multiple file name 1933arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the 1934Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs 1935selects the buffer visiting @var{file1}, and buries the other buffers 1936at the bottom of the buffer list (@pxref{Buffers}). The 1937@command{emacsclient} program exits once all the specified files are 1938finished (i.e., once you have typed @kbd{C-x #} in each server 1939buffer). 1940 1941@vindex server-kill-new-buffers 1942@vindex server-temp-file-regexp 1943 Finishing with a server buffer also kills the buffer, unless it 1944already existed in the Emacs session before the server was asked to 1945create it. However, if you set @code{server-kill-new-buffers} to 1946@code{nil}, then a different criterion is used: finishing with a 1947server buffer kills it if the file name matches the regular expression 1948@code{server-temp-file-regexp}. This is set up to distinguish certain 1949temporary files. 1950 1951 Each @kbd{C-x #} checks for other pending external requests to edit 1952various files, and selects the next such file. You can switch to a 1953server buffer manually if you wish; you don't have to arrive at it 1954with @kbd{C-x #}. But @kbd{C-x #} is the way to tell 1955@command{emacsclient} that you are finished. 1956 1957@vindex server-window 1958 If you set the value of the variable @code{server-window} to a 1959window or a frame, @kbd{C-x #} always displays the next server buffer 1960in that window or in that frame. 1961 1962@vindex server-client-instructions 1963 When @command{emacsclient} connects, the server will normally output 1964a message that says how to exit the client frame. If 1965@code{server-client-instructions} is set to @code{nil}, this message 1966is inhibited. 1967 1968@node emacsclient Options 1969@subsection @code{emacsclient} Options 1970@cindex @code{emacsclient} options 1971 1972 You can pass some optional arguments to the @command{emacsclient} 1973program, such as: 1974 1975@example 1976emacsclient -c +12 @var{file1} +4:3 @var{file2} 1977@end example 1978 1979@noindent 1980The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments 1981specify line numbers, or line and column numbers, for the next file 1982argument. These behave like the command line arguments for Emacs 1983itself. @xref{Action Arguments}. 1984 1985 The other optional arguments recognized by @command{emacsclient} are 1986listed below: 1987 1988@table @samp 1989@item -a @var{command} 1990@itemx --alternate-editor=@var{command} 1991Specify a shell command to run if @command{emacsclient} fails to 1992contact Emacs. This is useful when running @code{emacsclient} in a 1993script. The command may include arguments, which may be quoted "like 1994this". Currently, escaping of quotes is not supported. 1995 1996As a special exception, if @var{command} is the empty string, then 1997@command{emacsclient} starts Emacs in daemon mode (as @samp{emacs 1998--daemon}) and then tries connecting again. 1999 2000@cindex @env{ALTERNATE_EDITOR} environment variable 2001The environment variable @env{ALTERNATE_EDITOR} has the same effect as 2002the @samp{-a} option. If both are present, the latter takes 2003precedence. 2004 2005@cindex client frame 2006@item -c 2007@itemx --create-frame 2008Create a new graphical @dfn{client frame}, instead of using an 2009existing Emacs frame. See below for the special behavior of @kbd{C-x 2010C-c} in a client frame. If Emacs cannot create a new graphical frame 2011(e.g., if it cannot connect to the X server), it tries to create a 2012text terminal client frame, as though you had supplied the @samp{-t} 2013option instead. 2014 2015On MS-Windows, a single Emacs session cannot display frames on both 2016graphical and text terminals, nor on multiple text terminals. Thus, 2017if the Emacs server is running on a text terminal, the @samp{-c} 2018option, like the @samp{-t} option, creates a new frame in the server's 2019current text terminal. @xref{Windows Startup}. 2020 2021If you omit a filename argument while supplying the @samp{-c} option, 2022the new frame displays the @file{*scratch*} buffer by default. You 2023can customize this behavior with the variable @code{initial-buffer-choice} 2024(@pxref{Entering Emacs}). 2025 2026@item -r 2027@itemx --reuse-frame 2028Create a new graphical client frame if none exists, otherwise use an 2029existing Emacs frame. 2030 2031@item -F @var{alist} 2032@itemx --frame-parameters=@var{alist} 2033Set the parameters for a newly-created graphical frame 2034(@pxref{Frame Parameters}). 2035 2036@item -d @var{display} 2037@itemx --display=@var{display} 2038Tell Emacs to open the given files on the X display @var{display} 2039(assuming there is more than one X display available). 2040 2041@item -e 2042@itemx --eval 2043Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some 2044files. When this option is given, the arguments to 2045@command{emacsclient} are interpreted as a list of expressions to 2046evaluate, @emph{not} as a list of files to visit. 2047 2048@item -f @var{server-file} 2049@itemx --server-file=@var{server-file} 2050Specify a server file (@pxref{TCP Emacs server}) for connecting to an 2051Emacs server via TCP@. Alternatively, you can set the 2052@env{EMACS_SERVER_FILE} environment variable to point to the server 2053file. (The command-line option overrides the environment variable.) 2054 2055An Emacs server usually uses a local socket to listen for connections, 2056but also supports connections over TCP@. To connect to a TCP Emacs 2057server, @command{emacsclient} needs to read a @dfn{server file} 2058containing the connection details of the Emacs server. The name of 2059this file is specified with this option, either as a file name 2060relative to @file{~/.emacs.d/server} or as an absolute file name. 2061@xref{TCP Emacs server}. 2062 2063@item -n 2064@itemx --no-wait 2065Let @command{emacsclient} exit immediately, instead of waiting until 2066all server buffers are finished. You can take as long as you like to 2067edit the server buffers within Emacs, and they are @emph{not} killed 2068when you type @kbd{C-x #} in them. 2069 2070@item --parent-id @var{id} 2071Open an @command{emacsclient} frame as a client frame in the parent X 2072window with id @var{id}, via the XEmbed protocol. Currently, this 2073option is mainly useful for developers. 2074 2075@item -q 2076@itemx --quiet 2077Do not let @command{emacsclient} display messages about waiting for 2078Emacs or connecting to remote server sockets. 2079 2080@item -u 2081@itemx --suppress-output 2082Do not let @command{emacsclient} display results returned from the 2083server. Mostly useful in combination with @samp{-e} when the 2084evaluation performed is for side-effect rather than result. 2085 2086@item -s @var{server-name} 2087@itemx --socket-name=@var{server-name} 2088Connect to the Emacs server named @var{server-name}. (This option is 2089not supported on MS-Windows.) The server name is given by the 2090variable @code{server-name} on the Emacs server. If this option is 2091omitted, @command{emacsclient} connects to the default socket. 2092If you set @code{server-name} of the Emacs server to an absolute file 2093name, give the same absolute file name as @var{server-name} to this 2094option to instruct @command{emacsclient} to connect to that server. 2095You need to use this option if you started Emacs as daemon 2096(@pxref{Initial Options}) and specified the name for the server 2097started by the daemon. 2098 2099Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment 2100variable to point to the server socket. (The command-line option 2101overrides the environment variable.) 2102 2103@item -t 2104@itemx --tty 2105@itemx -nw 2106Create a new client frame on the current text terminal, instead of 2107using an existing Emacs frame. This behaves just like the @samp{-c} 2108option, described above, except that it creates a text terminal frame 2109(@pxref{Non-Window Terminals}). 2110 2111On MS-Windows, @samp{-t} behaves just like @samp{-c} if the Emacs 2112server is using the graphical display, but if the Emacs server is 2113running on a text terminal, it creates a new frame in the current text 2114terminal. 2115 2116@item -T @var{tramp-prefix} 2117@itemx --tramp-prefix=@var{tramp-prefix} 2118Set the prefix to add to filenames for Emacs to locate files on remote 2119machines (@pxref{Remote Files}) using TRAMP (@pxref{Top, The Tramp 2120Manual,, tramp, The Tramp Manual}). This is mostly useful in 2121combination with using the Emacs server over TCP (@pxref{TCP Emacs 2122server}). By ssh-forwarding the listening port and making the 2123@var{server-file} available on a remote machine, programs on the 2124remote machine can use @command{emacsclient} as the value for the 2125@env{EDITOR} and similar environment variables, but instead of talking 2126to an Emacs server on the remote machine, the files will be visited in 2127the local Emacs session using TRAMP. 2128 2129@vindex EMACSCLIENT_TRAMP@r{, environment variable} 2130Setting the environment variable @env{EMACSCLIENT_TRAMP} has the same 2131effect as using the @samp{-T} option. If both are specified, the 2132command-line option takes precedence. 2133 2134For example, assume two hosts, @samp{local} and @samp{remote}, and 2135that the local Emacs listens on tcp port 12345. Assume further that 2136@file{/home} is on a shared file system, so that the server file 2137@file{~/.emacs.d/server/server} is readable on both hosts. 2138 2139@example 2140local$ ssh -R12345:localhost:12345 remote 2141remote$ export EDITOR="emacsclient \ 2142 --server-file=server \ 2143 --tramp=/ssh:remote:" 2144remote$ $EDITOR /tmp/foo.txt #Should open in local emacs. 2145@end example 2146 2147@end table 2148 2149 The new graphical or text terminal frames created by the @samp{-c} 2150or @samp{-t} options are considered @dfn{client frames}. Any new 2151frame that you create from a client frame is also considered a client 2152frame. If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) 2153in a client frame, that command does not kill the Emacs session as it 2154normally does (@pxref{Exiting}). Instead, Emacs deletes the client 2155frame; furthermore, if the client frame has an @command{emacsclient} 2156waiting to regain control (i.e., if you did not supply the @samp{-n} 2157option), Emacs deletes all other frames of the same client, and marks 2158the client's server buffers as finished, as though you had typed 2159@kbd{C-x #} in all of them. If it so happens that there are no 2160remaining frames after the client frame(s) are deleted, the Emacs 2161session exits. 2162 2163 As an exception, when Emacs is started as a daemon, all frames are 2164considered client frames, and @kbd{C-x C-c} never kills Emacs. To 2165kill a daemon session, type @kbd{M-x kill-emacs}. 2166 2167 Note that the @samp{-t} and @samp{-n} options are contradictory: 2168@samp{-t} says to take control of the current text terminal to create 2169a new client frame, while @samp{-n} says not to take control of the 2170text terminal. If you supply both options, Emacs visits the specified 2171files(s) in an existing frame rather than a new client frame, negating 2172the effect of @samp{-t}. 2173 2174@node Printing 2175@section Printing Hard Copies 2176@cindex hardcopy 2177@cindex printing 2178 2179 Emacs provides commands for printing hardcopies of either an entire 2180buffer or part of one. You can invoke the printing commands directly, 2181as detailed below, or using the @samp{File} menu on the menu bar. 2182 2183@findex htmlfontify-buffer 2184 Aside from the commands described in this section, you can also 2185print hardcopies from Dired (@pxref{Operating on Files}) and the diary 2186(@pxref{Displaying the Diary}). You can also ``print'' an Emacs 2187buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which 2188converts the current buffer to a HTML file, replacing Emacs faces with 2189CSS-based markup. Furthermore, Org mode allows you to print Org 2190files to a variety of formats, such as PDF (@pxref{Org Mode}). 2191 2192@table @kbd 2193@item M-x print-buffer 2194Print hardcopy of current buffer with page headings containing the 2195file name and page number. 2196@item M-x lpr-buffer 2197Print hardcopy of current buffer without page headings. 2198@item M-x print-region 2199Like @code{print-buffer} but print only the current region. 2200@item M-x lpr-region 2201Like @code{lpr-buffer} but print only the current region. 2202@end table 2203 2204@findex print-buffer 2205@findex print-region 2206@findex lpr-buffer 2207@findex lpr-region 2208@vindex lpr-switches 2209@vindex lpr-commands 2210 On most operating systems, the above hardcopy commands submit files 2211for printing by calling the @command{lpr} program. To change the 2212printer program, customize the variable @code{lpr-command}. To 2213specify extra switches to give the printer program, customize the list 2214variable @code{lpr-switches}. Its value should be a list of option 2215strings, each of which should start with @samp{-} (e.g., the option 2216string @code{"-w80"} specifies a line width of 80 columns). The 2217default is the empty list, @code{nil}. 2218 2219@vindex printer-name 2220@vindex lpr-printer-switch 2221 To specify the printer to use, set the variable @code{printer-name}. 2222The default, @code{nil}, specifies the default printer. If you set it 2223to a printer name (a string), that name is passed to @command{lpr} 2224with the @samp{-P} switch; if you are not using @command{lpr}, you 2225should specify the switch with @code{lpr-printer-switch}. 2226 2227@vindex lpr-headers-switches 2228@vindex lpr-add-switches 2229 The variable @code{lpr-headers-switches} similarly specifies the 2230extra switches to use to make page headers. The variable 2231@code{lpr-add-switches} controls whether to supply @samp{-T} and 2232@samp{-J} options (suitable for @command{lpr}) to the printer program: 2233@code{nil} means don't add them (this should be the value if your 2234printer program is not compatible with @command{lpr}). 2235 2236@menu 2237* PostScript:: Printing buffers or regions as PostScript. 2238* PostScript Variables:: Customizing the PostScript printing commands. 2239* Printing Package:: An optional advanced printing interface. 2240@end menu 2241 2242@node PostScript 2243@subsection PostScript Hardcopy 2244 2245 These commands convert buffer contents to PostScript, 2246either printing it or leaving it in another Emacs buffer. 2247 2248@table @kbd 2249@item M-x ps-print-buffer 2250Print hardcopy of the current buffer in PostScript form. 2251@item M-x ps-print-region 2252Print hardcopy of the current region in PostScript form. 2253@item M-x ps-print-buffer-with-faces 2254Print hardcopy of the current buffer in PostScript form, showing the 2255faces used in the text by means of PostScript features. 2256@item M-x ps-print-region-with-faces 2257Print hardcopy of the current region in PostScript form, showing the 2258faces used in the text. 2259@item M-x ps-spool-buffer 2260Generate and spool a PostScript image for the current buffer text. 2261@item M-x ps-spool-region 2262Generate and spool a PostScript image for the current region. 2263@item M-x ps-spool-buffer-with-faces 2264Generate and spool a PostScript image for the current buffer, showing the faces used. 2265@item M-x ps-spool-region-with-faces 2266Generate and spool a PostScript image for the current region, showing the faces used. 2267@item M-x ps-despool 2268Send the spooled PostScript to the printer. 2269@item M-x handwrite 2270Generate/print PostScript for the current buffer as if handwritten. 2271@end table 2272 2273@findex ps-print-region 2274@findex ps-print-buffer 2275@findex ps-print-region-with-faces 2276@findex ps-print-buffer-with-faces 2277 The @code{ps-print-buffer} and @code{ps-print-region} commands print 2278buffer contents in PostScript form. One command prints the entire 2279buffer; the other, just the region. The commands 2280@code{ps-print-buffer-with-faces} and 2281@code{ps-print-region-with-faces} behave similarly, but use PostScript 2282features to show the faces (fonts and colors) of the buffer text. 2283 2284 Interactively, when you use a prefix argument (@kbd{C-u}), these commands 2285prompt the user for a file name, and save the PostScript image in that file 2286instead of sending it to the printer. 2287 2288@findex ps-spool-region 2289@findex ps-spool-buffer 2290@findex ps-spool-region-with-faces 2291@findex ps-spool-buffer-with-faces 2292 The commands whose names have @samp{spool} instead of @samp{print}, 2293generate the PostScript output in an Emacs buffer instead of sending 2294it to the printer. 2295 2296@findex ps-despool 2297 Use the command @code{ps-despool} to send the spooled images to the 2298printer. This command sends the PostScript generated by 2299@samp{-spool-} commands (see commands above) to the printer. With a 2300prefix argument (@kbd{C-u}), it prompts for a file name, and saves the 2301spooled PostScript image in that file instead of sending it to the 2302printer. 2303 2304@findex handwrite 2305@cindex handwriting 2306 @kbd{M-x handwrite} is more frivolous. It generates a PostScript 2307rendition of the current buffer as a cursive handwritten document. It 2308can be customized in group @code{handwrite}. This function only 2309supports ISO 8859-1 characters. 2310 2311@node PostScript Variables 2312@subsection Variables for PostScript Hardcopy 2313 2314@vindex ps-lpr-command 2315@vindex ps-lpr-switches 2316@vindex ps-printer-name 2317 All the PostScript hardcopy commands use the variables 2318@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print 2319the output. @code{ps-lpr-command} specifies the command name to run, 2320@code{ps-lpr-switches} specifies command line options to use, and 2321@code{ps-printer-name} specifies the printer. If you don't set the 2322first two variables yourself, they take their initial values from 2323@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} 2324is @code{nil}, @code{printer-name} is used. 2325 2326@vindex ps-print-header 2327 The variable @code{ps-print-header} controls whether these commands 2328add header lines to each page---set it to @code{nil} to turn headers 2329off. 2330 2331@cindex color emulation on black-and-white printers 2332@vindex ps-print-color-p 2333 If your printer doesn't support colors, you should turn off color 2334processing by setting @code{ps-print-color-p} to @code{nil}. By 2335default, if the display supports colors, Emacs produces hardcopy 2336output with color information; on black-and-white printers, colors are 2337emulated with shades of gray. This might produce barely-readable or 2338even illegible output, even if your screen colors only use shades of 2339gray. 2340 2341@vindex ps-black-white-faces 2342 Alternatively, you can set @code{ps-print-color-p} to @code{black-white} 2343to have colors display better on black/white printers. This works by 2344using information in @code{ps-black-white-faces} to express colors by 2345customizable list of shades of gray, augmented by bold and italic 2346face attributes. 2347 2348@vindex ps-use-face-background 2349 By default, PostScript printing ignores the background colors of the 2350faces, unless the variable @code{ps-use-face-background} is 2351non-@code{nil}. This is to avoid unwanted interference with the zebra 2352stripes and background image/text. 2353 2354@vindex ps-paper-type 2355@vindex ps-page-dimensions-database 2356 The variable @code{ps-paper-type} specifies which size of paper to 2357format for; legitimate values include @code{a4}, @code{a3}, 2358@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, 2359@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, 2360@code{tabloid}. The default is @code{letter}. You can define 2361additional paper sizes by changing the variable 2362@code{ps-page-dimensions-database}. 2363 2364@vindex ps-landscape-mode 2365 The variable @code{ps-landscape-mode} specifies the orientation of 2366printing on the page. The default is @code{nil}, which stands for 2367portrait mode. Any non-@code{nil} value specifies landscape 2368mode. 2369 2370@vindex ps-number-of-columns 2371 The variable @code{ps-number-of-columns} specifies the number of 2372columns; it takes effect in both landscape and portrait mode. The 2373default is 1. 2374 2375@vindex ps-font-family 2376@vindex ps-font-size 2377@vindex ps-font-info-database 2378 The variable @code{ps-font-family} specifies which font family to use 2379for printing ordinary text. Legitimate values include @code{Courier}, 2380@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and 2381@code{Times}. The variable @code{ps-font-size} specifies the size of 2382the font for ordinary text and defaults to 8.5 points. The value of 2383@code{ps-font-size} can also be a cons of 2 floats: one for landscape 2384mode, the other for portrait mode. 2385 2386@vindex ps-multibyte-buffer 2387@cindex Intlfonts for PostScript printing 2388@cindex fonts for PostScript printing 2389 Emacs supports more scripts and characters than a typical PostScript 2390printer. Thus, some of the characters in your buffer might not be 2391printable using the fonts built into your printer. You can augment 2392the fonts supplied with the printer with those from the GNU Intlfonts 2393package, or you can instruct Emacs to use Intlfonts exclusively. The 2394variable @code{ps-multibyte-buffer} controls this: the default value, 2395@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 2396characters; a value of @code{non-latin-printer} is for printers which 2397have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean 2398characters built into them. A value of @code{bdf-font} arranges for 2399the BDF fonts from the Intlfonts package to be used for @emph{all} 2400characters. Finally, a value of @code{bdf-font-except-latin} 2401instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 2402characters, and Intlfonts BDF fonts for the rest. 2403 2404@vindex bdf-directory-list 2405 To be able to use the BDF fonts, Emacs needs to know where to find 2406them. The variable @code{bdf-directory-list} holds the list of 2407directories where Emacs should look for the fonts; the default value 2408includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. 2409 2410 Many other customization variables for these commands are defined and 2411described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. 2412 2413@node Printing Package 2414@subsection Printing Package 2415@cindex Printing package 2416 2417 The basic Emacs facilities for printing hardcopy can be extended 2418using the Printing package. This provides an easy-to-use interface 2419for choosing what to print, previewing PostScript files before 2420printing, and setting various printing options such as print headers, 2421landscape or portrait modes, duplex modes, and so forth. On GNU/Linux 2422or Unix systems, the Printing package relies on the @file{gs} and 2423@file{gv} utilities, which are distributed as part of the GhostScript 2424program. On MS-Windows, the @file{gstools} port of Ghostscript can be 2425used. 2426 2427@findex pr-interface 2428 To use the Printing package, add @code{(require 'printing)} to your 2429init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. 2430This function replaces the usual printing commands in the menu bar 2431with a @samp{Printing} submenu that contains various printing options. 2432You can also type @kbd{M-x pr-interface @key{RET}}; this creates a 2433@file{*Printing Interface*} buffer, similar to a customization buffer, 2434where you can set the printing options. After selecting what and how 2435to print, you start the print job using the @samp{Print} button (click 2436@kbd{mouse-2} on it, or move point over it and type @key{RET}). For 2437further information on the various options, use the @samp{Interface 2438Help} button. 2439 2440@node Sorting 2441@section Sorting Text 2442@cindex sorting 2443 2444 Emacs provides several commands for sorting text in the buffer. All 2445operate on the contents of the region. 2446They divide the text of the region into many @dfn{sort records}, 2447identify a @dfn{sort key} for each record, and then reorder the records 2448into the order determined by the sort keys. The records are ordered so 2449that their keys are in alphabetical order, or, for numeric sorting, in 2450numeric order. In alphabetic sorting, all upper-case letters @samp{A} 2451through @samp{Z} come before lower-case @samp{a}, in accordance with the 2452@acronym{ASCII} character sequence (but @code{sort-fold-case}, 2453described below, can change that). 2454 2455 The various sort commands differ in how they divide the text into sort 2456records and in which part of each record is used as the sort key. Most of 2457the commands make each line a separate sort record, but some commands use 2458paragraphs or pages as sort records. Most of the sort commands use each 2459entire sort record as its own sort key, but some use only a portion of the 2460record as the sort key. 2461 2462@findex sort-lines 2463@findex sort-paragraphs 2464@findex sort-pages 2465@findex sort-fields 2466@findex sort-numeric-fields 2467@vindex sort-numeric-base 2468@table @kbd 2469@item M-x sort-lines 2470Divide the region into lines, and sort by comparing the entire 2471text of a line. A numeric argument means sort into descending order. 2472 2473@item M-x sort-paragraphs 2474Divide the region into paragraphs, and sort by comparing the entire 2475text of a paragraph (except for leading blank lines). A numeric 2476argument means sort into descending order. 2477 2478@item M-x sort-pages 2479Divide the region into pages, and sort by comparing the entire 2480text of a page (except for leading blank lines). A numeric 2481argument means sort into descending order. 2482 2483@item M-x sort-fields 2484Divide the region into lines, and sort by comparing the contents of 2485one field in each line. Fields are defined as separated by 2486whitespace, so the first run of consecutive non-whitespace characters 2487in a line constitutes field 1, the second such run constitutes field 24882, etc. 2489 2490Specify which field to sort by with a numeric argument: 1 to sort by 2491field 1, etc.; the default is 1. A negative argument means count 2492fields from the right instead of from the left; thus, minus 1 means 2493sort by the last field. If several lines have identical contents in 2494the field being sorted, they keep the same relative order that they 2495had in the original buffer. 2496 2497@item M-x sort-numeric-fields 2498Like @kbd{M-x sort-fields} except the specified field is converted 2499to an integer for each line, and the numbers are compared. @samp{10} 2500comes before @samp{2} when considered as text, but after it when 2501considered as a number. By default, numbers are interpreted according 2502to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or 2503@samp{0} are interpreted as hexadecimal and octal, respectively. 2504 2505@item M-x sort-columns 2506Like @kbd{M-x sort-fields} except that the text within each line 2507used for comparison comes from a fixed range of columns. With a 2508prefix argument, sort in reverse order. See below for more details 2509on this command. 2510 2511@findex reverse-region 2512@item M-x reverse-region 2513Reverse the order of the lines in the region. This is useful for 2514sorting into descending order by fields, since those sort 2515commands do not have a feature for doing that. 2516@end table 2517 2518 For example, if the buffer contains this: 2519 2520@smallexample 2521On systems where clash detection (locking of files being edited) is 2522implemented, Emacs also checks the first time you modify a buffer 2523whether the file has changed on disk since it was last visited or 2524saved. If it has, you are asked to confirm that you want to change 2525the buffer. 2526@end smallexample 2527 2528@noindent 2529applying @kbd{M-x sort-lines} to the entire buffer produces this: 2530 2531@smallexample 2532On systems where clash detection (locking of files being edited) is 2533implemented, Emacs also checks the first time you modify a buffer 2534saved. If it has, you are asked to confirm that you want to change 2535the buffer. 2536whether the file has changed on disk since it was last visited or 2537@end smallexample 2538 2539@noindent 2540where the upper-case @samp{O} sorts before all lower-case letters. If 2541you use @kbd{C-u 2 M-x sort-fields} instead, you get this: 2542 2543@smallexample 2544implemented, Emacs also checks the first time you modify a buffer 2545saved. If it has, you are asked to confirm that you want to change 2546the buffer. 2547On systems where clash detection (locking of files being edited) is 2548whether the file has changed on disk since it was last visited or 2549@end smallexample 2550 2551@noindent 2552where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, 2553@samp{systems} and @samp{the}. 2554 2555@findex sort-columns 2556 @kbd{M-x sort-columns} requires more explanation. You specify the 2557columns by putting point at one of the columns and the mark at the other 2558column. Because this means you cannot put point or the mark at the 2559beginning of the first line of the text you want to sort, this command 2560uses an unusual definition of ``region'': all of the line point is in is 2561considered part of the region, and so is all of the line the mark is in, 2562as well as all the lines in between. 2563 2564 For example, to sort a table by information found in columns 10 to 15, 2565you could put the mark on column 10 in the first line of the table, and 2566point on column 15 in the last line of the table, and then run 2567@code{sort-columns}. Equivalently, you could run it with the mark on 2568column 15 in the first line and point on column 10 in the last line. 2569 2570 This can be thought of as sorting the rectangle specified by point and 2571the mark, except that the text on each line to the left or right of the 2572rectangle moves along with the text inside the rectangle. 2573@xref{Rectangles}. 2574 2575@vindex sort-fold-case 2576 Many of the sort commands ignore case differences when comparing, if 2577@code{sort-fold-case} is non-@code{nil}. 2578 2579@c Picture Mode documentation 2580@ifnottex 2581@include picture-xtra.texi 2582@end ifnottex 2583 2584 2585@node Editing Binary Files 2586@section Editing Binary Files 2587 2588@cindex Hexl mode 2589@cindex mode, Hexl 2590@cindex editing binary files 2591@cindex hex editing 2592 There is a special major mode for editing binary files: Hexl mode. To 2593use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit 2594the file. This command converts the file's contents to hexadecimal and 2595lets you edit the translation. When you save the file, it is converted 2596automatically back to binary. 2597 2598 You can also use @kbd{M-x hexl-mode} to translate an existing buffer 2599into hex. This is useful if you visit a file normally and then discover 2600it is a binary file. 2601 2602 Inserting text always overwrites in Hexl mode. This is to reduce 2603the risk of accidentally spoiling the alignment of data in the file. 2604Ordinary text characters insert themselves (i.e., overwrite with 2605themselves). There are commands for insertion of special characters 2606by their code. Most cursor motion keys, as well as @kbd{C-x C-s}, are 2607bound in Hexl mode to commands that produce the same effect. Here is 2608a list of other important commands special to Hexl mode: 2609 2610@c I don't think individual index entries for these commands are useful--RMS. 2611@table @kbd 2612@item C-M-d 2613Insert a byte with a code typed in decimal. 2614 2615@item C-M-o 2616Insert a byte with a code typed in octal. 2617 2618@item C-M-x 2619Insert a byte with a code typed in hex. 2620 2621@item C-M-a 2622Move to the beginning of a 512-byte page. 2623 2624@item C-M-e 2625Move to the end of a 512-byte page. 2626 2627@item C-x [ 2628Move to the beginning of a 1k-byte page. 2629 2630@item C-x ] 2631Move to the end of a 1k-byte page. 2632 2633@item M-g 2634Move to an address specified in hex. 2635 2636@item M-j 2637Move to an address specified in decimal. 2638 2639@item C-c C-c 2640Leave Hexl mode, going back to the major mode this buffer had before you 2641invoked @code{hexl-mode}. 2642@end table 2643 2644@noindent 2645Other Hexl commands let you insert strings (sequences) of binary 2646bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a 2647hexl- @key{TAB}} for details. 2648 2649 Hexl mode can also be used for editing text files. This could come 2650in handy if the text file includes unusual characters or uses unusual 2651encoding (@pxref{Coding Systems}). For this purpose, Hexl commands 2652that insert bytes can also insert @acronym{ASCII} and 2653non-@acronym{ASCII} characters, including multibyte characters. To 2654edit a text file with Hexl, visit the file as usual, and then type 2655@w{@kbd{M-x hexl-mode @key{RET}}} to switch to Hexl mode. You can now 2656insert text characters by typing them. However, inserting multibyte 2657characters requires special care, to avoid the danger of creating 2658invalid multibyte sequences: you should start typing such characters 2659when point is on the first byte of a multibyte sequence in the file. 2660 2661@node Saving Emacs Sessions 2662@section Saving Emacs Sessions 2663@cindex saving sessions 2664@cindex restore session 2665@cindex remember editing session 2666@cindex reload files 2667@cindex desktop 2668 2669@vindex desktop-restore-frames 2670 Use the desktop library to save the state of Emacs from one session 2671to another. Once you save the Emacs @dfn{desktop}---the buffers, 2672their file names, major modes, buffer positions, and so on---then 2673subsequent Emacs sessions reload the saved desktop. By default, 2674the desktop also tries to save the frame and window configuration. 2675To disable this, set @code{desktop-restore-frames} to @code{nil}. 2676(See that variable's documentation for some related options 2677that you can customize to fine-tune this behavior.) 2678 2679@vindex desktop-files-not-to-save 2680Information about buffers visiting remote files is not saved by 2681default. Customize the variable @code{desktop-files-not-to-save} to 2682change this. 2683 2684@vindex frameset-filter-alist 2685 When the desktop restores the frame and window configuration, it 2686uses the recorded values of frame parameters, disregarding any 2687settings for those parameters you have in your init file (@pxref{Init 2688File}). This means that frame parameters such as fonts and faces for 2689the restored frames will come from the desktop file, where they were 2690saved when you exited your previous Emacs session; any settings for 2691those parameters in your init file will be ignored. To disable this, 2692customize the value of @code{frameset-filter-alist} to filter out the 2693frame parameters you don't want to be restored. 2694 2695@findex desktop-save 2696@vindex desktop-save-mode 2697 You can save the desktop manually with the command @kbd{M-x 2698desktop-save}. You can also enable automatic saving of the desktop 2699when you exit Emacs, and automatic restoration of the last saved 2700desktop when Emacs starts: use the Customization buffer (@pxref{Easy 2701Customization}) to set @code{desktop-save-mode} to @code{t} for future 2702sessions, or add this line in your init file (@pxref{Init File}): 2703 2704@example 2705(desktop-save-mode 1) 2706@end example 2707 2708@findex desktop-change-dir 2709@findex desktop-revert 2710@vindex desktop-path 2711 If you turn on @code{desktop-save-mode} in your init file, then when 2712Emacs starts, it looks for a saved desktop in the current directory. 2713(More precisely, it looks in the directories specified by 2714@code{desktop-path}, and uses the first desktop it finds.) 2715Thus, you can have separate saved desktops in different directories, 2716and the starting directory determines which one Emacs reloads. You 2717can save the current desktop and reload one saved in another directory 2718by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x 2719desktop-revert} reverts to the desktop previously reloaded. 2720 2721 Specify the option @samp{--no-desktop} on the command line when you 2722don't want it to reload any saved desktop. This turns off 2723@code{desktop-save-mode} for the current session. Starting Emacs with 2724the @samp{--no-init-file} option also disables desktop reloading, 2725since it bypasses the init file, where @code{desktop-save-mode} is 2726usually turned on. 2727 2728@vindex desktop-restore-eager 2729 By default, all the buffers in the desktop are restored in one go. 2730However, this may be slow if there are a lot of buffers in the 2731desktop. You can specify the maximum number of buffers to restore 2732immediately with the variable @code{desktop-restore-eager}; the 2733remaining buffers are restored lazily, when Emacs is idle. 2734 2735@findex desktop-clear 2736@vindex desktop-globals-to-clear 2737@vindex desktop-clear-preserve-buffers-regexp 2738 Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills 2739all buffers except for internal ones, and clears the global variables 2740listed in @code{desktop-globals-to-clear}. If you want this to 2741preserve certain buffers, customize the variable 2742@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular 2743expression matching the names of buffers not to kill. 2744 2745 If you want to save minibuffer history from one session to 2746another, use the @code{savehist} library. 2747 2748@vindex desktop-auto-save-timeout 2749 While Emacs runs with @code{desktop-save-mode} turned on, it by 2750default auto-saves the desktop whenever any of it changes. The 2751variable @code{desktop-auto-save-timeout} determines how frequently 2752Emacs checks for modifications to your desktop. 2753 2754@vindex desktop-load-locked-desktop 2755 The file in which Emacs saves the desktop is locked while the 2756session runs, to avoid inadvertently overwriting it from another Emacs 2757session. That lock is normally removed when Emacs exits, but if Emacs 2758or your system crashes, the lock stays, and when you restart Emacs, it 2759will by default ask you whether to use the locked desktop file. You 2760can avoid the question by customizing the variable 2761@code{desktop-load-locked-desktop} to either @code{nil}, which means 2762never load the desktop in this case, or @code{t}, which means load the 2763desktop without asking. 2764 2765@cindex desktop restore in daemon mode 2766 When Emacs starts in daemon mode, it cannot ask you any questions, 2767so if it finds the desktop file locked, it will not load it, unless 2768@code{desktop-load-locked-desktop} is @code{t}. Note that restoring 2769the desktop in daemon mode is somewhat problematic for other reasons: 2770e.g., the daemon cannot use GUI features, so parameters such as frame 2771position, size, and decorations cannot be restored. For that reason, 2772you may wish to delay restoring the desktop in daemon mode until the 2773first client connects, by calling @code{desktop-read} in a hook 2774function that you add to @code{server-after-make-frame-hook} 2775(@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}). 2776 2777@node Recursive Edit 2778@section Recursive Editing Levels 2779@cindex recursive editing level 2780@cindex editing level, recursive 2781 2782 A @dfn{recursive edit} is a situation in which you are using Emacs 2783commands to perform arbitrary editing while in the middle of another 2784Emacs command. For example, when you type @kbd{C-r} inside of a 2785@code{query-replace}, you enter a recursive edit in which you can change 2786the current buffer. On exiting from the recursive edit, you go back to 2787the @code{query-replace}. @xref{Query Replace}. 2788 2789@kindex C-M-c 2790@findex exit-recursive-edit 2791@cindex exiting recursive edit 2792 @dfn{Exiting} the recursive edit means returning to the unfinished 2793command, which continues execution. The command to exit is @kbd{C-M-c} 2794(@code{exit-recursive-edit}). 2795 2796 You can also @dfn{abort} the recursive edit. This is like exiting, 2797but also quits the unfinished command immediately. Use the command 2798@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. 2799 2800 The mode line shows you when you are in a recursive edit by displaying 2801square brackets around the parentheses that always surround the major and 2802minor mode names. Every window's mode line shows this in the same way, 2803since being in a recursive edit is true of Emacs as a whole rather than 2804any particular window or buffer. 2805 2806 It is possible to be in recursive edits within recursive edits. For 2807example, after typing @kbd{C-r} in a @code{query-replace}, you may type a 2808command that enters the debugger. This begins a recursive editing level 2809for the debugger, within the recursive editing level for @kbd{C-r}. 2810Mode lines display a pair of square brackets for each recursive editing 2811level currently in progress. 2812 2813 Exiting the inner recursive edit (such as with the debugger @kbd{c} 2814command) resumes the command running in the next level up. When that 2815command finishes, you can then use @kbd{C-M-c} to exit another recursive 2816editing level, and so on. Exiting applies to the innermost level only. 2817Aborting also gets out of only one level of recursive edit; it returns 2818immediately to the command level of the previous recursive edit. If you 2819wish, you can then abort the next recursive editing level. 2820 2821 Alternatively, the command @kbd{M-x top-level} aborts all levels of 2822recursive edits, returning immediately to the top-level command 2823reader. It also exits the minibuffer, if it is active. 2824 2825 The text being edited inside the recursive edit need not be the same text 2826that you were editing at top level. It depends on what the recursive edit 2827is for. If the command that invokes the recursive edit selects a different 2828buffer first, that is the buffer you will edit recursively. In any case, 2829you can switch buffers within the recursive edit in the normal manner (as 2830long as the buffer-switching keys have not been rebound). You could 2831probably do all the rest of your editing inside the recursive edit, 2832visiting files and all. But this could have surprising effects (such as 2833stack overflow) from time to time. So remember to exit or abort the 2834recursive edit when you no longer need it. 2835 2836 In general, we try to minimize the use of recursive editing levels in 2837GNU Emacs. This is because they constrain you to go back in a 2838particular order---from the innermost level toward the top level. When 2839possible, we present different activities in separate buffers so that 2840you can switch between them as you please. Some commands switch to a 2841new major mode which provides a command to switch back. These 2842approaches give you more flexibility to go back to unfinished tasks in 2843the order you choose. 2844 2845@ignore 2846@c Apart from edt and viper, this is all obsolete. 2847@c (Can't believe we were saying "most other editors" into 2014!) 2848@c There seems no point having a node just for those, which both have 2849@c their own manuals. 2850@node Emulation 2851@section Emulation 2852@cindex emulating other editors 2853@cindex other editors 2854@cindex EDT 2855@cindex vi 2856@cindex WordStar 2857 2858 GNU Emacs can be programmed to emulate (more or less) most other 2859editors. Standard facilities can emulate these: 2860 2861@table @asis 2862@item CRiSP/Brief (PC editor) 2863@findex crisp-mode 2864@vindex crisp-override-meta-x 2865@findex scroll-all-mode 2866@cindex CRiSP mode 2867@cindex Brief emulation 2868@cindex emulation of Brief 2869@cindex mode, CRiSP 2870@kbd{M-x crisp-mode} enables key bindings to emulate the CRiSP/Brief 2871editor. Note that this rebinds @kbd{M-x} to exit Emacs unless you set 2872the variable @code{crisp-override-meta-x}. You can also use the 2873command @kbd{M-x scroll-all-mode} or set the variable 2874@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature 2875(scrolling all windows together). 2876 2877@item EDT (DEC VMS editor) 2878@findex edt-emulation-on 2879@findex edt-emulation-off 2880Turn on EDT emulation with @kbd{M-x edt-emulation-on}; restore normal 2881command bindings with @kbd{M-x edt-emulation-off}. 2882 2883Most of the EDT emulation commands are keypad keys, and most standard 2884Emacs key bindings are still available. The EDT emulation rebindings 2885are done in the global keymap, so there is no problem switching 2886buffers or major modes while in EDT emulation. 2887 2888@item TPU (DEC VMS editor) 2889@findex tpu-edt-on 2890@cindex TPU 2891@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. 2892 2893@item vi (Berkeley editor) 2894@findex viper-mode 2895Viper is an emulator for vi. It implements several levels of 2896emulation; level 1 is closest to vi itself, while level 5 departs 2897somewhat from strict emulation to take advantage of the capabilities of 2898Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you 2899the rest of the way and ask for the emulation level. @inforef{Top, 2900Viper, viper}. 2901 2902@item vi (another emulator) 2903@findex vi-mode 2904@kbd{M-x vi-mode} enters a major mode that replaces the previously 2905established major mode. All of the vi commands that, in real vi, enter 2906input mode are programmed instead to return to the previous major 2907mode. Thus, ordinary Emacs serves as vi's input mode. 2908 2909Because vi emulation works through major modes, it does not work 2910to switch buffers during emulation. Return to normal Emacs first. 2911 2912If you plan to use vi emulation much, you probably want to bind a key 2913to the @code{vi-mode} command. 2914 2915@item vi (alternate emulator) 2916@findex vip-mode 2917@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi 2918more thoroughly than @kbd{M-x vi-mode}. Input mode in this emulator 2919is changed from ordinary Emacs so you can use @key{ESC} to go back to 2920emulated vi command mode. To get from emulated vi command mode back to 2921ordinary Emacs, type @kbd{C-z}. 2922 2923This emulation does not work through major modes, and it is possible 2924to switch buffers in various ways within the emulator. It is not 2925so necessary to assign a key to the command @code{vip-mode} as 2926it is with @code{vi-mode} because terminating insert mode does 2927not use it. 2928 2929@inforef{Top, VIP, vip}, for full information. 2930 2931@item WordStar (old wordprocessor) 2932@findex wordstar-mode 2933@kbd{M-x wordstar-mode} provides a major mode with WordStar-like 2934key bindings. 2935@end table 2936@end ignore 2937 2938 2939@node Hyperlinking 2940@section Hyperlinking and Web Navigation Features 2941 2942 The following subsections describe convenience features for handling 2943URLs and other types of links occurring in Emacs buffer text. 2944 2945@menu 2946* EWW:: A web browser in Emacs. 2947* Embedded WebKit Widgets:: Embedding browser widgets in Emacs buffers. 2948* Browse-URL:: Following URLs. 2949* Goto Address mode:: Activating URLs. 2950* FFAP:: Finding files etc. at point. 2951@end menu 2952 2953@node EWW 2954@subsection Web Browsing with EWW 2955 2956@findex eww 2957@findex eww-open-file 2958 @dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs. 2959It allows browsing URLs within an Emacs buffer. The command @kbd{M-x 2960eww} will open a URL or search the web. You can open a file 2961using the command @kbd{M-x eww-open-file}. You can use EWW as the 2962web browser for @code{browse-url}, @pxref{Browse-URL}. For full 2963details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}. 2964 2965@node Embedded WebKit Widgets 2966@subsection Embedded WebKit Widgets 2967@cindex xwidget 2968@cindex webkit widgets 2969@cindex embedded widgets 2970 2971@findex xwidget-webkit-browse-url 2972@findex xwidget-webkit-mode 2973@cindex Xwidget-WebKit mode 2974 If Emacs was compiled with the appropriate support packages, it is 2975able to show browser widgets in its buffers. The command @kbd{M-x 2976xwidget-webkit-browse-url} asks for a URL to display in the browser 2977widget. The URL normally defaults to the URL at or before point, but 2978if there is an active region (@pxref{Mark}), the default URL comes 2979from the region instead, after removing any whitespace from it. The 2980command then creates a new buffer with the embedded browser showing 2981the specified URL@. The buffer is put in the Xwidget-WebKit mode 2982(similar to Image mode, @pxref{Image Mode}), which provides 2983one-key commands for scrolling the widget, changing its size, and 2984reloading it. Type @w{@kbd{C-h b}} in that buffer to see the key 2985bindings. 2986 2987@findex xwidget-webkit-edit-mode 2988@cindex xwidget-webkit-edit-mode 2989 By default, typing a self-inserting character inside an xwidget 2990webkit buffer will do nothing, or trigger some special action. To 2991make those characters and other common editing keys insert themselves 2992when pressed, you can enable @code{xwidget-webkit-edit-mode}, which 2993redefines them to be passed through to the WebKit xwidget. 2994 2995You can also enable @code{xwidget-webkit-edit-mode} by typing @kbd{e} 2996inside the xwidget webkit buffer. 2997 2998@findex xwidget-webkit-isearch-mode 2999@cindex searching in webkit buffers 3000 @code{xwidget-webkit-isearch-mode} is a minor mode that behaves 3001similarly to incremental search (@pxref{Incremental Search}), but 3002operates on the contents of a WebKit widget instead of the current 3003buffer. It is bound to @kbd{C-s} and @kbd{C-r} inside xwidget-webkit 3004buffers. When it is invoked by @kbd{C-r}, the initial search will be 3005performed in reverse direction. 3006 3007Typing any self-inserting character will cause the character to be 3008inserted into the current search query. Typing @kbd{C-s} will cause 3009the WebKit widget to display the next search result, while typing 3010@kbd{C-r} will cause it to display the previous one. 3011 3012To leave incremental search, you can type @kbd{C-g}. 3013 3014@findex xwidget-webkit-browse-history 3015@cindex history of webkit buffers 3016 The command @code{xwidget-webkit-browse-history} displays a buffer 3017containing a list of pages previously loaded by the current WebKit 3018buffer, and lets you navigate to those pages by hitting @kbd{RET}. 3019 3020It is bound to @kbd{H}. 3021 3022@node Browse-URL 3023@subsection Following URLs 3024@cindex World Wide Web 3025@cindex Web 3026@findex browse-url 3027@findex browse-url-at-point 3028@findex browse-url-at-mouse 3029@cindex Browse-URL 3030@cindex URLs 3031 3032@table @kbd 3033@item M-x browse-url @key{RET} @var{url} @key{RET} 3034Load a URL into a Web browser. 3035@end table 3036 3037 The Browse-URL package allows you to easily follow URLs from within 3038Emacs. Most URLs are followed by invoking a web browser; 3039@samp{mailto:} URLs are followed by invoking the @code{compose-mail} 3040Emacs command to send mail to the specified address (@pxref{Sending 3041Mail}). 3042 3043 The command @kbd{M-x browse-url} prompts for a URL, and follows it. 3044If point is located near a plausible URL, that URL is offered as the 3045default. The Browse-URL package also provides other commands which 3046you might like to bind to keys, such as @code{browse-url-at-point} and 3047@code{browse-url-at-mouse}. 3048 3049@vindex browse-url-mailto-function 3050@vindex browse-url-browser-function 3051 You can customize Browse-URL's behavior via various options in the 3052@code{browse-url} Customize group. In particular, the option 3053@code{browse-url-mailto-function} lets you define how to follow 3054@samp{mailto:} URLs, while @code{browse-url-browser-function} 3055specifies your default browser. 3056 3057@vindex browse-url-handlers 3058 You can define that certain URLs are browsed with other functions by 3059customizing @code{browse-url-handlers}, an alist of regular 3060expressions or predicates paired with functions to browse matching 3061URLs. 3062 3063For more information, view the package commentary by typing @kbd{C-h P 3064browse-url @key{RET}}. 3065 3066@findex url-handler-mode 3067 Emacs also has a minor mode that has some support for handling 3068@acronym{URL}s as if they were files. @code{url-handler-mode} is a 3069global minor mode that affects most of the Emacs commands and 3070primitives that deal with file names. After switching on this mode, 3071you can say, for instance, @kbd{C-x C-f https://www.gnu.org/ RET} to 3072see the @acronym{HTML} for that web page, and you can then edit it and 3073save it to a local file, for instance. 3074 3075@node Goto Address mode 3076@subsection Activating URLs 3077@findex goto-address-mode 3078@cindex mode, Goto Address 3079@cindex Goto Address mode 3080@cindex URLs, activating 3081 3082@table @kbd 3083@item M-x goto-address-mode 3084Activate URLs and e-mail addresses in the current buffer. 3085 3086@item M-x global-goto-address-mode 3087Activate @code{goto-address-mode} in all buffers. 3088@end table 3089 3090@kindex C-c RET @r{(Goto Address mode)} 3091@findex goto-address-at-point 3092 You can make Emacs mark out URLs specially in the current buffer, by 3093typing @kbd{M-x goto-address-mode}. When this buffer-local minor mode 3094is enabled, it finds all the URLs in the buffer, highlights them, and 3095turns them into clickable buttons. You can follow the URL by typing 3096@kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on 3097its text; or by clicking with @kbd{mouse-2}, or by clicking 3098@kbd{mouse-1} quickly (@pxref{Mouse References}). Following a URL is 3099done by calling @code{browse-url} as a subroutine 3100(@pxref{Browse-URL}). 3101 3102 It can be useful to add @code{goto-address-mode} to mode hooks and 3103hooks for displaying an incoming message 3104(e.g., @code{rmail-show-message-hook} for Rmail). This is not needed 3105for Gnus or MH-E, which have similar features of their own. 3106 3107@node FFAP 3108@subsection Finding Files and URLs at Point 3109@findex find-file-at-point 3110@findex ffap 3111@findex dired-at-point 3112@findex ffap-next 3113@findex ffap-menu 3114@cindex finding file at point 3115 3116 The FFAP package replaces certain key bindings for finding files, 3117such as @kbd{C-x C-f}, with commands that provide more sensible 3118defaults. These commands behave like the ordinary ones when given a 3119prefix argument. Otherwise, they get the default file name or URL 3120from the text around point. If what is found in the buffer has the 3121form of a URL rather than a file name, the commands use 3122@code{browse-url} to view it (@pxref{Browse-URL}). 3123 3124 This feature is useful for following references in mail or news 3125buffers, @file{README} files, @file{MANIFEST} files, and so on. For 3126more information, view the package commentary by typing @kbd{C-h P 3127ffap @key{RET}}. 3128 3129@cindex FFAP minor mode 3130@findex ffap-mode 3131 To enable FFAP, type @kbd{M-x ffap-bindings}. This makes the 3132following key bindings, and also installs hooks for additional FFAP 3133functionality in Rmail, Gnus and VM article buffers. 3134 3135@table @kbd 3136@item C-x C-f @var{filename} @key{RET} 3137@kindex C-x C-f @r{(FFAP)} 3138Find @var{filename}, guessing a default from text around point 3139(@code{find-file-at-point}). 3140@item C-x C-r @var{filename} @key{RET} 3141@kindex C-x C-r @r{(FFAP)} 3142@code{ffap-read-only}, analogous to @code{find-file-read-only}. 3143@item C-x C-v @var{filename} @key{RET} 3144@kindex C-x C-v @r{(FFAP)} 3145@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. 3146@item C-x d @var{directory} @key{RET} 3147@kindex C-x d @r{(FFAP)} 3148Start Dired on @var{directory}, defaulting to the directory at 3149point (@code{dired-at-point}). 3150@item C-x C-d @var{directory} @key{RET} 3151@code{ffap-list-directory}, analogous to @code{list-directory}. 3152@item C-x 4 f @var{filename} @key{RET} 3153@kindex C-x 4 f @r{(FFAP)} 3154@code{ffap-other-window}, analogous to @code{find-file-other-window}. 3155@item C-x 4 r @var{filename} @key{RET} 3156@code{ffap-read-only-other-window}, analogous to 3157@code{find-file-read-only-other-window}. 3158@item C-x 4 d @var{directory} @key{RET} 3159@code{ffap-dired-other-window}, like @code{dired-other-window}. 3160@item C-x 5 f @var{filename} @key{RET} 3161@kindex C-x 5 f @r{(FFAP)} 3162@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. 3163@item C-x 5 r @var{filename} @key{RET} 3164@code{ffap-read-only-other-frame}, analogous to 3165@code{find-file-read-only-other-frame}. 3166@item C-x 5 d @var{directory} @key{RET} 3167@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. 3168@kindex C-x t C-f @r{(FFAP)} 3169@item C-x t C-f @var{filename} @key{return} 3170@code{ffap-other-tab}, analogous to @code{find-file-other-tab}. 3171@item C-x t C-r @var{filename} @key{return} 3172@code{ffap-read-only-other-tab}, analogous to @code{find-file-read-only-other-tab}. 3173@item M-x ffap-next 3174Search buffer for next file name or URL, then find that file or URL. 3175@item S-mouse-3 3176@kindex S-mouse-3 @r{(FFAP)} 3177@code{ffap-at-mouse} finds the file guessed from text around the position 3178of a mouse click. 3179@item C-S-mouse-3 3180@kindex C-S-mouse-3 @r{(FFAP)} 3181Display a menu of files and URLs mentioned in current buffer, then 3182find the one you select (@code{ffap-menu}). 3183@end table 3184 3185@node Amusements 3186@section Games and Other Amusements 3187@cindex boredom 3188@cindex games 3189 3190@findex animate-birthday-present 3191@cindex animate 3192 The @code{animate} package makes text dance (e.g., @kbd{M-x 3193animate-birthday-present}). 3194 3195@findex blackbox 3196@findex mpuz 3197@findex 5x5 3198@cindex puzzles 3199 @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. 3200@code{blackbox} challenges you to determine the location of objects 3201inside a box by tomography. @code{mpuz} displays a multiplication 3202puzzle with letters standing for digits in a code that you must 3203guess---to guess a value, type a letter and then the digit you think it 3204stands for. The aim of @code{5x5} is to fill in all the squares. 3205 3206@findex bubbles 3207@cindex bubbles 3208 @kbd{M-x bubbles} is a game in which the object is to remove as many 3209bubbles as you can in the smallest number of moves. 3210 3211@findex decipher 3212@cindex ciphers 3213@cindex cryptanalysis 3214 @kbd{M-x decipher} helps you to cryptanalyze a buffer which is 3215encrypted in a simple monoalphabetic substitution cipher. 3216 3217@findex dissociated-press 3218 @kbd{M-x dissociated-press} scrambles the text in the current Emacs 3219buffer, word by word or character by character, writing its output to 3220a buffer named @file{*Dissociation*}. A positive argument tells it to 3221operate character by character, and specifies the number of overlap 3222characters. A negative argument tells it to operate word by word, and 3223specifies the number of overlap words. Dissociated Press produces 3224results fairly like those of a Markov chain, but is however, an 3225independent, ignoriginal invention; it techniquitously copies several 3226consecutive characters from the sample text between random jumps, 3227unlike a Markov chain which would jump randomly after each word or 3228character. Keep dissociwords out of your documentation, if you want 3229it to be well userenced and properbose. 3230 3231@findex dunnet 3232@cindex dunnet 3233 @kbd{M-x dunnet} runs a text-based adventure game. 3234 3235@findex gomoku 3236@cindex Go Moku 3237 If you want a little more personal involvement, try @kbd{M-x gomoku}, 3238which plays the game Go Moku with you. 3239 3240@cindex tower of Hanoi 3241@findex hanoi 3242 If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are 3243considerably bored, give it a numeric argument. If you are very, very 3244bored, try an argument of 9. Sit back and watch. 3245 3246@findex life 3247@cindex Life 3248 @kbd{M-x life} runs Conway's Game of Life cellular automaton. 3249 3250@findex morse-region 3251@findex unmorse-region 3252@findex nato-region 3253@cindex Morse code 3254@cindex --/---/.-./.../. 3255 @kbd{M-x morse-region} converts the text in the region to Morse 3256code; @kbd{M-x unmorse-region} converts it back. @kbd{M-x 3257nato-region} converts the text in the region to NATO phonetic 3258alphabet; @kbd{M-x denato-region} converts it back. 3259 3260@findex pong 3261@cindex Pong game 3262@findex tetris 3263@cindex Tetris 3264@findex snake 3265@cindex Snake 3266 @kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are 3267implementations of the well-known Pong, Snake and Tetris games. 3268 3269@findex solitaire 3270@cindex solitaire 3271 @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs 3272across other pegs. 3273 3274@findex zone 3275@cindex zone 3276 The command @kbd{M-x zone} plays games with the display when Emacs 3277is idle. 3278 3279@findex butterfly 3280@cindex butterfly 3281 ``Real Programmers'' deploy @kbd{M-x butterfly}, which uses butterflies 3282to flip a bit on the drive platter, see @uref{https://xkcd.com/378}. 3283 3284@findex doctor 3285@cindex Eliza 3286 Finally, if you find yourself frustrated, try describing your 3287problems to the famous psychotherapist Eliza. Just do @kbd{M-x 3288doctor}. End each input by typing @key{RET} twice. 3289 3290@ifnottex 3291@lowersections 3292@end ifnottex 3293