0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @iftex
0006: @chapter Miscellaneous Commands
0007: 
0008:   This chapter contains several brief topics that do not fit anywhere
0009: else: reading Usenet news, host and network security,
0010: viewing PDFs and other such documents, web
0011: browsing, running shell commands and shell subprocesses, using a
0012: single shared Emacs for utilities that expect to run an editor as a
0013: subprocess, printing, sorting text, editing binary files, saving an
0014: Emacs session for later resumption, recursive editing level, following
0015: hyperlinks, and various diversions and amusements.
0016: 
0017: @end iftex
0018: 
0019: @ifnottex
0020: @raisesections
0021: @end ifnottex
0022: 
0023: @node Gnus
0024: @section Email and Usenet News with Gnus
0025: @cindex Gnus
0026: @cindex Usenet news
0027: @cindex newsreader
0028: 
0029:   Gnus is an Emacs package primarily designed for reading and posting
0030: Usenet news.  It can also be used to read and respond to messages from
0031: a number of other sources---email, remote directories, digests, and so
0032: on.  Here we introduce Gnus and describe several basic features.
0033: @ifnottex
0034: For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
0035: @end ifnottex
0036: @iftex
0037: For full details on Gnus, type @kbd{C-h i} and then select the Gnus
0038: manual.
0039: @end iftex
0040: 
0041: @menu
0042: * Buffers of Gnus::     The group, summary, and article buffers.
0043: * Gnus Startup::        What you should know about starting Gnus.
0044: * Gnus Group Buffer::   A short description of Gnus group commands.
0045: * Gnus Summary Buffer:: A short description of Gnus summary commands.
0046: @end menu
0047: 
0048: @node Buffers of Gnus
0049: @subsection Gnus Buffers
0050: 
0051:   Gnus uses several buffers to display information and to receive
0052: commands.  The three most commonly-used Gnus buffers are the
0053: @dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article
0054: buffer}.
0055: 
0056:   The @dfn{group buffer} contains a list of article sources (e.g.,
0057: newsgroups and email inboxes), which are collectively referred to as
0058: @dfn{groups}.  This is the first buffer Gnus displays when it starts
0059: up.  It normally displays only the groups to which you subscribe and
0060: that contain unread articles.  From this buffer, you can select a
0061: group to read.
0062: 
0063:   The @dfn{summary buffer} lists the articles in a single group,
0064: showing one article per line.  By default, it displays each article's
0065: author, subject, and line
0066: @iftex
0067: number.
0068: @end iftex
0069: @ifnottex
0070: number, but this is customizable; @xref{Summary Buffer Format,,, gnus,
0071: The Gnus Manual}.
0072: @end ifnottex
0073: The summary buffer is created when you select a group in the group
0074: buffer, and is killed when you exit the group.
0075: 
0076:   From the summary buffer, you can choose an article to view.  The
0077: article is displayed in the @dfn{article buffer}.  In normal Gnus
0078: usage, you view this buffer but do not select it---all useful Gnus
0079: commands can be invoked from the summary buffer.  But you can select
0080: the article buffer, and execute Gnus commands from it, if you wish.
0081: 
0082: @node Gnus Startup
0083: @subsection When Gnus Starts Up
0084: 
0085: @findex gnus
0086: @cindex @file{.newsrc} file
0087:   If your system has been set up for reading Usenet news, getting
0088: started with Gnus is easy---just type @kbd{M-x gnus}.
0089: 
0090:   On starting up, Gnus reads your @dfn{news initialization file}: a
0091: file named @file{.newsrc} in your home directory which lists your
0092: Usenet newsgroups and subscriptions (this file is not unique to Gnus;
0093: it is used by many other newsreader programs).  It then tries to
0094: contact the system's default news server, which is typically specified
0095: by the @env{NNTPSERVER} environment variable.
0096: 
0097:   If your system does not have a default news server, or if you wish
0098: to use Gnus for reading email, then before invoking @kbd{M-x gnus} you
0099: need to tell Gnus where to get news and/or mail.  To do this,
0100: customize the variables @code{gnus-select-method} and/or
0101: @code{gnus-secondary-select-methods}.
0102: @iftex
0103: See the Gnus manual for details.
0104: @end iftex
0105: @ifnottex
0106: @xref{Finding the News,,, gnus, The Gnus Manual}.
0107: @end ifnottex
0108: 
0109:   Once Gnus has started up, it displays the group buffer.  By default,
0110: the group buffer shows only a small number of @dfn{subscribed groups}.
0111: Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or
0112: @dfn{zombie}---are hidden.  The first time you start Gnus, any group
0113: to which you are not subscribed is made into a killed group; any group
0114: that subsequently appears on the news server becomes a zombie group.
0115: 
0116:   To proceed, you must select a group in the group buffer to open the
0117: summary buffer for that group; then, select an article in the summary
0118: buffer to view its article buffer in a separate window.  The following
0119: sections explain how to use the group and summary buffers to do this.
0120: 
0121:   To quit Gnus, type @kbd{q} in the group buffer.  This automatically
0122: records your group statuses in the files @file{.newsrc} and
0123: @file{.newsrc.eld}, so that they take effect in subsequent Gnus
0124: sessions.
0125: 
0126: @node Gnus Group Buffer
0127: @subsection Using the Gnus Group Buffer
0128: 
0129:   The following commands are available in the Gnus group buffer:
0130: 
0131: @table @kbd
0132: @kindex SPC @r{(Gnus Group mode)}
0133: @findex gnus-group-read-group
0134: @item @key{SPC}
0135: Switch to the summary buffer for the group on the current line
0136: (@code{gnus-group-read-group}).
0137: 
0138: @kindex l @r{(Gnus Group mode)}
0139: @kindex A s @r{(Gnus Group mode)}
0140: @findex gnus-group-list-groups
0141: @item l
0142: @itemx A s
0143: In the group buffer, list only the groups to which you subscribe and
0144: which contain unread articles (@code{gnus-group-list-groups}; this is
0145: the default listing).
0146: 
0147: @kindex L @r{(Gnus Group mode)}
0148: @kindex A u @r{(Gnus Group mode)}
0149: @findex gnus-group-list-all-groups
0150: @item L
0151: @itemx A u
0152: List all subscribed and unsubscribed groups, but not killed or zombie
0153: groups (@code{gnus-group-list-all-groups}).
0154: 
0155: @kindex A k @r{(Gnus Group mode)}
0156: @findex gnus-group-list-killed
0157: @item A k
0158: List killed groups (@code{gnus-group-list-killed}).
0159: 
0160: @kindex A z @r{(Gnus Group mode)}
0161: @findex gnus-group-list-zombies
0162: @item A z
0163: List zombie groups (@code{gnus-group-list-zombies}).
0164: 
0165: @kindex u @r{(Gnus Group mode)}
0166: @findex gnus-group-unsubscribe-current-group
0167: @cindex subscribe groups
0168: @cindex unsubscribe groups
0169: @item u
0170: Toggle the subscription status of the group
0171: (@code{gnus-group-unsubscribe-current-group}) on the current line
0172: (i.e., turn a subscribed group into an unsubscribed group, or vice
0173: versa).  Invoking this on a killed or zombie group turns it into an
0174: unsubscribed group.
0175: 
0176: @kindex C-k @r{(Gnus Group mode)}
0177: @findex gnus-group-kill-group
0178: @item C-k
0179: Kill the group on the current line (@code{gnus-group-kill-group}).
0180: Killed groups are not recorded in the @file{.newsrc} file, and they
0181: are not shown in the @kbd{l} or @kbd{L} listings.
0182: 
0183: @kindex DEL @r{(Gnus Group mode)}
0184: @item @key{DEL}
0185: Move point to the previous group containing unread articles
0186: (@code{gnus-group-prev-unread-group}).
0187: 
0188: @kindex n @r{(Gnus Group mode)}
0189: @findex gnus-group-next-unread-group
0190: @item n
0191: Move point to the next unread group
0192: (@code{gnus-group-next-unread-group}).
0193: 
0194: @kindex p @r{(Gnus Group mode)}
0195: @findex gnus-group-prev-unread-group
0196: @item p
0197: Move point to the previous unread group
0198: (@code{gnus-group-prev-unread-group}).
0199: 
0200: @kindex q @r{(Gnus Group mode)}
0201: @findex gnus-group-exit
0202: @item q
0203: Update your Gnus settings, and quit Gnus (@code{gnus-group-exit}).
0204: @end table
0205: 
0206: @node Gnus Summary Buffer
0207: @subsection Using the Gnus Summary Buffer
0208: 
0209:   The following commands are available in the Gnus summary buffer:
0210: 
0211: @table @kbd
0212: @kindex SPC @r{(Gnus Summary mode)}
0213: @findex gnus-summary-next-page
0214: @item @key{SPC}
0215: If there is no article selected, select the article on the current
0216: line and display its article buffer.  Otherwise, try scrolling the
0217: selected article buffer in its window; on reaching the end of the
0218: buffer, select the next unread article (@code{gnus-summary-next-page}).
0219: 
0220: Thus, you can read through all articles by repeatedly typing
0221: @key{SPC}.
0222: 
0223: @kindex DEL @r{(Gnus Summary mode)}
0224: @findex gnus-summary-prev-page
0225: @item @key{DEL}
0226: Scroll the text of the article backwards
0227: (@code{gnus-summary-prev-page}).
0228: 
0229: @kindex n @r{(Gnus Summary mode)}
0230: @findex gnus-summary-next-unread-article
0231: @item n
0232: Select the next unread article
0233: (@code{gnus-summary-next-unread-article}).
0234: 
0235: @kindex p @r{(Gnus Summary mode)}
0236: @findex gnus-summary-prev-unread-article
0237: @item p
0238: Select the previous unread article
0239: (@code{gnus-summary-prev-unread-article}).
0240: 
0241: @kindex s @r{(Gnus Summary mode)}
0242: @findex gnus-summary-isearch-article
0243: @item s
0244: Do an incremental search on the selected article buffer
0245: (@code{gnus-summary-isearch-article}), as if you switched to the
0246: buffer and typed @kbd{C-s} (@pxref{Incremental Search}).
0247: 
0248: @kindex M-s @r{(Gnus Summary mode)}
0249: @findex gnus-summary-search-article-forward
0250: @item M-s @var{regexp} @key{RET}
0251: Search forward for articles containing a match for @var{regexp}
0252: (@code{gnus-summary-search-article-forward}).
0253: 
0254: @kindex M-r @r{(Gnus Summary mode)}
0255: @findex gnus-summary-search-article-backward
0256: @item M-r @var{regexp} @key{RET}
0257: Search back for articles containing a match for @var{regexp}
0258: (@code{gnus-summary-search-article-backward}).
0259: 
0260: @kindex q @r{(Gnus Summary mode)}
0261: @item q
0262: Exit the summary buffer and return to the group buffer
0263: (@code{gnus-summary-exit}).
0264: @end table
0265: 
0266: @node Host Security
0267: @section Host Security
0268: @cindex security
0269: 
0270: Emacs runs inside an operating system such as GNU/Linux, and relies on
0271: the operating system to check security constraints such as accesses to
0272: files.  The default settings for Emacs are designed for typical use;
0273: they may require some tailoring in environments where security is more
0274: of a concern, or less of a concern, than usual.  For example,
0275: file-local variables can be risky, and you can set the variable
0276: @code{enable-local-variables} to @code{:safe} or (even more
0277: conservatively) to @code{nil}; conversely, if your files can all be
0278: trusted and the default checking for these variables is irritating,
0279: you can set @code{enable-local-variables} to @code{:all}.  @xref{Safe
0280: File Variables}.
0281: 
0282: @xref{Security Considerations,,, elisp, The Emacs Lisp Reference
0283: Manual}, for more information about security considerations when using
0284: Emacs as part of a larger application.
0285: 
0286: @node Network Security
0287: @section Network Security
0288: @cindex network security manager
0289: @cindex NSM
0290: @cindex encryption
0291: @cindex SSL
0292: @cindex TLS
0293: @cindex Transport Layer Security
0294: @cindex STARTTLS
0295: 
0296: Whenever Emacs establishes any network connection, it passes the
0297: established connection to the @dfn{Network Security Manager}
0298: (@acronym{NSM}).  @acronym{NSM} is responsible for enforcing the
0299: network security under your control.  Currently, this works by using
0300: the Transport Layer Security (@acronym{TLS}) features.
0301: 
0302: @vindex network-security-level
0303: The @code{network-security-level} variable determines the security
0304: level that @acronym{NSM} enforces.  If its value is @code{low}, no
0305: security checks are performed.
0306: 
0307: If this variable is @code{medium} (which is the default), a number of
0308: checks will be performed.  If as result @acronym{NSM} determines that
0309: the network connection might not be trustworthy, it will make you
0310: aware of that, and will ask you what to do about the network
0311: connection.
0312: 
0313: You can decide to register a permanent security exception for an
0314: unverified connection, a temporary exception, or refuse the connection
0315: entirely.
0316: 
0317: @vindex network-security-protocol-checks
0318: In addition to the basic certificate correctness checks, several
0319: @acronym{TLS} algorithm checks are available.  Some encryption
0320: technologies that were previously thought to be secure have shown
0321: themselves to be fragile, so Emacs (by default) warns you about some
0322: of these problems.
0323: 
0324: The protocol network checks is controlled via the
0325: @code{network-security-protocol-checks} variable.
0326: 
0327: It's an alist where the first element of each association is the name
0328: of the check, the second element is the security level where the check
0329: should be used, and the optional third element is a parameter supplied
0330: to the check.
0331: 
0332: An element like @code{(rc4 medium)} will result in the function
0333: @code{nsm-protocol-check--rc4} being called like thus:
0334: @w{@code{(nsm-protocol-check--rc4 host port status optional-parameter)}}.
0335: The function should return non-@code{nil} if the connection should
0336: proceed and @code{nil} otherwise.
0337: 
0338: Below is a list of the checks done on the default @code{medium} level.
0339: 
0340: @table @asis
0341: 
0342: @item unable to verify a @acronym{TLS} certificate
0343: If the connection is a @acronym{TLS}, @acronym{SSL} or
0344: @acronym{STARTTLS} connection, @acronym{NSM} will check whether
0345: the certificate used to establish the identity of the server we're
0346: connecting to can be verified.
0347: 
0348: While an invalid certificate is often the cause for concern (there
0349: could be a Man-in-the-Middle hijacking your network connection and
0350: stealing your password), there may be valid reasons for going ahead
0351: with the connection anyway.  For instance, the server may be using a
0352: self-signed certificate, or the certificate may have expired.  It's up
0353: to you to determine whether it's acceptable to continue with the
0354: connection.
0355: 
0356: @item a self-signed certificate has changed
0357: If you've previously accepted a self-signed certificate, but it has
0358: now changed, that could mean that the server has just changed the
0359: certificate, but it might also mean that the network connection has
0360: been hijacked.
0361: 
0362: @item previously encrypted connection now unencrypted
0363: If the connection is unencrypted, but it was encrypted in previous
0364: sessions, this might mean that there is a proxy between you and the
0365: server that strips away @acronym{STARTTLS} announcements, leaving the
0366: connection unencrypted.  This is usually very suspicious.
0367: 
0368: @item talking to an unencrypted service when sending a password
0369: When connecting to an @acronym{IMAP} or @acronym{POP3} server, these
0370: should usually be encrypted, because it's common to send passwords
0371: over these connections.  Similarly, if you're sending email via
0372: @acronym{SMTP} that requires a password, you usually want that
0373: connection to be encrypted.  If the connection isn't encrypted,
0374: @acronym{NSM} will warn you.
0375: 
0376: @item Diffie-Hellman low prime bits
0377: When doing the public key exchange, the number of prime bits should be
0378: high enough to ensure that the channel can't be eavesdropped on by third
0379: parties.  If this number is too low, Emacs will warn you.  (This is the
0380: @code{diffie-hellman-prime-bits} check in
0381: @code{network-security-protocol-checks}).
0382: 
0383: @item @acronym{RC4} stream cipher
0384: The @acronym{RC4} stream cipher is believed to be of low quality and
0385: may allow eavesdropping by third parties.  (This is the @code{rc4}
0386: check in @code{network-security-protocol-checks}).
0387: 
0388: @item @acronym{SHA1} in the host certificate or in intermediate certificates
0389: It is believed that if an intermediate certificate uses the
0390: @acronym{SHA1} hashing algorithm, then third parties can issue
0391: certificates pretending to be that issuing instance.  These
0392: connections are therefore vulnerable to man-in-the-middle attacks.
0393: (These are the @code{signature-sha1} and @code{intermediate-sha1}
0394: checks in @code{network-security-protocol-checks}).
0395: 
0396: @item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3}
0397: The protocols older than @acronym{TLS1.0} are believed to be
0398: vulnerable to a variety of attacks, and you may want to avoid using
0399: these if what you're doing requires higher security.  (This is the
0400: @code{ssl} check in @code{network-security-protocol-checks}).
0401: 
0402: @end table
0403: 
0404: If @code{network-security-level} is @code{high}, the following checks
0405: will be made, in addition to the above:
0406: 
0407: @table @asis
0408: @item @acronym{3DES} cipher
0409: The @acronym{3DES} stream cipher provides at most 112 bits of
0410: effective security, which is considered to be towards the low end.
0411: (This is the @code{3des} check in
0412: @code{network-security-protocol-checks}).
0413: 
0414: @item a validated certificate changes the public key
0415: Servers change their keys occasionally, and that is normally nothing
0416: to be concerned about.  However, if you are worried that your network
0417: connections are being hijacked by agencies who have access to pliable
0418: Certificate Authorities which issue new certificates for third-party
0419: services, you may want to keep track of these changes.
0420: 
0421: @end table
0422: 
0423: Finally, if @code{network-security-level} is @code{paranoid}, you will
0424: also be notified the first time @acronym{NSM} sees any new
0425: certificate.  This will allow you to inspect all the certificates from
0426: all the connections that Emacs makes.
0427: 
0428: The following additional variables can be used to control details of
0429: @acronym{NSM} operation:
0430: 
0431: @table @code
0432: @item nsm-settings-file
0433: @vindex nsm-settings-file
0434: This is the file where @acronym{NSM} stores details about connections.
0435: It defaults to @file{~/.emacs.d/network-security.data}.
0436: 
0437: @item nsm-save-host-names
0438: @vindex nsm-save-host-names
0439: By default, host names will not be saved for non-@code{STARTTLS}
0440: connections.  Instead a host/port hash is used to identify connections.
0441: This means that one can't casually read the settings file to see what
0442: servers the user has connected to.  If this variable is @code{t},
0443: @acronym{NSM} will also save host names in the
0444: @code{nsm-settings-file}.
0445: 
0446: @end table
0447: 
0448: 
0449: @node Document View
0450: @section Document Viewing
0451: @cindex DVI file
0452: @cindex PDF file
0453: @cindex PS file
0454: @cindex PostScript file
0455: @cindex OpenDocument file
0456: @cindex Microsoft Office file
0457: @cindex DocView mode
0458: @cindex mode, DocView
0459: @cindex document viewer (DocView)
0460: @findex doc-view-mode
0461: 
0462:   DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
0463: OpenDocument, and Microsoft Office documents.  It provides features
0464: such as slicing, zooming, and searching inside documents.  It works by
0465: converting the document to a set of images using the @command{gs}
0466: (GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands
0467: and other external tools @footnote{For PostScript files, GhostScript
0468: is a hard requirement.  For DVI files, @code{dvipdf} or @code{dvipdfm}
0469: is needed.  For OpenDocument and Microsoft Office documents, the
0470: @code{unoconv} tool is needed.}, and displaying those images.
0471: 
0472: @findex doc-view-toggle-display
0473: @findex doc-view-minor-mode
0474:   When you visit a document file that can be displayed with DocView
0475: mode, Emacs automatically uses that mode @footnote{The needed
0476: external tools for the document type must be available, and Emacs must
0477: be running in a graphical frame and have PNG image support.  If these
0478: requirements is not fulfilled, Emacs falls back to another major
0479: mode.}.  As an exception, when you visit a PostScript file, Emacs
0480: switches to PS mode, a major mode for editing PostScript files as
0481: text; however, it also enables DocView minor mode, so you can type
0482: @kbd{C-c C-c} to view the document with DocView.  In either DocView
0483: mode or DocView minor mode, repeating @kbd{C-c C-c}
0484: (@code{doc-view-toggle-display}) toggles between DocView and the
0485: underlying file contents.
0486: 
0487: @findex doc-view-open-text
0488:   When you visit a file which would normally be handled by DocView
0489: mode but some requirement is not met (e.g., you operate in a terminal
0490: frame or Emacs has no PNG support), you are queried if you want to
0491: view the document's contents as plain text.  If you confirm, the
0492: buffer is put in text mode and DocView minor mode is activated.  Thus,
0493: by typing @kbd{C-c C-c} you switch to the fallback mode.  With another
0494: @kbd{C-c C-c} you return to DocView mode.  The plain text contents can
0495: also be displayed from within DocView mode by typing @kbd{C-c C-t}
0496: (@code{doc-view-open-text}).
0497: 
0498:   You can explicitly enable DocView mode with the command @kbd{M-x
0499: doc-view-mode}.  You can toggle DocView minor mode with @kbd{M-x
0500: doc-view-minor-mode}.
0501: 
0502:   When DocView mode starts, it displays a welcome screen and begins
0503: formatting the file, page by page.  It displays the first page once
0504: that has been formatted.
0505: 
0506:   To kill the DocView buffer, type @kbd{k}
0507: (@code{doc-view-kill-proc-and-buffer}).  To bury it, type @kbd{q}
0508: (@code{quit-window}).
0509: 
0510: @menu
0511: * Navigation: DocView Navigation.  Navigating DocView buffers.
0512: * Searching: DocView Searching.    Searching inside documents.
0513: * Slicing: DocView Slicing.        Specifying which part of a page is displayed.
0514: * Conversion: DocView Conversion.  Influencing and triggering conversion.
0515: @end menu
0516: 
0517: @node DocView Navigation
0518: @subsection DocView Navigation
0519: 
0520:   In DocView mode, you can scroll the current page using the usual
0521: Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
0522: the arrow keys.
0523: 
0524: @vindex doc-view-continuous
0525:   By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
0526: scrolling at the beginning and end of the current page, respectively.
0527: However, if you change the variable @code{doc-view-continuous} to a
0528: non-@code{nil} value, then @kbd{C-p} displays the previous page if you
0529: are already at the beginning of the current page, and @kbd{C-n}
0530: displays the next page if you are at the end of the current page.
0531: 
0532: @findex doc-view-next-page
0533: @findex doc-view-previous-page
0534: @kindex n @r{(DocView mode)}
0535: @kindex p @r{(DocView mode)}
0536: @kindex PageDown @r{(DocView mode)}
0537: @kindex PageUp @r{(DocView mode)}
0538: @kindex next @r{(DocView mode)}
0539: @kindex prior @r{(DocView mode)}
0540: @kindex C-x ] @r{(DocView mode)}
0541: @kindex C-x [ @r{(DocView mode)}
0542:   You can also display the next page by typing @kbd{n},
0543: @key{PageDown}, @key{next} or @kbd{C-x ]} (@code{doc-view-next-page}).
0544: To display the previous page, type @kbd{p}, @key{PageUp}, @key{prior}
0545: or @kbd{C-x [} (@code{doc-view-previous-page}).
0546: 
0547: @findex doc-view-scroll-up-or-next-page
0548: @findex doc-view-scroll-down-or-previous-page
0549: @kindex SPC @r{(DocView mode)}
0550: @kindex DEL @r{(DocView mode)}
0551:   @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient
0552: way to advance through the document.  It scrolls within the current
0553: page or advances to the next.  @key{DEL} moves backwards in a similar
0554: way (@code{doc-view-scroll-down-or-previous-page}).
0555: 
0556: @findex doc-view-first-page
0557: @findex doc-view-last-page
0558: @findex doc-view-goto-page
0559: @kindex M-< @r{(DocView mode)}
0560: @kindex M-> @r{(DocView mode)}
0561:   To go to the first page, type @kbd{M-<}
0562: (@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
0563: (@code{doc-view-last-page}).  To jump to a page by its number, type
0564: @kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
0565: 
0566: @findex doc-view-enlarge
0567: @findex doc-view-shrink
0568: @vindex doc-view-resolution
0569: @kindex + @r{(DocView mode)}
0570: @kindex - @r{(DocView mode)}
0571:   You can enlarge or shrink the document with @kbd{+}
0572: (@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}).  These
0573: commands work by reconverting the document at the new size.  To
0574: specify the default size for DocView, customize the variable
0575: @code{doc-view-resolution}.
0576: 
0577: @node DocView Searching
0578: @subsection DocView Searching
0579: 
0580:   In DocView mode, you can search the file's text for a regular
0581: expression (@pxref{Regexps}).  The interface for searching is inspired
0582: by @code{isearch} (@pxref{Incremental Search}).
0583: 
0584: @findex doc-view-search
0585: @findex doc-view-search-backward
0586: @findex doc-view-show-tooltip
0587:   To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
0588: @kbd{C-r} (@code{doc-view-search-backward}).  This reads a regular
0589: expression using a minibuffer, then echoes the number of matches found
0590: within the document.  You can move forward and back among the matches
0591: by typing @kbd{C-s} and @kbd{C-r}.  DocView mode has no way to show
0592: the match inside the page image; instead, it displays a tooltip (at
0593: the mouse position) listing all matching lines in the current page.
0594: To force display of this tooltip, type @kbd{C-t}
0595: (@code{doc-view-show-tooltip}).
0596: 
0597:   To start a new search, use the search command with a prefix
0598: argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
0599: for a backward search.
0600: 
0601: @node DocView Slicing
0602: @subsection DocView Slicing
0603: 
0604: Documents often have wide margins for printing.  They are annoying
0605: when reading the document on the screen, because they use up screen
0606: space and can cause inconvenient scrolling.
0607: 
0608: @findex doc-view-set-slice
0609: @findex doc-view-set-slice-using-mouse
0610:   With DocView you can hide these margins by selecting a @dfn{slice}
0611: of pages to display.  A slice is a rectangle within the page area;
0612: once you specify a slice in DocView, it applies to whichever page you
0613: look at.
0614: 
0615:   To specify the slice numerically, type @kbd{s s}
0616: (@code{doc-view-set-slice}); then enter the top left pixel position
0617: and the slice's width and height.
0618: @c ??? how does this work?
0619: 
0620:   A more convenient graphical way to specify the slice is with @kbd{s
0621: m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
0622: select the slice.  Simply press and hold the left mouse button at the
0623: upper-left corner of the region you want to have in the slice, then
0624: move the mouse pointer to the lower-right corner and release the
0625: button.
0626: 
0627:   The most convenient way is to set the optimal slice by using
0628: BoundingBox information automatically determined from the document by
0629: typing @kbd{s b} (@code{doc-view-set-slice-from-bounding-box}).
0630: 
0631: @findex doc-view-reset-slice
0632:   To cancel the selected slice, type @kbd{s r}
0633: (@code{doc-view-reset-slice}).  Then DocView shows the entire page
0634: including its entire margins.
0635: 
0636: @node DocView Conversion
0637: @subsection DocView Conversion
0638: 
0639: @vindex doc-view-cache-directory
0640: @findex doc-view-clear-cache
0641:   For efficiency, DocView caches the images produced by @command{gs}.
0642: The name of the directory where it caches images is given by the variable
0643: @code{doc-view-cache-directory}.  You can clear the cache directory by
0644: typing @kbd{M-x doc-view-clear-cache}.
0645: 
0646: @findex doc-view-kill-proc
0647: @findex doc-view-kill-proc-and-buffer
0648:   To force reconversion of the currently viewed document, type @kbd{r}
0649: or @kbd{g} (@code{revert-buffer}).  To kill the converter process
0650: associated with the current buffer, type @kbd{K}
0651: (@code{doc-view-kill-proc}).  The command @kbd{k}
0652: (@code{doc-view-kill-proc-and-buffer}) kills the converter process and
0653: the DocView buffer.
0654: 
0655: @node Shell
0656: @section Running Shell Commands from Emacs
0657: @cindex subshell
0658: @cindex shell commands
0659: 
0660:   Emacs has commands for passing single command lines to shell
0661: subprocesses, and for running a shell interactively with input and
0662: output to an Emacs buffer, and for running a shell in a terminal
0663: emulator window.
0664: 
0665: @table @kbd
0666: @item M-! @var{cmd} @key{RET}
0667: Run the shell command @var{cmd} and display the output
0668: (@code{shell-command}).
0669: @item M-| @var{cmd} @key{RET}
0670: Run the shell command @var{cmd} with region contents as input;
0671: optionally replace the region with the output
0672: (@code{shell-command-on-region}).
0673: @item M-& @var{cmd} @key{RET}
0674: Run the shell command @var{cmd} asynchronously, and display the output
0675: (@code{async-shell-command}).
0676: @item M-x shell
0677: Run a subshell with input and output through an Emacs buffer.  You can
0678: then give commands interactively.
0679: @item M-x term
0680: Run a subshell with input and output through an Emacs buffer.  You can
0681: then give commands interactively.  Full terminal emulation is
0682: available.
0683: @end table
0684: 
0685: @vindex exec-path
0686:   Whenever you specify a relative file name for an executable program
0687: (either in the @var{cmd} argument to one of the above commands, or in
0688: other contexts), Emacs searches for the program in the directories
0689: specified by the variable @code{exec-path}.  The value of this
0690: variable must be a list of directories; the default value is
0691: initialized from the environment variable @env{PATH} when Emacs is
0692: started (@pxref{General Variables}).
0693: 
0694:   @kbd{M-x eshell} invokes a shell implemented entirely in Emacs.  It
0695: is documented in its own manual.
0696: @ifnottex
0697: @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
0698: @end ifnottex
0699: @iftex
0700: See the Eshell Info manual, which is distributed with Emacs.
0701: @end iftex
0702: 
0703: @menu
0704: * Single Shell::           How to run one shell command and return.
0705: * Interactive Shell::      Permanent shell taking input via Emacs.
0706: * Shell Mode::             Special Emacs commands used with permanent shell.
0707: * Shell Prompts::          Two ways to recognize shell prompts.
0708: * History: Shell History.  Repeating previous commands in a shell buffer.
0709: * Directory Tracking::     Keeping track when the subshell changes directory.
0710: * Options: Shell Options.  Options for customizing Shell mode.
0711: * Terminal emulator::      An Emacs window as a terminal emulator.
0712: * Term Mode::              Special Emacs commands used in Term mode.
0713: * Remote Host::            Connecting to another computer.
0714: * Serial Terminal::        Connecting to a serial port.
0715: @end menu
0716: 
0717: @node Single Shell
0718: @subsection Single Shell Commands
0719: 
0720: @kindex M-!
0721: @findex shell-command
0722:   @kbd{M-!} (@code{shell-command}) reads a line of text using the
0723: minibuffer and executes it as a shell command, in a subshell made just
0724: for that command.  Standard input for the command comes from the null
0725: device.  If the shell command produces any output, the output appears
0726: either in the echo area (if it is short), or in an Emacs buffer named
0727: @file{*Shell Command Output*}, displayed in another window (if the
0728: output is long).  The variables @code{resize-mini-windows} and
0729: @code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when
0730: Emacs should consider the output to be too long for the echo area.
0731: 
0732:   For instance, one way to decompress a file named @file{foo.gz} is to
0733: type @kbd{M-! gunzip foo.gz @key{RET}}.  That shell command normally
0734: creates the file @file{foo} and produces no terminal output.
0735: 
0736:   A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!},
0737: causes it to insert terminal output into the current buffer instead of
0738: a separate buffer.  It puts point before the output, and sets the mark
0739: after the output.  For instance, @kbd{M-1 M-! gunzip < foo.gz
0740: @key{RET}} would insert the uncompressed form of the file
0741: @file{foo.gz} into the current buffer.
0742: 
0743:   Provided the specified shell command does not end with @samp{&}, it
0744: runs @dfn{synchronously}, and you must wait for it to exit before
0745: continuing to use Emacs.  To stop waiting, type @kbd{C-g} to quit;
0746: this sends a @code{SIGINT} signal to terminate the shell command (this
0747: is the same signal that @kbd{C-c} normally generates in the shell).
0748: Emacs then waits until the command actually terminates.  If the shell
0749: command doesn't stop (because it ignores the @code{SIGINT} signal),
0750: type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal,
0751: which is impossible to ignore.
0752: 
0753: @kindex M-&
0754: @findex async-shell-command
0755:   A shell command that ends in @samp{&} is executed
0756: @dfn{asynchronously}, and you can continue to use Emacs as it runs.
0757: You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
0758: shell command asynchronously; this is exactly like calling @kbd{M-!}
0759: with a trailing @samp{&}, except that you do not need the @samp{&}.
0760: The default output buffer for asynchronous shell commands is named
0761: @samp{*Async Shell Command*}.  Emacs inserts the output into this
0762: buffer as it comes in, whether or not the buffer is visible in a
0763: window.
0764: 
0765: @vindex async-shell-command-buffer
0766:   If you want to run more than one asynchronous shell command at the
0767: same time, they could end up competing for the output buffer.  The
0768: option @code{async-shell-command-buffer} specifies what to do about
0769: this; e.g., whether to rename the pre-existing output buffer, or to
0770: use a different buffer for the new command.  Consult the variable's
0771: documentation for more possibilities.
0772: 
0773: @vindex async-shell-command-display-buffer
0774:   If you want the output buffer for asynchronous shell commands to be
0775: displayed only when the command generates output, set
0776: @code{async-shell-command-display-buffer} to @code{nil}.
0777: 
0778: @kindex M-|
0779: @findex shell-command-on-region
0780:   @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
0781: passes the contents of the region as the standard input to the shell
0782: command, instead of no input.  With a numeric argument, it deletes the
0783: old region and replaces it with the output from the shell command.
0784: 
0785:   For example, you can use @kbd{M-|} with the @command{gpg} program to
0786: see what keys are in the buffer.  If the buffer contains a GnuPG key,
0787: type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
0788: to @command{gpg}.  This will output the list of keys to the
0789: @file{*Shell Command Output*} buffer.
0790: 
0791: @vindex shell-file-name
0792:   The above commands use the shell specified by the variable
0793: @code{shell-file-name}.  Its default value is determined by the
0794: @env{SHELL} environment variable when Emacs is started.  If the file
0795: name is relative, Emacs searches the directories listed in
0796: @code{exec-path} (@pxref{Shell}).
0797: 
0798:   If the default directory is remote (@pxref{Remote Files}), the
0799: default value is @file{/bin/sh}.  This can be changed by declaring
0800: @code{shell-file-name} connection-local (@pxref{Connection Variables}).
0801: 
0802:   To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
0803: @kbd{C-x @key{RET} c} immediately beforehand.  @xref{Communication Coding}.
0804: 
0805: @vindex shell-command-default-error-buffer
0806:   By default, error output is intermixed with the regular output in
0807: the output buffer.  But if you change the value of the variable
0808: @code{shell-command-default-error-buffer} to a string, error output is
0809: inserted into a buffer of that name.
0810: 
0811: @vindex shell-command-dont-erase-buffer
0812:   By default, the output buffer is erased between shell commands.
0813: If you change the value of the variable
0814: @code{shell-command-dont-erase-buffer} to a non-@code{nil} value,
0815: the output buffer is not erased.  This variable also controls where to
0816: set the point in the output buffer after the command completes; see the
0817: documentation of the variable for details.
0818: 
0819: @node Interactive Shell
0820: @subsection Interactive Subshell
0821: 
0822: @findex shell
0823:   To run a subshell interactively, type @kbd{M-x shell}.  This creates
0824: (or reuses) a buffer named @file{*shell*}, and runs a shell subprocess
0825: with input coming from and output going to that buffer.  That is to
0826: say, any terminal output from the subshell goes into the buffer,
0827: advancing point, and any terminal input for the subshell comes from
0828: text in the buffer.  To give input to the subshell, go to the end of
0829: the buffer and type the input, terminated by @key{RET}.
0830: 
0831:   By default, when the subshell is invoked interactively, the
0832: @file{*shell*} buffer is displayed in a new window, unless the current
0833: window already shows the @file{*shell*} buffer.  This behavior can
0834: be customized via @code{display-buffer-alist} (@pxref{Window Choice}).
0835: 
0836:   While the subshell is waiting or running a command, you can switch
0837: windows or buffers and perform other editing in Emacs.  Emacs inserts
0838: the output from the subshell into the Shell buffer whenever it has
0839: time to process it (e.g., while waiting for keyboard input).
0840: 
0841: @cindex @code{comint-highlight-input} face
0842: @cindex @code{comint-highlight-prompt} face
0843:   In the Shell buffer, prompts are displayed with the face
0844: @code{comint-highlight-prompt}, and submitted input lines are
0845: displayed with the face @code{comint-highlight-input}.  This makes it
0846: easier to distinguish input lines from the shell output.
0847: @xref{Faces}.
0848: 
0849:   To make multiple subshells, invoke @kbd{M-x shell} with a prefix
0850: argument (e.g., @kbd{C-u M-x shell}).  Then the command will read a
0851: buffer name, and create (or reuse) a subshell in that buffer.  You can
0852: also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
0853: then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
0854: Subshells in different buffers run independently and in parallel.
0855: 
0856: @vindex explicit-shell-file-name
0857: @cindex environment variables for subshells
0858: @cindex @env{ESHELL} environment variable
0859: @cindex @env{SHELL} environment variable
0860:   To specify the shell file name used by @kbd{M-x shell}, customize
0861: the variable @code{explicit-shell-file-name}.  If this is @code{nil}
0862: (the default), Emacs uses the environment variable @env{ESHELL} if it
0863: exists.  Otherwise, it usually uses the variable
0864: @code{shell-file-name} (@pxref{Single Shell}); but if the default
0865: directory is remote (@pxref{Remote Files}), it prompts you for the
0866: shell file name.  @xref{Minibuffer File}, for hints how to type remote
0867: file names effectively.
0868: 
0869:   Emacs sends the new shell the contents of the file
0870: @file{~/.emacs_@var{shellname}} as input, if it exists, where
0871: @var{shellname} is the name of the file that the shell was loaded
0872: from.  For example, if you use bash, the file sent to it is
0873: @file{~/.emacs_bash}.  If this file is not found, Emacs tries with
0874: @file{~/.emacs.d/init_@var{shellname}.sh}.
0875: 
0876:   To specify a coding system for the shell, you can use the command
0877: @kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can
0878: also change the coding system for a running subshell by typing
0879: @kbd{C-x @key{RET} p} in the shell buffer.  @xref{Communication
0880: Coding}.
0881: 
0882: @cindex @env{INSIDE_EMACS} environment variable
0883:   Emacs sets the environment variable @env{INSIDE_EMACS} in the
0884: subshell to @samp{@var{version},comint}, where @var{version} is the
0885: Emacs version (e.g., @samp{24.1}).  Programs can check this variable
0886: to determine whether they are running inside an Emacs subshell.
0887: 
0888: @node Shell Mode
0889: @subsection Shell Mode
0890: @cindex Shell mode
0891: @cindex mode, Shell
0892: 
0893:   The major mode for Shell buffers is Shell mode.  Many of its special
0894: commands are bound to the @kbd{C-c} prefix, and resemble the usual
0895: editing and job control characters present in ordinary shells, except
0896: that you must type @kbd{C-c} first.  Here is a list of Shell mode
0897: commands:
0898: 
0899: @table @kbd
0900: @item @key{RET}
0901: @kindex RET @r{(Shell mode)}
0902: @findex comint-send-input
0903: Send the current line as input to the subshell
0904: (@code{comint-send-input}).  Any shell prompt at the beginning of the
0905: line is omitted (@pxref{Shell Prompts}).  If point is at the end of
0906: buffer, this is like submitting the command line in an ordinary
0907: interactive shell.  However, you can also invoke @key{RET} elsewhere
0908: in the shell buffer to submit the current line as input.
0909: 
0910: @item @key{TAB}
0911: @kindex TAB @r{(Shell mode)}
0912: @findex completion-at-point@r{, in Shell Mode}
0913: @cindex shell completion
0914: Complete the command name or file name before point in the shell
0915: buffer (@code{completion-at-point}).  This uses the usual Emacs
0916: completion rules (@pxref{Completion}), with the completion
0917: alternatives being file names, environment variable names, the shell
0918: command history, and history references (@pxref{History References}).
0919: For options controlling the completion, @pxref{Shell Options}.
0920: 
0921: @item M-?
0922: @kindex M-? @r{(Shell mode)}
0923: @findex comint-dynamic-list-filename@dots{}
0924: Display temporarily a list of the possible completions of the file
0925: name before point (@code{comint-dynamic-list-filename-completions}).
0926: 
0927: @item C-d
0928: @kindex C-d @r{(Shell mode)}
0929: @findex comint-delchar-or-maybe-eof
0930: Either delete a character or send @acronym{EOF}
0931: (@code{comint-delchar-or-maybe-eof}).  Typed at the end of the shell
0932: buffer, this sends @acronym{EOF} to the subshell.  Typed at any other
0933: position in the buffer, this deletes a character as usual.
0934: 
0935: @item C-c C-a
0936: @kindex C-c C-a @r{(Shell mode)}
0937: @findex comint-bol-or-process-mark
0938: Move to the beginning of the line, but after the prompt if any
0939: (@code{comint-bol-or-process-mark}).  If you repeat this command twice
0940: in a row, the second time it moves back to the process mark, which is
0941: the beginning of the input that you have not yet sent to the subshell.
0942: (Normally that is the same place---the end of the prompt on this
0943: line---but after @kbd{C-c @key{SPC}} the process mark may be in a
0944: previous line.)
0945: 
0946: @item C-c @key{SPC}
0947: Accumulate multiple lines of input, then send them together
0948: (@code{comint-accumulate}).  This command inserts a newline before
0949: point, but does not send the preceding text as input to the
0950: subshell---at least, not yet.  Both lines, the one before this newline
0951: and the one after, will be sent together (along with the newline that
0952: separates them), when you type @key{RET}.
0953: 
0954: @item C-c C-u
0955: @kindex C-c C-u @r{(Shell mode)}
0956: @findex comint-kill-input
0957: Kill all text pending at end of buffer to be sent as input
0958: (@code{comint-kill-input}).  If point is not at end of buffer,
0959: this only kills the part of this text that precedes point.
0960: 
0961: @item C-c C-w
0962: @kindex C-c C-w @r{(Shell mode)}
0963: Kill a word before point (@code{backward-kill-word}).
0964: 
0965: @item C-c C-c
0966: @kindex C-c C-c @r{(Shell mode)}
0967: @findex comint-interrupt-subjob
0968: Interrupt the shell or its current subjob if any
0969: (@code{comint-interrupt-subjob}).  This command also kills
0970: any shell input pending in the shell buffer and not yet sent.
0971: 
0972: @item C-c C-z
0973: @kindex C-c C-z @r{(Shell mode)}
0974: @findex comint-stop-subjob
0975: Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
0976: This command also kills any shell input pending in the shell buffer and
0977: not yet sent.
0978: 
0979: @item C-c C-\
0980: @findex comint-quit-subjob
0981: @kindex C-c C-\ @r{(Shell mode)}
0982: Send quit signal to the shell or its current subjob if any
0983: (@code{comint-quit-subjob}).  This command also kills any shell input
0984: pending in the shell buffer and not yet sent.
0985: 
0986: @item C-c C-o
0987: @kindex C-c C-o @r{(Shell mode)}
0988: @findex comint-delete-output
0989: Delete the last batch of output from a shell command
0990: (@code{comint-delete-output}).  This is useful if a shell command spews
0991: out lots of output that just gets in the way.
0992: 
0993: @item C-c C-s
0994: @kindex C-c C-s @r{(Shell mode)}
0995: @findex comint-write-output
0996: Write the last batch of output from a shell command to a file
0997: (@code{comint-write-output}).  With a prefix argument, the file is
0998: appended to instead.  Any prompt at the end of the output is not
0999: written.
1000: 
1001: @item C-c C-r
1002: @itemx C-M-l
1003: @kindex C-c C-r @r{(Shell mode)}
1004: @kindex C-M-l @r{(Shell mode)}
1005: @findex comint-show-output
1006: Scroll to display the beginning of the last batch of output at the top
1007: of the window; also move the cursor there (@code{comint-show-output}).
1008: 
1009: @item C-c C-e
1010: @kindex C-c C-e @r{(Shell mode)}
1011: @findex comint-show-maximum-output
1012: Scroll to put the last line of the buffer at the bottom of the window
1013: (@code{comint-show-maximum-output}).
1014: 
1015: @item C-c C-f
1016: @kindex C-c C-f @r{(Shell mode)}
1017: @findex shell-forward-command
1018: @vindex shell-command-regexp
1019: Move forward across one shell command, but not beyond the current line
1020: (@code{shell-forward-command}).  The variable @code{shell-command-regexp}
1021: specifies how to recognize the end of a command.
1022: 
1023: @item C-c C-b
1024: @kindex C-c C-b @r{(Shell mode)}
1025: @findex shell-backward-command
1026: Move backward across one shell command, but not beyond the current line
1027: (@code{shell-backward-command}).
1028: 
1029: @item M-x dirs
1030: Ask the shell for its working directory, and update the Shell buffer's
1031: default directory.  @xref{Directory Tracking}.
1032: 
1033: @item M-x comint-send-invisible @key{RET} @var{text} @key{RET}
1034: @findex comint-send-invisible
1035: Send @var{text} as input to the shell, after reading it without
1036: echoing.  This is useful when a shell command runs a program that asks
1037: for a password.
1038: 
1039: Please note that Emacs will not echo passwords by default.  If you
1040: really want them to be echoed, evaluate (@pxref{Lisp Eval}) the
1041: following Lisp expression:
1042: 
1043: @example
1044: (remove-hook 'comint-output-filter-functions
1045:              'comint-watch-for-password-prompt)
1046: @end example
1047: 
1048: @item M-x comint-continue-subjob
1049: @findex comint-continue-subjob
1050: Continue the shell process.  This is useful if you accidentally suspend
1051: the shell process.@footnote{You should not suspend the shell process.
1052: Suspending a subjob of the shell is a completely different matter---that
1053: is normal practice, but you must use the shell to continue the subjob;
1054: this command won't do it.}
1055: 
1056: @item M-x comint-strip-ctrl-m
1057: @findex comint-strip-ctrl-m
1058: Discard all control-M characters from the current group of shell output.
1059: The most convenient way to use this command is to make it run
1060: automatically when you get output from the subshell.  To do that,
1061: evaluate this Lisp expression:
1062: 
1063: @example
1064: (add-hook 'comint-output-filter-functions
1065:           'comint-strip-ctrl-m)
1066: @end example
1067: 
1068: @item M-x comint-truncate-buffer
1069: @findex comint-truncate-buffer
1070: This command truncates the shell buffer to a certain maximum number of
1071: lines, specified by the variable @code{comint-buffer-maximum-size}.
1072: Here's how to do this automatically each time you get output from the
1073: subshell:
1074: 
1075: @example
1076: (add-hook 'comint-output-filter-functions
1077:           'comint-truncate-buffer)
1078: @end example
1079: @end table
1080: 
1081: @cindex Comint mode
1082: @cindex mode, Comint
1083:   Shell mode is a derivative of Comint mode, a general-purpose mode for
1084: communicating with interactive subprocesses.  Most of the features of
1085: Shell mode actually come from Comint mode, as you can see from the
1086: command names listed above.  The special features of Shell mode include
1087: the directory tracking feature, and a few user commands.
1088: 
1089:   Other Emacs features that use variants of Comint mode include GUD
1090: (@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
1091: 
1092: @findex comint-run
1093:   You can use @kbd{M-x comint-run} to execute any program of your choice
1094: in a subprocess using unmodified Comint mode---without the
1095: specializations of Shell mode.
1096: 
1097: @node Shell Prompts
1098: @subsection Shell Prompts
1099: 
1100: @cindex prompt, shell
1101:   A prompt is text output by a program to show that it is ready to
1102: accept new user input.  Normally, Comint mode (and thus Shell mode)
1103: automatically figures out which part of the buffer is a prompt, based
1104: on the output of the subprocess.  (Specifically, it assumes that any
1105: received output line which doesn't end with a newline is a prompt.)
1106: 
1107:   Comint mode divides the buffer into two types of @dfn{fields}: input
1108: fields (where user input is typed) and output fields (everywhere
1109: else).  Prompts are part of the output fields.  Most Emacs motion
1110: commands do not cross field boundaries, unless they move over multiple
1111: lines.  For instance, when point is in the input field on a shell
1112: command line, @kbd{C-a} puts point at the beginning of the input
1113: field, after the prompt.  Internally, the fields are implemented using
1114: the @code{field} text property (@pxref{Text Properties,,, elisp, the
1115: Emacs Lisp Reference Manual}).
1116: 
1117: @vindex comint-use-prompt-regexp
1118: @vindex shell-prompt-pattern
1119:   If you change the variable @code{comint-use-prompt-regexp} to a
1120: non-@code{nil} value, then Comint mode will recognize prompts using a
1121: regular expression (@pxref{Regexps}).  In Shell mode, the regular
1122: expression is specified by the variable @code{shell-prompt-pattern}.
1123: The default value of @code{comint-use-prompt-regexp} is @code{nil},
1124: because this method for recognizing prompts is unreliable, but you may
1125: want to set it to a non-@code{nil} value in unusual circumstances.  In
1126: that case, Emacs does not divide the Comint buffer into fields, so the
1127: general motion commands behave as they normally do in buffers without
1128: special text properties.  However, you can use the paragraph motion
1129: commands to conveniently navigate the buffer (@pxref{Paragraphs}); in
1130: Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph
1131: boundaries.
1132: 
1133: @node Shell History
1134: @subsection Shell Command History
1135: 
1136:   Shell buffers support three ways of repeating earlier commands.  You
1137: can use keys like those used for the minibuffer history; these work
1138: much as they do in the minibuffer, inserting text from prior commands
1139: while point remains always at the end of the buffer.  You can move
1140: through the buffer to previous inputs in their original place, then
1141: resubmit them or copy them to the end.  Or you can use a
1142: @samp{!}-style history reference.
1143: 
1144: @menu
1145: * Ring: Shell Ring.             Fetching commands from the history list.
1146: * Copy: Shell History Copying.  Moving to a command and then copying it.
1147: * History References::          Expanding @samp{!}-style history references.
1148: @end menu
1149: 
1150: @node Shell Ring
1151: @subsubsection Shell History Ring
1152: 
1153: @table @kbd
1154: @findex comint-previous-input
1155: @kindex M-p @r{(Shell mode)}
1156: @item M-p
1157: @itemx C-@key{UP}
1158: Fetch the next earlier old shell command
1159: (@code{comint-previous-input}).
1160: 
1161: @kindex M-n @r{(Shell mode)}
1162: @findex comint-next-input
1163: @item M-n
1164: @itemx C-@key{DOWN}
1165: Fetch the next later old shell command (@code{comint-next-input}).
1166: 
1167: @kindex M-r @r{(Shell mode)}
1168: @findex comint-history-isearch-backward-regexp
1169: @item M-r
1170: Begin an incremental regexp search of old shell commands
1171: (@code{comint-history-isearch-backward-regexp}).
1172: 
1173: @item C-c C-x
1174: @kindex C-c C-x @r{(Shell mode)}
1175: @findex comint-get-next-from-history
1176: Fetch the next subsequent command from the history
1177: (@code{comint-get-next-from-history}).
1178: 
1179: @item C-c .
1180: @kindex C-c . @r{(Shell mode)}
1181: @findex comint-insert-previous-argument
1182: Fetch one argument from an old shell command
1183: (@code{comint-input-previous-argument}).
1184: 
1185: @item C-c C-l
1186: @kindex C-c C-l @r{(Shell mode)}
1187: @findex comint-dynamic-list-input-ring
1188: Display the buffer's history of shell commands in another window
1189: (@code{comint-dynamic-list-input-ring}).
1190: @end table
1191: 
1192:   Shell buffers provide a history of previously entered shell
1193: commands.  To reuse shell commands from the history, use the editing
1194: commands @kbd{M-p}, @kbd{M-n}, and @kbd{M-r}.  These work
1195: similar to the minibuffer history commands (@pxref{Minibuffer
1196: History}), except that they operate within the Shell buffer rather
1197: than the minibuffer, and @code{M-r} in a Shell buffer invokes
1198: incremental search through shell command history.
1199: 
1200:   @kbd{M-p} fetches an earlier shell command to the end of the shell
1201: buffer.  Successive use of @kbd{M-p} fetches successively earlier
1202: shell commands, each replacing any text that was already present as
1203: potential shell input.  @kbd{M-n} does likewise except that it finds
1204: successively more recent shell commands from the buffer.
1205: @kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
1206: @kbd{M-n}.
1207: 
1208:   The history search command @kbd{M-r} begins an incremental regular
1209: expression search of previous shell commands.  After typing @kbd{M-r},
1210: start typing the desired string or regular expression; the last
1211: matching shell command will be displayed in the current line.
1212: Incremental search commands have their usual effects---for instance,
1213: @kbd{C-s} and @kbd{C-r} search forward and backward for the next match
1214: (@pxref{Incremental Search}).  When you find the desired input, type
1215: @key{RET} to terminate the search.  This puts the input in the command
1216: line.  Any partial input you were composing before navigating the
1217: history list is restored when you go to the beginning or end of the
1218: history ring.
1219: 
1220:   Often it is useful to reexecute several successive shell commands that
1221: were previously executed in sequence.  To do this, first find and
1222: reexecute the first command of the sequence.  Then type @kbd{C-c C-x};
1223: that will fetch the following command---the one that follows the command
1224: you just repeated.  Then type @key{RET} to reexecute this command.  You
1225: can reexecute several successive commands by typing @kbd{C-c C-x
1226: @key{RET}} over and over.
1227: 
1228:   The command @kbd{C-c .}@: (@code{comint-insert-previous-argument})
1229: copies an individual argument from a previous command, like
1230: @kbd{@key{ESC} .}@: in Bash and @command{zsh}.  The simplest use
1231: copies the last argument from the previous shell command.  With a
1232: prefix argument @var{n}, it copies the @var{n}th argument instead.
1233: Repeating @kbd{C-c .} copies from an earlier shell commands, always
1234: using the same value of @var{n}  (don't give a prefix argument when
1235: you repeat the @kbd{C-c .} command).
1236: 
1237: @vindex comint-insert-previous-argument-from-end
1238:   If you set @code{comint-insert-previous-argument-from-end} to a
1239: non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th
1240: argument counting from the last one; this emulates @kbd{@key{ESC} .}@:
1241: in @command{zsh}.
1242: 
1243:   These commands get the text of previous shell commands from a special
1244: history list, not from the shell buffer itself.  Thus, editing the shell
1245: buffer, or even killing large parts of it, does not affect the history
1246: that these commands access.
1247: 
1248: @vindex shell-input-ring-file-name
1249:   Some shells store their command histories in files so that you can
1250: refer to commands from previous shell sessions.  Emacs reads
1251: the command history file for your chosen shell, to initialize its own
1252: command history.  The file name is @file{~/.bash_history} for bash,
1253: @file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
1254: 
1255: @node Shell History Copying
1256: @subsubsection Shell History Copying
1257: 
1258: @table @kbd
1259: @kindex C-c C-p @r{(Shell mode)}
1260: @findex comint-previous-prompt
1261: @item C-c C-p
1262: Move point to the previous prompt (@code{comint-previous-prompt}).
1263: 
1264: @kindex C-c C-n @r{(Shell mode)}
1265: @findex comint-next-prompt
1266: @item C-c C-n
1267: Move point to the following prompt (@code{comint-next-prompt}).
1268: 
1269: @kindex C-c RET @r{(Shell mode)}
1270: @findex comint-copy-old-input
1271: @item C-c @key{RET}
1272: Copy the input command at point, inserting the copy at the end of the
1273: buffer (@code{comint-copy-old-input}).  This is useful if you move
1274: point back to a previous command.  After you copy the command, you can
1275: submit the copy as input with @key{RET}.  If you wish, you can edit
1276: the copy before resubmitting it.  If you use this command on an output
1277: line, it copies that line to the end of the buffer.
1278: 
1279: @item mouse-2
1280: If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
1281: the old input command that you click on, inserting the copy at the end
1282: of the buffer (@code{comint-insert-input}).  If
1283: @code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
1284: not over old input, just yank as usual.
1285: @end table
1286: 
1287:   Moving to a previous input and then copying it with @kbd{C-c
1288: @key{RET}} or @kbd{mouse-2} produces the same results---the same
1289: buffer contents---that you would get by using @kbd{M-p} enough times
1290: to fetch that previous input from the history list.  However, @kbd{C-c
1291: @key{RET}} copies the text from the buffer, which can be different
1292: from what is in the history list if you edit the input text in the
1293: buffer after it has been sent.
1294: 
1295: @node History References
1296: @subsubsection Shell History References
1297: @cindex history reference
1298: 
1299:   Various shells, including csh and bash, support @dfn{history
1300: references} that begin with @samp{!} and @samp{^}.  Shell mode
1301: recognizes these constructs, and can perform the history substitution
1302: for you.
1303: 
1304:   If you insert a history reference and type @key{TAB}, this searches
1305: the input history for a matching command, performs substitution if
1306: necessary, and places the result in the buffer in place of the history
1307: reference.  For example, you can fetch the most recent command
1308: beginning with @samp{mv} with @kbd{! m v @key{TAB}}.  You can edit the
1309: command if you wish, and then resubmit the command to the shell by
1310: typing @key{RET}.
1311: 
1312: @vindex comint-input-autoexpand
1313: @findex comint-magic-space
1314:   Shell mode can optionally expand history references in the buffer
1315: when you send them to the shell.  To request this, set the variable
1316: @code{comint-input-autoexpand} to @code{input}.  You can make
1317: @key{SPC} perform history expansion by binding @key{SPC} to the
1318: command @code{comint-magic-space}.  @xref{Rebinding}.
1319: 
1320:   Shell mode recognizes history references when they follow a prompt.
1321: @xref{Shell Prompts}, for how Shell mode recognizes prompts.
1322: 
1323: @node Directory Tracking
1324: @subsection Directory Tracking
1325: @cindex directory tracking
1326: 
1327: @vindex shell-pushd-regexp
1328: @vindex shell-popd-regexp
1329: @vindex shell-cd-regexp
1330:   Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
1331: commands given to the subshell, in order to keep the Shell buffer's
1332: default directory (@pxref{File Names}) the same as the shell's working
1333: directory.  It recognizes these commands by examining lines of input
1334: that you send.
1335: 
1336:   If you use aliases for these commands, you can tell Emacs to
1337: recognize them also, by setting the variables
1338: @code{shell-pushd-regexp}, @code{shell-popd-regexp}, and
1339: @code{shell-cd-regexp} to the appropriate regular expressions
1340: (@pxref{Regexps}).  For example, if @code{shell-pushd-regexp} matches
1341: the beginning of a shell command line, that line is regarded as a
1342: @code{pushd} command.  These commands are recognized only at the
1343: beginning of a shell command line.
1344: 
1345: @findex dirs
1346:   If Emacs gets confused about changes in the working directory of the
1347: subshell, type @kbd{M-x dirs}.  This command asks the shell for its
1348: working directory and updates the default directory accordingly.  It
1349: works for shells that support the most common command syntax, but may
1350: not work for unusual shells.
1351: 
1352: @findex dirtrack-mode
1353: @cindex Dirtrack mode
1354: @cindex mode, Dirtrack
1355: @vindex dirtrack-list
1356:   You can also use Dirtrack mode, a buffer-local minor mode that
1357: implements an alternative method of tracking the shell's working
1358: directory.  To use this method, your shell prompt must contain the
1359: working directory at all times, and you must supply a regular
1360: expression for recognizing which part of the prompt contains the
1361: working directory; see the documentation of the variable
1362: @code{dirtrack-list} for details.  To use Dirtrack mode, type @kbd{M-x
1363: dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to
1364: @code{shell-mode-hook} (@pxref{Hooks}).
1365: 
1366: @node Shell Options
1367: @subsection Shell Mode Options
1368: 
1369: @vindex comint-scroll-to-bottom-on-input
1370:   If the variable @code{comint-scroll-to-bottom-on-input} is
1371: non-@code{nil}, insertion and yank commands scroll the selected window
1372: to the bottom before inserting.  The default is @code{nil}.
1373: 
1374: @vindex comint-scroll-show-maximum-output
1375:   If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
1376: arrival of output when point is at the end tries to scroll the last
1377: line of text to the bottom line of the window, showing as much useful
1378: text as possible.  (This mimics the scrolling behavior of most
1379: terminals.)  The default is @code{t}.
1380: 
1381: @vindex comint-move-point-for-output
1382:   By setting @code{comint-move-point-for-output}, you can opt for
1383: having point jump to the end of the buffer whenever output arrives---no
1384: matter where in the buffer point was before.  If the value is
1385: @code{this}, point jumps in the selected window.  If the value is
1386: @code{all}, point jumps in each window that shows the Comint buffer.  If
1387: the value is @code{other}, point jumps in all nonselected windows that
1388: show the current buffer.  The default value is @code{nil}, which means
1389: point does not jump to the end.
1390: 
1391: @vindex comint-prompt-read-only
1392:   If you set @code{comint-prompt-read-only}, the prompts in the Comint
1393: buffer are read-only.
1394: 
1395: @vindex comint-input-ignoredups
1396:   The variable @code{comint-input-ignoredups} controls whether successive
1397: identical inputs are stored in the input history.  A non-@code{nil}
1398: value means to omit an input that is the same as the previous input.
1399: The default is @code{nil}, which means to store each input even if it is
1400: equal to the previous input.
1401: 
1402: @vindex comint-completion-addsuffix
1403: @vindex comint-completion-recexact
1404: @vindex comint-completion-autolist
1405:   Three variables customize file name completion.  The variable
1406: @code{comint-completion-addsuffix} controls whether completion inserts a
1407: space or a slash to indicate a fully completed file or directory name
1408: (non-@code{nil} means do insert a space or slash).
1409: @code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
1410: to choose the shortest possible completion if the usual Emacs completion
1411: algorithm cannot add even a single character.
1412: @code{comint-completion-autolist}, if non-@code{nil}, says to list all
1413: the possible completions whenever completion is not exact.
1414: 
1415: @vindex shell-completion-execonly
1416:   Command completion normally considers only executable files.
1417: If you set @code{shell-completion-execonly} to @code{nil},
1418: it considers nonexecutable files as well.
1419: 
1420: @vindex shell-completion-fignore
1421: @vindex comint-completion-fignore
1422: The variable @code{shell-completion-fignore} specifies a list of file
1423: name extensions to ignore in Shell mode completion.  The default
1424: setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
1425: ignore file names ending in @samp{~}, @samp{#} or @samp{%}.  Other
1426: related Comint modes use the variable @code{comint-completion-fignore}
1427: instead.
1428: 
1429: @findex shell-dynamic-complete-command
1430: Some implementation details of the shell command completion may also be found
1431: in the lisp documentation of the @code{shell-dynamic-complete-command}
1432: function.
1433: 
1434: @findex shell-pushd-tohome
1435: @findex shell-pushd-dextract
1436: @findex shell-pushd-dunique
1437:   You can configure the behavior of @samp{pushd}.  Variables control
1438: whether @samp{pushd} behaves like @samp{cd} if no argument is given
1439: (@code{shell-pushd-tohome}), pop rather than rotate with a numeric
1440: argument (@code{shell-pushd-dextract}), and only add directories to the
1441: directory stack if they are not already on it
1442: (@code{shell-pushd-dunique}).  The values you choose should match the
1443: underlying shell, of course.
1444: 
1445: @vindex comint-terminfo-terminal
1446: @vindex TERM@r{, environment variable, in sub-shell}
1447: Comint mode sets the @env{TERM} environment variable to a safe default
1448: value, but this value disables some useful features.  For example,
1449: color is disabled in applications that use @env{TERM} to determine if
1450: color is supported.  Therefore, Emacs provides an option
1451: @code{comint-terminfo-terminal}, which you can set to a terminal that
1452: is present in your system's terminfo database, in order to take
1453: advantage of advanced features of that terminal.
1454: 
1455: @node Terminal emulator
1456: @subsection Emacs Terminal Emulator
1457: @findex term
1458: 
1459:   To run a subshell in a text terminal emulator, use @kbd{M-x term}.
1460: This creates (or reuses) a buffer named @file{*terminal*}, and runs a
1461: subshell with input coming from your keyboard, and output going to
1462: that buffer.
1463: 
1464: @cindex line mode @r{(terminal emulator)}
1465: @cindex char mode @r{(terminal emulator)}
1466:   The terminal emulator uses Term mode, which has two input modes.  In
1467: @dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell
1468: Mode}).  In @dfn{char mode}, each character is sent directly to the
1469: subshell, as terminal input; the sole exception is the terminal escape
1470: character, which by default is @kbd{C-c} (@pxref{Term Mode}).  Any
1471: echoing of your input is the responsibility of the subshell; any
1472: terminal output from the subshell goes into the buffer, advancing
1473: point.
1474: 
1475:   Some programs (such as Emacs itself) need to control the appearance
1476: of the terminal screen in detail.  They do this by emitting special
1477: control codes.  Term mode recognizes and handles ANSI-standard
1478: VT100-style escape sequences, which are accepted by most modern
1479: terminals, including @command{xterm}.  (Hence, you can actually run
1480: Emacs inside an Emacs Term window.)
1481: 
1482:   The @code{term} face specifies the default appearance of text
1483: in the terminal emulator (the default is the same appearance as the
1484: @code{default} face).  When terminal control codes are used to change
1485: the appearance of text, these are represented in the terminal emulator
1486: by the faces @code{term-color-black}, @code{term-color-red},
1487: @code{term-color-green}, @code{term-color-yellow}
1488: @code{term-color-blue}, @code{term-color-magenta},
1489: @code{term-color-cyan}, @code{term-color-white},
1490: @code{term-color-underline}, and @code{term-color-bold}.
1491: @xref{Faces}.
1492: 
1493:   You can also use Term mode to communicate with a device connected to
1494: a serial port.  @xref{Serial Terminal}.
1495: 
1496:   The file name used to load the subshell is determined the same way
1497: as for Shell mode.  To make multiple terminal emulators, rename the
1498: buffer @file{*terminal*} to something different using @kbd{M-x
1499: rename-uniquely}, just as with Shell mode.
1500: 
1501:   Unlike Shell mode, Term mode does not track the current directory by
1502: examining your input.  But some shells can tell Term what the current
1503: directory is.  This is done automatically by @code{bash} version 1.15
1504: and later.
1505: 
1506: @node Term Mode
1507: @subsection Term Mode
1508: @cindex Term mode
1509: @cindex mode, Term
1510: 
1511:   To switch between line and char mode in Term mode, use these
1512: commands:
1513: 
1514: @table @kbd
1515: @kindex C-c C-j @r{(Term mode)}
1516: @findex term-line-mode
1517: @item C-c C-j
1518: Switch to line mode (@code{term-line-mode}).  Do nothing if already in
1519: line mode.
1520: 
1521: @kindex C-c C-k @r{(Term mode)}
1522: @findex term-char-mode
1523: @item C-c C-k
1524: Switch to char mode (@code{term-char-mode}).  Do nothing if already in
1525: char mode.
1526: @end table
1527: 
1528:   The following commands are only available in char mode:
1529: 
1530: @table @kbd
1531: @item C-c C-c
1532: Send a literal @kbd{C-c} to the sub-shell
1533: (@code{term-interrupt-subjob}).
1534: 
1535: @item C-c @var{char}
1536: This is equivalent to @kbd{C-x @var{char}} in normal Emacs.  For
1537: example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
1538: is normally @samp{other-window}.
1539: @end table
1540: 
1541: @cindex paging in Term mode
1542:   Term mode has a page-at-a-time feature.  When enabled, it makes
1543: output pause at the end of each screenful:
1544: 
1545: @table @kbd
1546: @kindex C-c C-q @r{(Term mode)}
1547: @findex term-pager-toggle
1548: @item C-c C-q
1549: Toggle the page-at-a-time feature (@code{term-pager-toggle}).  This
1550: command works in both line and char modes.  When the feature is
1551: enabled, the mode-line displays the word @samp{page}, and each time
1552: Term receives more than a screenful of output, it pauses and displays
1553: @samp{**MORE**} in the mode-line.  Type @key{SPC} to display the next
1554: screenful of output, or @kbd{?} to see your other options.  The
1555: interface is similar to the @code{more} program.
1556: @end table
1557: 
1558: @node Remote Host
1559: @subsection Remote Host Shell
1560: @cindex remote host
1561: @cindex connecting to remote host
1562: @cindex Telnet
1563: @cindex Rlogin
1564: 
1565:   You can login to a remote computer, using whatever commands you
1566: would from a regular terminal (e.g., using the @command{ssh} or
1567: @command{telnet} or @code{rlogin} commands), from a Term window.
1568: 
1569:   A program that asks you for a password will normally suppress
1570: echoing of the password, so the password will not show up in the
1571: buffer.  This will happen just as if you were using a real terminal,
1572: if the buffer is in char mode.  If it is in line mode, the password is
1573: temporarily visible, but will be erased when you hit return.  (This
1574: happens automatically; there is no special password processing.)
1575: 
1576:   When you log in to a different machine, you need to specify the type
1577: of terminal you're using, by setting the @env{TERM} environment
1578: variable in the environment for the remote login command.  (If you use
1579: bash, you do that by writing the variable assignment before the remote
1580: login command, without a separating comma.)  Terminal types
1581: @samp{ansi} or @samp{vt100} will work on most systems.
1582: 
1583: @node Serial Terminal
1584: @subsection Serial Terminal
1585: @cindex terminal, serial
1586: @findex serial-term
1587: 
1588:   If you have a device connected to a serial port of your computer,
1589: you can communicate with it by typing @kbd{M-x serial-term}.  This
1590: command asks for a serial port name and speed, and switches to a new
1591: Term mode buffer.  Emacs communicates with the serial device through
1592: this buffer just like it does with a terminal in ordinary Term mode.
1593: 
1594:   The speed of the serial port is measured in bits per second.  The
1595: most common speed is 9600 bits per second.  You can change the speed
1596: interactively by clicking on the mode line.
1597: 
1598:   A serial port can be configured even more by clicking on @samp{8N1} in
1599: the mode line.  By default, a serial port is configured as @samp{8N1},
1600: which means that each byte consists of 8 data bits, No parity check
1601: bit, and 1 stopbit.
1602: 
1603:   If the speed or the configuration is wrong, you cannot communicate
1604: with your device and will probably only see garbage output in the
1605: window.
1606: 
1607: @node Emacs Server
1608: @section Using Emacs as a Server
1609: @pindex emacsclient
1610: @cindex Emacs as a server
1611: @cindex server, using Emacs as
1612: @cindex @env{EDITOR} environment variable
1613: 
1614:   Various programs can invoke your choice of editor to edit a
1615: particular piece of text.  For instance, version control programs
1616: invoke an editor to enter version control logs (@pxref{Version
1617: Control}), and the Unix @command{mail} utility invokes an editor to
1618: enter a message to send.  By convention, your choice of editor is
1619: specified by the environment variable @env{EDITOR}.  If you set
1620: @env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an
1621: inconvenient way---by starting a new Emacs process.  This is
1622: inconvenient because the new Emacs process doesn't share buffers, a
1623: command history, or other kinds of information with any existing Emacs
1624: process.
1625: 
1626:   You can solve this problem by setting up Emacs as an @dfn{edit
1627: server}, so that it ``listens'' for external edit requests and acts
1628: accordingly.  There are various ways to start an Emacs server:
1629: 
1630: @itemize
1631: @findex server-start
1632: @item
1633: Run the command @code{server-start} in an existing Emacs process:
1634: either type @kbd{M-x server-start}, or put the expression
1635: @code{(server-start)} in your init file (@pxref{Init File}).  The
1636: existing Emacs process is the server; when you exit Emacs, the server
1637: dies with the Emacs process.
1638: 
1639: @cindex daemon, Emacs
1640: @item
1641: Run Emacs as a @dfn{daemon}, using one of the @samp{--daemon} command-line
1642: options.  @xref{Initial Options}.  When Emacs is started this way, it
1643: calls @code{server-start} after initialization and does not open an
1644: initial frame.  It then waits for edit requests from clients.
1645: 
1646: @cindex systemd unit file
1647: @item
1648: If your operating system uses @command{systemd} to manage startup,
1649: you can automatically start Emacs in daemon mode when you login
1650: using the supplied @dfn{systemd unit file}.  To activate this:
1651: @example
1652: systemctl --user enable emacs
1653: @end example
1654: (If your Emacs was installed into a non-standard location, you may
1655: need to copy the @file{emacs.service} file to a standard directory
1656: such as @file{~/.config/systemd/user/}.)
1657: 
1658: @cindex socket activation, systemd, Emacs
1659: @item
1660: An external process can invoke the Emacs server when a connection
1661: event occurs upon a specified socket and pass the socket to the new
1662: Emacs server process.  An instance of this is the socket functionality
1663: of @command{systemd}: the @command{systemd} service creates a socket and
1664: listens for connections on it; when @command{emacsclient} connects to
1665: it for the first time, @command{systemd} can launch the Emacs server
1666: and hand over the socket to it for servicing @command{emacsclient}
1667: connections.  A setup to use this functionality could be:
1668: 
1669: @file{~/.config/systemd/user/emacs.socket}:
1670: @example
1671: [Socket]
1672: ListenStream=/path/to/.emacs.socket
1673: 
1674: [Install]
1675: WantedBy=sockets.target
1676: @end example
1677: 
1678: (The @file{emacs.service} file described above must also be installed.)
1679: 
1680: The @code{ListenStream} path will be the path that Emacs listens for
1681: connections from @command{emacsclient}; this is a file of your choice.
1682: @end itemize
1683: 
1684: @cindex @env{TEXEDIT} environment variable
1685:   Once an Emacs server is started, you can use a shell
1686: command called @command{emacsclient} to connect to the Emacs process
1687: and tell it to visit a file.  You can then set the @env{EDITOR}
1688: environment variable to @samp{emacsclient}, so that external programs
1689: will use the existing Emacs process for editing.@footnote{Some
1690: programs use a different environment variable; for example, to make
1691: @TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment
1692: variable to @samp{emacsclient +%d %s}.}
1693: 
1694: @vindex server-name
1695:   You can run multiple Emacs servers on the same machine by giving
1696: each one a unique @dfn{server name}, using the variable
1697: @code{server-name}.  For example, @kbd{M-x set-variable @key{RET}
1698: server-name @key{RET} "foo" @key{RET}} sets the server name to
1699: @samp{foo}.  The @code{emacsclient} program can specify a server by
1700: name, using the @samp{-s} or the @samp{-f} option (@pxref{emacsclient
1701: Options}), depending on whether or not the server uses a TCP socket
1702: (@pxref{TCP Emacs server}).
1703: 
1704:   If you want to run multiple Emacs daemons (@pxref{Initial Options}),
1705: you can give each daemon its own server name like this:
1706: 
1707: @example
1708:   emacs --daemon=foo
1709: @end example
1710: 
1711: @findex server-eval-at
1712:   If you have defined a server by a unique server name, it is possible
1713: to connect to the server from another Emacs instance and evaluate Lisp
1714: expressions on the server, using the @code{server-eval-at} function.
1715: For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the
1716: expression @code{(+ 1 2)} on the @samp{foo} server, and returns
1717: @code{3}.  (If there is no server with that name, an error is
1718: signaled.)  Currently, this feature is mainly useful for developers.
1719: 
1720: @menu
1721: * TCP Emacs server::     Listening to a TCP socket.
1722: * Invoking emacsclient:: Connecting to the Emacs server.
1723: * emacsclient Options::  Emacs client startup options.
1724: @end menu
1725: 
1726: @node TCP Emacs server
1727: @subsection TCP Emacs server
1728: @cindex TCP Emacs server
1729: 
1730: @vindex server-use-tcp
1731:   An Emacs server usually listens to connections on a local Unix
1732: domain socket.  Some operating systems, such as MS-Windows, do not
1733: support local sockets; in that case, the server uses TCP sockets
1734: instead.  In some cases it is useful to have the server listen on a
1735: TCP socket even if local sockets are supported, e.g., if you need to
1736: contact the Emacs server from a remote machine.  You can set
1737: @code{server-use-tcp} to non-@code{nil} to have Emacs listen on a TCP
1738: socket instead of a local socket.  This is the default if your OS does
1739: not support local sockets.
1740: 
1741: @vindex server-host
1742: @vindex server-port
1743:   If the Emacs server is set to use TCP, it will by default listen on
1744: a random port on the localhost interface.  This can be changed to
1745: another interface and/or a fixed port using the variables
1746: @code{server-host} and @code{server-port}.
1747: 
1748: @vindex server-auth-key
1749:   A TCP socket is not subject to file system permissions.  To retain
1750: some control over which users can talk to an Emacs server over TCP
1751: sockets, the @command{emacsclient} program must send an authorization
1752: key to the server.  This key is normally randomly generated by the
1753: Emacs server.  This is the recommended mode of operation.
1754: 
1755: @findex server-generate-key
1756:   If needed, you can set the authorization key to a static value by
1757: setting the @code{server-auth-key} variable.  The key must consist of
1758: 64 ASCII printable characters except for space (this means characters
1759: from @samp{!} to @samp{~}, or from decimal code 33 to 126).  You can
1760: use @kbd{M-x server-generate-key} to get a random key.
1761: 
1762: @vindex server-auth-dir
1763: @cindex server file
1764:   When you start a TCP Emacs server, Emacs creates a @dfn{server file}
1765: containing the TCP information to be used by @command{emacsclient} to
1766: connect to the server.  The variable @code{server-auth-dir} specifies
1767: the default directory containing the server file; by default, this is
1768: @file{~/.emacs.d/server/}.  In the absence of a local socket with file
1769: permissions, the permissions of this directory determine which users
1770: can have their @command{emacsclient} processes talk to the Emacs
1771: server.  If @code{server-name} is an absolute file name, the server
1772: file is created where specified by that file name.
1773: 
1774: @vindex EMACS_SERVER_FILE@r{, environment variable}
1775:   To tell @command{emacsclient} to connect to the server over TCP with
1776: a specific server file, use the @samp{-f} or @samp{--server-file}
1777: option, or set the @env{EMACS_SERVER_FILE} environment variable
1778: (@pxref{emacsclient Options}).  If @code{server-auth-dir} is set to a
1779: non-standard value, or if @code{server-name} is set to an absolute
1780: file name, @command{emacsclient} needs an absolute file name to the
1781: server file, as the default @code{server-auth-dir} is hard-coded in
1782: @command{emacsclient} to be used as the directory for resolving
1783: relative filenames.
1784: 
1785: @node Invoking emacsclient
1786: @subsection Invoking @code{emacsclient}
1787: @cindex @code{emacsclient} invocation
1788: 
1789:   The simplest way to use the @command{emacsclient} program is to run
1790: the shell command @samp{emacsclient @var{file}}, where @var{file} is a
1791: file name.  This connects to an Emacs server, and tells that Emacs
1792: process to visit @var{file} in one of its existing frames---either a
1793: graphical frame, or one in a text terminal (@pxref{Frames}).  You
1794: can then select that frame to begin editing.
1795: 
1796:   If there is no Emacs server, the @command{emacsclient} program halts
1797: with an error message (you can prevent this from happening by using
1798: the @samp{--alternate-editor=""} option to @command{emacsclient},
1799: @pxref{emacsclient Options}).  If the Emacs process has no existing
1800: frame---which can happen if it was started as a daemon (@pxref{Emacs
1801: Server})---then Emacs opens a frame on the terminal in which you
1802: called @command{emacsclient}.
1803: 
1804:   You can also force @command{emacsclient} to open a new frame on a
1805: graphical display using the @samp{-c} option, or on a text terminal
1806: using the @samp{-t} option.  @xref{emacsclient Options}.
1807: 
1808:   If you are running on a single text terminal, you can switch between
1809: @command{emacsclient}'s shell and the Emacs server using one of two
1810: methods: (i) run the Emacs server and @command{emacsclient} on
1811: different virtual terminals, and switch to the Emacs server's virtual
1812: terminal after calling @command{emacsclient}; or (ii) call
1813: @command{emacsclient} from within the Emacs server itself, using Shell
1814: mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode});
1815: @command{emacsclient} blocks only the subshell under Emacs, and you can
1816: still use Emacs to edit the file.
1817: 
1818: @kindex C-x #
1819: @findex server-edit
1820:   When you finish editing @var{file} in the Emacs server, type
1821: @kbd{C-x #} (@code{server-edit}) in its buffer.  This saves the file
1822: and sends a message back to the @command{emacsclient} program, telling
1823: it to exit.  Programs that use @env{EDITOR} usually wait for the
1824: editor---in this case @command{emacsclient}---to exit before doing
1825: something else.
1826: 
1827:   You can also call @command{emacsclient} with multiple file name
1828: arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
1829: Emacs server to visit @var{file1}, @var{file2}, and so forth.  Emacs
1830: selects the buffer visiting @var{file1}, and buries the other buffers
1831: at the bottom of the buffer list (@pxref{Buffers}).  The
1832: @command{emacsclient} program exits once all the specified files are
1833: finished (i.e., once you have typed @kbd{C-x #} in each server
1834: buffer).
1835: 
1836: @vindex server-kill-new-buffers
1837: @vindex server-temp-file-regexp
1838:   Finishing with a server buffer also kills the buffer, unless it
1839: already existed in the Emacs session before the server was asked to
1840: create it.  However, if you set @code{server-kill-new-buffers} to
1841: @code{nil}, then a different criterion is used: finishing with a
1842: server buffer kills it if the file name matches the regular expression
1843: @code{server-temp-file-regexp}.  This is set up to distinguish certain
1844: temporary files.
1845: 
1846:   Each @kbd{C-x #} checks for other pending external requests to edit
1847: various files, and selects the next such file.  You can switch to a
1848: server buffer manually if you wish; you don't have to arrive at it
1849: with @kbd{C-x #}.  But @kbd{C-x #} is the way to tell
1850: @command{emacsclient} that you are finished.
1851: 
1852: @vindex server-window
1853:   If you set the value of the variable @code{server-window} to a
1854: window or a frame, @kbd{C-x #} always displays the next server buffer
1855: in that window or in that frame.
1856: 
1857: @node emacsclient Options
1858: @subsection @code{emacsclient} Options
1859: @cindex @code{emacsclient} options
1860: 
1861:   You can pass some optional arguments to the @command{emacsclient}
1862: program, such as:
1863: 
1864: @example
1865: emacsclient -c +12 @var{file1} +4:3 @var{file2}
1866: @end example
1867: 
1868: @noindent
1869: The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments
1870: specify line numbers, or line and column numbers, for the next file
1871: argument.  These behave like the command line arguments for Emacs
1872: itself.  @xref{Action Arguments}.
1873: 
1874:   The other optional arguments recognized by @command{emacsclient} are
1875: listed below:
1876: 
1877: @table @samp
1878: @item -a @var{command}
1879: @itemx --alternate-editor=@var{command}
1880: Specify a shell command to run if @command{emacsclient} fails to
1881: contact Emacs.  This is useful when running @code{emacsclient} in a
1882: script.  The command may include arguments, which may be quoted "like
1883: this".  Currently, escaping of quotes is not supported.
1884: 
1885: As a special exception, if @var{command} is the empty string, then
1886: @command{emacsclient} starts Emacs in daemon mode (as @samp{emacs
1887: --daemon}) and then tries connecting again.
1888: 
1889: @cindex @env{ALTERNATE_EDITOR} environment variable
1890: The environment variable @env{ALTERNATE_EDITOR} has the same effect as
1891: the @samp{-a} option.  If both are present, the latter takes
1892: precedence.
1893: 
1894: @cindex client frame
1895: @item -c
1896: @itemx --create-frame
1897: Create a new graphical @dfn{client frame}, instead of using an
1898: existing Emacs frame.  See below for the special behavior of @kbd{C-x
1899: C-c} in a client frame.  If Emacs cannot create a new graphical frame
1900: (e.g., if it cannot connect to the X server), it tries to create a
1901: text terminal client frame, as though you had supplied the @samp{-t}
1902: option instead.
1903: 
1904: On MS-Windows, a single Emacs session cannot display frames on both
1905: graphical and text terminals, nor on multiple text terminals.  Thus,
1906: if the Emacs server is running on a text terminal, the @samp{-c}
1907: option, like the @samp{-t} option, creates a new frame in the server's
1908: current text terminal.  @xref{Windows Startup}.
1909: 
1910: If you omit a filename argument while supplying the @samp{-c} option,
1911: the new frame displays the @file{*scratch*} buffer by default.  You
1912: can customize this behavior with the variable @code{initial-buffer-choice}
1913: (@pxref{Entering Emacs}).
1914: 
1915: @item -F @var{alist}
1916: @itemx --frame-parameters=@var{alist}
1917: Set the parameters for a newly-created graphical frame
1918: (@pxref{Frame Parameters}).
1919: 
1920: @item -d @var{display}
1921: @itemx --display=@var{display}
1922: Tell Emacs to open the given files on the X display @var{display}
1923: (assuming there is more than one X display available).
1924: 
1925: @item -e
1926: @itemx --eval
1927: Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
1928: files.  When this option is given, the arguments to
1929: @command{emacsclient} are interpreted as a list of expressions to
1930: evaluate, @emph{not} as a list of files to visit.
1931: 
1932: @item -f @var{server-file}
1933: @itemx --server-file=@var{server-file}
1934: Specify a server file (@pxref{TCP Emacs server}) for connecting to an
1935: Emacs server via TCP.  Alternatively, you can set the
1936: @env{EMACS_SERVER_FILE} environment variable to point to the server
1937: file.  (The command-line option overrides the environment variable.)
1938: 
1939: An Emacs server usually uses a local socket to listen for connections,
1940: but also supports connections over TCP.  To connect to a TCP Emacs
1941: server, @command{emacsclient} needs to read a @dfn{server file}
1942: containing the connection details of the Emacs server.  The name of
1943: this file is specified with this option, either as a file name
1944: relative to @file{~/.emacs.d/server} or as an absolute file name.
1945: @xref{TCP Emacs server}.
1946: 
1947: @item -n
1948: @itemx --no-wait
1949: Let @command{emacsclient} exit immediately, instead of waiting until
1950: all server buffers are finished.  You can take as long as you like to
1951: edit the server buffers within Emacs, and they are @emph{not} killed
1952: when you type @kbd{C-x #} in them.
1953: 
1954: @item --parent-id @var{id}
1955: Open an @command{emacsclient} frame as a client frame in the parent X
1956: window with id @var{id}, via the XEmbed protocol.  Currently, this
1957: option is mainly useful for developers.
1958: 
1959: @item -q
1960: @itemx --quiet
1961: Do not let @command{emacsclient} display messages about waiting for
1962: Emacs or connecting to remote server sockets.
1963: 
1964: @item -u
1965: @itemx --suppress-output
1966: Do not let @command{emacsclient} display results returned from the
1967: server.  Mostly useful in combination with @samp{-e} when the
1968: evaluation performed is for side-effect rather than result.
1969: 
1970: @item -s @var{server-name}
1971: @itemx --socket-name=@var{server-name}
1972: Connect to the Emacs server named @var{server-name}.  (This option is
1973: not supported on MS-Windows.)  The server name is given by the
1974: variable @code{server-name} on the Emacs server.  If this option is
1975: omitted, @command{emacsclient} connects to the first server it finds.
1976: If you set @code{server-name} of the Emacs server to an absolute file
1977: name, give the same absolute file name as @var{server-name} to this
1978: option to instruct @command{emacsclient} to connect to that server.
1979: 
1980: Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment
1981: variable to point to the server socket.  (The command-line option
1982: overrides the environment variable.)
1983: 
1984: @item -t
1985: @itemx --tty
1986: @itemx -nw
1987: Create a new client frame on the current text terminal, instead of
1988: using an existing Emacs frame.  This behaves just like the @samp{-c}
1989: option, described above, except that it creates a text terminal frame
1990: (@pxref{Non-Window Terminals}).
1991: 
1992: On MS-Windows, @samp{-t} behaves just like @samp{-c} if the Emacs
1993: server is using the graphical display, but if the Emacs server is
1994: running on a text terminal, it creates a new frame in the current text
1995: terminal.
1996: 
1997: @item -T @var{tramp-prefix}
1998: @itemx --tramp-prefix=@var{tramp-prefix}
1999: Set the prefix to add to filenames for Emacs to locate files on remote
2000: machines (@pxref{Remote Files}) using TRAMP (@pxref{Top, The Tramp
2001: Manual,, tramp, The Tramp Manual}).  This is mostly useful in
2002: combination with using the Emacs server over TCP (@pxref{TCP Emacs
2003: server}).  By ssh-forwarding the listening port and making the
2004: @var{server-file} available on a remote machine, programs on the
2005: remote machine can use @command{emacsclient} as the value for the
2006: @env{EDITOR} and similar environment variables, but instead of talking
2007: to an Emacs server on the remote machine, the files will be visited in
2008: the local Emacs session using TRAMP.
2009: 
2010: @vindex EMACSCLIENT_TRAMP@r{, environment variable}
2011: Setting the environment variable @env{EMACSCLIENT_TRAMP} has the same
2012: effect as using the @samp{-T} option.  If both are specified, the
2013: command-line option takes precedence.
2014: 
2015: For example, assume two hosts, @samp{local} and @samp{remote}, and
2016: that the local Emacs listens on tcp port 12345.  Assume further that
2017: @file{/home} is on a shared file system, so that the server file
2018: @file{~/.emacs.d/server/server} is readable on both hosts.
2019: 
2020: @example
2021: local$ ssh -R12345:localhost:12345 remote
2022: remote$ export EDITOR="emacsclient \
2023:         --server-file=server \
2024:         --tramp=/ssh:remote:"
2025: remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
2026: @end example
2027: 
2028: @end table
2029: 
2030:   The new graphical or text terminal frames created by the @samp{-c}
2031: or @samp{-t} options are considered @dfn{client frames}.  Any new
2032: frame that you create from a client frame is also considered a client
2033: frame.  If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal})
2034: in a client frame, that command does not kill the Emacs session as it
2035: normally does (@pxref{Exiting}).  Instead, Emacs deletes the client
2036: frame; furthermore, if the client frame has an @command{emacsclient}
2037: waiting to regain control (i.e., if you did not supply the @samp{-n}
2038: option), Emacs deletes all other frames of the same client, and marks
2039: the client's server buffers as finished, as though you had typed
2040: @kbd{C-x #} in all of them.  If it so happens that there are no
2041: remaining frames after the client frame(s) are deleted, the Emacs
2042: session exits.
2043: 
2044:   As an exception, when Emacs is started as a daemon, all frames are
2045: considered client frames, and @kbd{C-x C-c} never kills Emacs.  To
2046: kill a daemon session, type @kbd{M-x kill-emacs}.
2047: 
2048:   Note that the @samp{-t} and @samp{-n} options are contradictory:
2049: @samp{-t} says to take control of the current text terminal to create
2050: a new client frame, while @samp{-n} says not to take control of the
2051: text terminal.  If you supply both options, Emacs visits the specified
2052: files(s) in an existing frame rather than a new client frame, negating
2053: the effect of @samp{-t}.
2054: 
2055: @node Printing
2056: @section Printing Hard Copies
2057: @cindex hardcopy
2058: @cindex printing
2059: 
2060:   Emacs provides commands for printing hardcopies of either an entire
2061: buffer or part of one.  You can invoke the printing commands directly,
2062: as detailed below, or using the @samp{File} menu on the menu bar.
2063: 
2064: @findex htmlfontify-buffer
2065:   Aside from the commands described in this section, you can also
2066: print hardcopies from Dired (@pxref{Operating on Files}) and the diary
2067: (@pxref{Displaying the Diary}).  You can also ``print'' an Emacs
2068: buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which
2069: converts the current buffer to a HTML file, replacing Emacs faces with
2070: CSS-based markup.  Furthermore, Org mode allows you to print Org
2071: files to a variety of formats, such as PDF (@pxref{Org Mode}).
2072: 
2073: @table @kbd
2074: @item M-x print-buffer
2075: Print hardcopy of current buffer with page headings containing the
2076: file name and page number.
2077: @item M-x lpr-buffer
2078: Print hardcopy of current buffer without page headings.
2079: @item M-x print-region
2080: Like @code{print-buffer} but print only the current region.
2081: @item M-x lpr-region
2082: Like @code{lpr-buffer} but print only the current region.
2083: @end table
2084: 
2085: @findex print-buffer
2086: @findex print-region
2087: @findex lpr-buffer
2088: @findex lpr-region
2089: @vindex lpr-switches
2090: @vindex lpr-commands
2091:   On most operating systems, the above hardcopy commands submit files
2092: for printing by calling the @command{lpr} program.  To change the
2093: printer program, customize the variable @code{lpr-command}.  To
2094: specify extra switches to give the printer program, customize the list
2095: variable @code{lpr-switches}.  Its value should be a list of option
2096: strings, each of which should start with @samp{-} (e.g., the option
2097: string @code{"-w80"} specifies a line width of 80 columns).  The
2098: default is the empty list, @code{nil}.
2099: 
2100: @vindex printer-name
2101: @vindex lpr-printer-switch
2102:   To specify the printer to use, set the variable @code{printer-name}.
2103: The default, @code{nil}, specifies the default printer.  If you set it
2104: to a printer name (a string), that name is passed to @command{lpr}
2105: with the @samp{-P} switch; if you are not using @command{lpr}, you
2106: should specify the switch with @code{lpr-printer-switch}.
2107: 
2108: @vindex lpr-headers-switches
2109: @vindex lpr-add-switches
2110:   The variable @code{lpr-headers-switches} similarly specifies the
2111: extra switches to use to make page headers.  The variable
2112: @code{lpr-add-switches} controls whether to supply @samp{-T} and
2113: @samp{-J} options (suitable for @command{lpr}) to the printer program:
2114: @code{nil} means don't add them (this should be the value if your
2115: printer program is not compatible with @command{lpr}).
2116: 
2117: @menu
2118: * PostScript::           Printing buffers or regions as PostScript.
2119: * PostScript Variables:: Customizing the PostScript printing commands.
2120: * Printing Package::     An optional advanced printing interface.
2121: @end menu
2122: 
2123: @node PostScript
2124: @subsection PostScript Hardcopy
2125: 
2126:   These commands convert buffer contents to PostScript,
2127: either printing it or leaving it in another Emacs buffer.
2128: 
2129: @table @kbd
2130: @item M-x ps-print-buffer
2131: Print hardcopy of the current buffer in PostScript form.
2132: @item M-x ps-print-region
2133: Print hardcopy of the current region in PostScript form.
2134: @item M-x ps-print-buffer-with-faces
2135: Print hardcopy of the current buffer in PostScript form, showing the
2136: faces used in the text by means of PostScript features.
2137: @item M-x ps-print-region-with-faces
2138: Print hardcopy of the current region in PostScript form, showing the
2139: faces used in the text.
2140: @item M-x ps-spool-buffer
2141: Generate and spool a PostScript image for the current buffer text.
2142: @item M-x ps-spool-region
2143: Generate and spool a PostScript image for the current region.
2144: @item M-x ps-spool-buffer-with-faces
2145: Generate and spool a PostScript image for the current buffer, showing the faces used.
2146: @item M-x ps-spool-region-with-faces
2147: Generate and spool a PostScript image for the current region, showing the faces used.
2148: @item M-x ps-despool
2149: Send the spooled PostScript to the printer.
2150: @item M-x handwrite
2151: Generate/print PostScript for the current buffer as if handwritten.
2152: @end table
2153: 
2154: @findex ps-print-region
2155: @findex ps-print-buffer
2156: @findex ps-print-region-with-faces
2157: @findex ps-print-buffer-with-faces
2158:   The @code{ps-print-buffer} and @code{ps-print-region} commands print
2159: buffer contents in PostScript form.  One command prints the entire
2160: buffer; the other, just the region.  The commands
2161: @code{ps-print-buffer-with-faces} and
2162: @code{ps-print-region-with-faces} behave similarly, but use PostScript
2163: features to show the faces (fonts and colors) of the buffer text.
2164: 
2165:   Interactively, when you use a prefix argument (@kbd{C-u}), these commands
2166: prompt the user for a file name, and save the PostScript image in that file
2167: instead of sending it to the printer.
2168: 
2169: @findex ps-spool-region
2170: @findex ps-spool-buffer
2171: @findex ps-spool-region-with-faces
2172: @findex ps-spool-buffer-with-faces
2173:   The commands whose names have @samp{spool} instead of @samp{print},
2174: generate the PostScript output in an Emacs buffer instead of sending
2175: it to the printer.
2176: 
2177: @findex ps-despool
2178:   Use the command @code{ps-despool} to send the spooled images to the
2179: printer.  This command sends the PostScript generated by
2180: @samp{-spool-} commands (see commands above) to the printer.  With a
2181: prefix argument (@kbd{C-u}), it prompts for a file name, and saves the
2182: spooled PostScript image in that file instead of sending it to the
2183: printer.
2184: 
2185: @findex handwrite
2186: @cindex handwriting
2187:   @kbd{M-x handwrite} is more frivolous.  It generates a PostScript
2188: rendition of the current buffer as a cursive handwritten document.  It
2189: can be customized in group @code{handwrite}.  This function only
2190: supports ISO 8859-1 characters.
2191: 
2192: @node PostScript Variables
2193: @subsection Variables for PostScript Hardcopy
2194: 
2195: @vindex ps-lpr-command
2196: @vindex ps-lpr-switches
2197: @vindex ps-printer-name
2198:   All the PostScript hardcopy commands use the variables
2199: @code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
2200: the output.  @code{ps-lpr-command} specifies the command name to run,
2201: @code{ps-lpr-switches} specifies command line options to use, and
2202: @code{ps-printer-name} specifies the printer.  If you don't set the
2203: first two variables yourself, they take their initial values from
2204: @code{lpr-command} and @code{lpr-switches}.  If @code{ps-printer-name}
2205: is @code{nil}, @code{printer-name} is used.
2206: 
2207: @vindex ps-print-header
2208:   The variable @code{ps-print-header} controls whether these commands
2209: add header lines to each page---set it to @code{nil} to turn headers
2210: off.
2211: 
2212: @cindex color emulation on black-and-white printers
2213: @vindex ps-print-color-p
2214:   If your printer doesn't support colors, you should turn off color
2215: processing by setting @code{ps-print-color-p} to @code{nil}.  By
2216: default, if the display supports colors, Emacs produces hardcopy output
2217: with color information; on black-and-white printers, colors are emulated
2218: with shades of gray.  This might produce illegible output, even if your
2219: screen colors only use shades of gray.
2220: 
2221:   Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to
2222: print colors on black/white printers.
2223: 
2224: @vindex ps-use-face-background
2225:   By default, PostScript printing ignores the background colors of the
2226: faces, unless the variable @code{ps-use-face-background} is
2227: non-@code{nil}.  This is to avoid unwanted interference with the zebra
2228: stripes and background image/text.
2229: 
2230: @vindex ps-paper-type
2231: @vindex ps-page-dimensions-database
2232:   The variable @code{ps-paper-type} specifies which size of paper to
2233: format for; legitimate values include @code{a4}, @code{a3},
2234: @code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger},
2235: @code{legal}, @code{letter}, @code{letter-small}, @code{statement},
2236: @code{tabloid}.  The default is @code{letter}.  You can define
2237: additional paper sizes by changing the variable
2238: @code{ps-page-dimensions-database}.
2239: 
2240: @vindex ps-landscape-mode
2241:   The variable @code{ps-landscape-mode} specifies the orientation of
2242: printing on the page.  The default is @code{nil}, which stands for
2243: portrait mode.  Any non-@code{nil} value specifies landscape
2244: mode.
2245: 
2246: @vindex ps-number-of-columns
2247:   The variable @code{ps-number-of-columns} specifies the number of
2248: columns; it takes effect in both landscape and portrait mode.  The
2249: default is 1.
2250: 
2251: @vindex ps-font-family
2252: @vindex ps-font-size
2253: @vindex ps-font-info-database
2254:   The variable @code{ps-font-family} specifies which font family to use
2255: for printing ordinary text.  Legitimate values include @code{Courier},
2256: @code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
2257: @code{Times}.  The variable @code{ps-font-size} specifies the size of
2258: the font for ordinary text and defaults to 8.5 points.  The value of
2259: @code{ps-font-size} can also be a cons of 2 floats: one for landscape
2260: mode, the other for portrait mode.
2261: 
2262: @vindex ps-multibyte-buffer
2263: @cindex Intlfonts for PostScript printing
2264: @cindex fonts for PostScript printing
2265:   Emacs supports more scripts and characters than a typical PostScript
2266: printer.  Thus, some of the characters in your buffer might not be
2267: printable using the fonts built into your printer.  You can augment
2268: the fonts supplied with the printer with those from the GNU Intlfonts
2269: package, or you can instruct Emacs to use Intlfonts exclusively.  The
2270: variable @code{ps-multibyte-buffer} controls this: the default value,
2271: @code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1
2272: characters; a value of @code{non-latin-printer} is for printers which
2273: have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean
2274: characters built into them.  A value of @code{bdf-font} arranges for
2275: the BDF fonts from the Intlfonts package to be used for @emph{all}
2276: characters.  Finally, a value of @code{bdf-font-except-latin}
2277: instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1
2278: characters, and Intlfonts BDF fonts for the rest.
2279: 
2280: @vindex bdf-directory-list
2281:   To be able to use the BDF fonts, Emacs needs to know where to find
2282: them.  The variable @code{bdf-directory-list} holds the list of
2283: directories where Emacs should look for the fonts; the default value
2284: includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
2285: 
2286:   Many other customization variables for these commands are defined and
2287: described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
2288: 
2289: @node Printing Package
2290: @subsection Printing Package
2291: @cindex Printing package
2292: 
2293:   The basic Emacs facilities for printing hardcopy can be extended
2294: using the Printing package.  This provides an easy-to-use interface
2295: for choosing what to print, previewing PostScript files before
2296: printing, and setting various printing options such as print headers,
2297: landscape or portrait modes, duplex modes, and so forth.  On GNU/Linux
2298: or Unix systems, the Printing package relies on the @file{gs} and
2299: @file{gv} utilities, which are distributed as part of the GhostScript
2300: program.  On MS-Windows, the @file{gstools} port of Ghostscript can be
2301: used.
2302: 
2303: @findex pr-interface
2304:   To use the Printing package, add @code{(require 'printing)} to your
2305: init file (@pxref{Init File}), followed by @code{(pr-update-menus)}.
2306: This function replaces the usual printing commands in the menu bar
2307: with a @samp{Printing} submenu that contains various printing options.
2308: You can also type @kbd{M-x pr-interface @key{RET}}; this creates a
2309: @file{*Printing Interface*} buffer, similar to a customization buffer,
2310: where you can set the printing options.  After selecting what and how
2311: to print, you start the print job using the @samp{Print} button (click
2312: @kbd{mouse-2} on it, or move point over it and type @key{RET}).  For
2313: further information on the various options, use the @samp{Interface
2314: Help} button.
2315: 
2316: @node Sorting
2317: @section Sorting Text
2318: @cindex sorting
2319: 
2320:   Emacs provides several commands for sorting text in the buffer.  All
2321: operate on the contents of the region.
2322: They divide the text of the region into many @dfn{sort records},
2323: identify a @dfn{sort key} for each record, and then reorder the records
2324: into the order determined by the sort keys.  The records are ordered so
2325: that their keys are in alphabetical order, or, for numeric sorting, in
2326: numeric order.  In alphabetic sorting, all upper-case letters @samp{A}
2327: through @samp{Z} come before lower-case @samp{a}, in accordance with the
2328: @acronym{ASCII} character sequence (but @code{sort-fold-case},
2329: described below, can change that).
2330: 
2331:   The various sort commands differ in how they divide the text into sort
2332: records and in which part of each record is used as the sort key.  Most of
2333: the commands make each line a separate sort record, but some commands use
2334: paragraphs or pages as sort records.  Most of the sort commands use each
2335: entire sort record as its own sort key, but some use only a portion of the
2336: record as the sort key.
2337: 
2338: @findex sort-lines
2339: @findex sort-paragraphs
2340: @findex sort-pages
2341: @findex sort-fields
2342: @findex sort-numeric-fields
2343: @vindex sort-numeric-base
2344: @table @kbd
2345: @item M-x sort-lines
2346: Divide the region into lines, and sort by comparing the entire
2347: text of a line.  A numeric argument means sort into descending order.
2348: 
2349: @item M-x sort-paragraphs
2350: Divide the region into paragraphs, and sort by comparing the entire
2351: text of a paragraph (except for leading blank lines).  A numeric
2352: argument means sort into descending order.
2353: 
2354: @item M-x sort-pages
2355: Divide the region into pages, and sort by comparing the entire
2356: text of a page (except for leading blank lines).  A numeric
2357: argument means sort into descending order.
2358: 
2359: @item M-x sort-fields
2360: Divide the region into lines, and sort by comparing the contents of
2361: one field in each line.  Fields are defined as separated by
2362: whitespace, so the first run of consecutive non-whitespace characters
2363: in a line constitutes field 1, the second such run constitutes field
2364: 2, etc.
2365: 
2366: Specify which field to sort by with a numeric argument: 1 to sort by
2367: field 1, etc.; the default is 1.  A negative argument means count
2368: fields from the right instead of from the left; thus, minus 1 means
2369: sort by the last field.  If several lines have identical contents in
2370: the field being sorted, they keep the same relative order that they
2371: had in the original buffer.
2372: 
2373: @item M-x sort-numeric-fields
2374: Like @kbd{M-x sort-fields} except the specified field is converted
2375: to an integer for each line, and the numbers are compared.  @samp{10}
2376: comes before @samp{2} when considered as text, but after it when
2377: considered as a number.  By default, numbers are interpreted according
2378: to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or
2379: @samp{0} are interpreted as hexadecimal and octal, respectively.
2380: 
2381: @item M-x sort-columns
2382: Like @kbd{M-x sort-fields} except that the text within each line
2383: used for comparison comes from a fixed range of columns.  With a
2384: prefix argument, sort in reverse order.  See below for more details
2385: on this command.
2386: 
2387: @findex reverse-region
2388: @item M-x reverse-region
2389: Reverse the order of the lines in the region.  This is useful for
2390: sorting into descending order by fields, since those sort
2391: commands do not have a feature for doing that.
2392: @end table
2393: 
2394:   For example, if the buffer contains this:
2395: 
2396: @smallexample
2397: On systems where clash detection (locking of files being edited) is
2398: implemented, Emacs also checks the first time you modify a buffer
2399: whether the file has changed on disk since it was last visited or
2400: saved.  If it has, you are asked to confirm that you want to change
2401: the buffer.
2402: @end smallexample
2403: 
2404: @noindent
2405: applying @kbd{M-x sort-lines} to the entire buffer produces this:
2406: 
2407: @smallexample
2408: On systems where clash detection (locking of files being edited) is
2409: implemented, Emacs also checks the first time you modify a buffer
2410: saved.  If it has, you are asked to confirm that you want to change
2411: the buffer.
2412: whether the file has changed on disk since it was last visited or
2413: @end smallexample
2414: 
2415: @noindent
2416: where the upper-case @samp{O} sorts before all lower-case letters.  If
2417: you use @kbd{C-u 2 M-x sort-fields} instead, you get this:
2418: 
2419: @smallexample
2420: implemented, Emacs also checks the first time you modify a buffer
2421: saved.  If it has, you are asked to confirm that you want to change
2422: the buffer.
2423: On systems where clash detection (locking of files being edited) is
2424: whether the file has changed on disk since it was last visited or
2425: @end smallexample
2426: 
2427: @noindent
2428: where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
2429: @samp{systems} and @samp{the}.
2430: 
2431: @findex sort-columns
2432:   @kbd{M-x sort-columns} requires more explanation.  You specify the
2433: columns by putting point at one of the columns and the mark at the other
2434: column.  Because this means you cannot put point or the mark at the
2435: beginning of the first line of the text you want to sort, this command
2436: uses an unusual definition of ``region'': all of the line point is in is
2437: considered part of the region, and so is all of the line the mark is in,
2438: as well as all the lines in between.
2439: 
2440:   For example, to sort a table by information found in columns 10 to 15,
2441: you could put the mark on column 10 in the first line of the table, and
2442: point on column 15 in the last line of the table, and then run
2443: @code{sort-columns}.  Equivalently, you could run it with the mark on
2444: column 15 in the first line and point on column 10 in the last line.
2445: 
2446:   This can be thought of as sorting the rectangle specified by point and
2447: the mark, except that the text on each line to the left or right of the
2448: rectangle moves along with the text inside the rectangle.
2449: @xref{Rectangles}.
2450: 
2451: @vindex sort-fold-case
2452:   Many of the sort commands ignore case differences when comparing, if
2453: @code{sort-fold-case} is non-@code{nil}.
2454: 
2455: @c Picture Mode documentation
2456: @ifnottex
2457: @include picture-xtra.texi
2458: @end ifnottex
2459: 
2460: 
2461: @node Editing Binary Files
2462: @section Editing Binary Files
2463: 
2464: @cindex Hexl mode
2465: @cindex mode, Hexl
2466: @cindex editing binary files
2467: @cindex hex editing
2468:   There is a special major mode for editing binary files: Hexl mode.  To
2469: use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
2470: the file.  This command converts the file's contents to hexadecimal and
2471: lets you edit the translation.  When you save the file, it is converted
2472: automatically back to binary.
2473: 
2474:   You can also use @kbd{M-x hexl-mode} to translate an existing buffer
2475: into hex.  This is useful if you visit a file normally and then discover
2476: it is a binary file.
2477: 
2478:   Ordinary text characters overwrite in Hexl mode.  This is to reduce
2479: the risk of accidentally spoiling the alignment of data in the file.
2480: There are special commands for insertion.  Here is a list of the
2481: commands of Hexl mode:
2482: 
2483: @c I don't think individual index entries for these commands are useful--RMS.
2484: @table @kbd
2485: @item C-M-d
2486: Insert a byte with a code typed in decimal.
2487: 
2488: @item C-M-o
2489: Insert a byte with a code typed in octal.
2490: 
2491: @item C-M-x
2492: Insert a byte with a code typed in hex.
2493: 
2494: @item C-x [
2495: Move to the beginning of a 1k-byte page.
2496: 
2497: @item C-x ]
2498: Move to the end of a 1k-byte page.
2499: 
2500: @item M-g
2501: Move to an address specified in hex.
2502: 
2503: @item M-j
2504: Move to an address specified in decimal.
2505: 
2506: @item C-c C-c
2507: Leave Hexl mode, going back to the major mode this buffer had before you
2508: invoked @code{hexl-mode}.
2509: @end table
2510: 
2511: @noindent
2512: Other Hexl commands let you insert strings (sequences) of binary
2513: bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a
2514: hexl-@key{RET}} for details.
2515: 
2516: 
2517: @node Saving Emacs Sessions
2518: @section Saving Emacs Sessions
2519: @cindex saving sessions
2520: @cindex restore session
2521: @cindex remember editing session
2522: @cindex reload files
2523: @cindex desktop
2524: 
2525: @vindex desktop-restore-frames
2526:    Use the desktop library to save the state of Emacs from one session
2527: to another.  Once you save the Emacs @dfn{desktop}---the buffers,
2528: their file names, major modes, buffer positions, and so on---then
2529: subsequent Emacs sessions reload the saved desktop.  By default,
2530: the desktop also tries to save the frame and window configuration.
2531: To disable this, set @code{desktop-restore-frames} to @code{nil}.
2532: (See that variable's documentation for some related options
2533: that you can customize to fine-tune this behavior.)
2534: 
2535: @vindex desktop-files-not-to-save
2536: Information about buffers visiting remote files is not saved by
2537: default.  Customize the variable @code{desktop-files-not-to-save} to
2538: change this.
2539: 
2540: @vindex frameset-filter-alist
2541:    When the desktop restores the frame and window configuration, it
2542: uses the recorded values of frame parameters, disregarding any
2543: settings for those parameters you have in your init file (@pxref{Init
2544: File}).  This means that frame parameters such as fonts and faces for
2545: the restored frames will come from the desktop file, where they were
2546: saved when you exited your previous Emacs session; any settings for
2547: those parameters in your init file will be ignored.  To disable this,
2548: customize the value of @code{frameset-filter-alist} to filter out the
2549: frame parameters you don't want to be restored.
2550: 
2551: @findex desktop-save
2552: @vindex desktop-save-mode
2553:   You can save the desktop manually with the command @kbd{M-x
2554: desktop-save}.  You can also enable automatic saving of the desktop
2555: when you exit Emacs, and automatic restoration of the last saved
2556: desktop when Emacs starts: use the Customization buffer (@pxref{Easy
2557: Customization}) to set @code{desktop-save-mode} to @code{t} for future
2558: sessions, or add this line in your init file (@pxref{Init File}):
2559: 
2560: @example
2561: (desktop-save-mode 1)
2562: @end example
2563: 
2564: @findex desktop-change-dir
2565: @findex desktop-revert
2566: @vindex desktop-path
2567:   If you turn on @code{desktop-save-mode} in your init file, then when
2568: Emacs starts, it looks for a saved desktop in the current directory.
2569: (More precisely, it looks in the directories specified by
2570: @code{desktop-path}, and uses the first desktop it finds.)
2571: Thus, you can have separate saved desktops in different directories,
2572: and the starting directory determines which one Emacs reloads.  You
2573: can save the current desktop and reload one saved in another directory
2574: by typing @kbd{M-x desktop-change-dir}.  Typing @kbd{M-x
2575: desktop-revert} reverts to the desktop previously reloaded.
2576: 
2577:   Specify the option @samp{--no-desktop} on the command line when you
2578: don't want it to reload any saved desktop.  This turns off
2579: @code{desktop-save-mode} for the current session.  Starting Emacs with
2580: the @samp{--no-init-file} option also disables desktop reloading,
2581: since it bypasses the init file, where @code{desktop-save-mode} is
2582: usually turned on.
2583: 
2584: @vindex desktop-restore-eager
2585:   By default, all the buffers in the desktop are restored in one go.
2586: However, this may be slow if there are a lot of buffers in the
2587: desktop.  You can specify the maximum number of buffers to restore
2588: immediately with the variable @code{desktop-restore-eager}; the
2589: remaining buffers are restored lazily, when Emacs is idle.
2590: 
2591: @findex desktop-clear
2592: @vindex desktop-globals-to-clear
2593: @vindex desktop-clear-preserve-buffers-regexp
2594:   Type @kbd{M-x desktop-clear} to empty the Emacs desktop.  This kills
2595: all buffers except for internal ones, and clears the global variables
2596: listed in @code{desktop-globals-to-clear}.  If you want this to
2597: preserve certain buffers, customize the variable
2598: @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
2599: expression matching the names of buffers not to kill.
2600: 
2601:   If you want to save minibuffer history from one session to
2602: another, use the @code{savehist} library.
2603: 
2604: @vindex desktop-auto-save-timeout
2605:   While Emacs runs with @code{desktop-save-mode} turned on, it by
2606: default auto-saves the desktop whenever any of it changes.  The
2607: variable @code{desktop-auto-save-timeout} determines how frequently
2608: Emacs checks for modifications to your desktop.
2609: 
2610: @vindex desktop-load-locked-desktop
2611:   The file in which Emacs saves the desktop is locked while the
2612: session runs, to avoid inadvertently overwriting it from another Emacs
2613: session.  That lock is normally removed when Emacs exits, but if Emacs
2614: or your system crashes, the lock stays, and when you restart Emacs, it
2615: will by default ask you whether to use the locked desktop file.  You
2616: can avoid the question by customizing the variable
2617: @code{desktop-load-locked-desktop} to either @code{nil}, which means
2618: never load the desktop in this case, or @code{t}, which means load the
2619: desktop without asking.
2620: 
2621: @cindex desktop restore in daemon mode
2622:   When Emacs starts in daemon mode, it cannot ask you any questions,
2623: so if it finds the desktop file locked, it will not load it, unless
2624: @code{desktop-load-locked-desktop} is @code{t}.  Note that restoring
2625: the desktop in daemon mode is somewhat problematic for other reasons:
2626: e.g., the daemon cannot use GUI features, so parameters such as frame
2627: position, size, and decorations cannot be restored.  For that reason,
2628: you may wish to delay restoring the desktop in daemon mode until the
2629: first client connects, by calling @code{desktop-read} in a hook
2630: function that you add to @code{server-after-make-frame-hook}
2631: (@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}).
2632: 
2633: @node Recursive Edit
2634: @section Recursive Editing Levels
2635: @cindex recursive editing level
2636: @cindex editing level, recursive
2637: 
2638:   A @dfn{recursive edit} is a situation in which you are using Emacs
2639: commands to perform arbitrary editing while in the middle of another
2640: Emacs command.  For example, when you type @kbd{C-r} inside of a
2641: @code{query-replace}, you enter a recursive edit in which you can change
2642: the current buffer.  On exiting from the recursive edit, you go back to
2643: the @code{query-replace}.  @xref{Query Replace}.
2644: 
2645: @kindex C-M-c
2646: @findex exit-recursive-edit
2647: @cindex exiting recursive edit
2648:   @dfn{Exiting} the recursive edit means returning to the unfinished
2649: command, which continues execution.  The command to exit is @kbd{C-M-c}
2650: (@code{exit-recursive-edit}).
2651: 
2652:   You can also @dfn{abort} the recursive edit.  This is like exiting,
2653: but also quits the unfinished command immediately.  Use the command
2654: @kbd{C-]} (@code{abort-recursive-edit}) to do this.  @xref{Quitting}.
2655: 
2656:   The mode line shows you when you are in a recursive edit by displaying
2657: square brackets around the parentheses that always surround the major and
2658: minor mode names.  Every window's mode line shows this in the same way,
2659: since being in a recursive edit is true of Emacs as a whole rather than
2660: any particular window or buffer.
2661: 
2662:   It is possible to be in recursive edits within recursive edits.  For
2663: example, after typing @kbd{C-r} in a @code{query-replace}, you may type a
2664: command that enters the debugger.  This begins a recursive editing level
2665: for the debugger, within the recursive editing level for @kbd{C-r}.
2666: Mode lines display a pair of square brackets for each recursive editing
2667: level currently in progress.
2668: 
2669:   Exiting the inner recursive edit (such as with the debugger @kbd{c}
2670: command) resumes the command running in the next level up.  When that
2671: command finishes, you can then use @kbd{C-M-c} to exit another recursive
2672: editing level, and so on.  Exiting applies to the innermost level only.
2673: Aborting also gets out of only one level of recursive edit; it returns
2674: immediately to the command level of the previous recursive edit.  If you
2675: wish, you can then abort the next recursive editing level.
2676: 
2677:   Alternatively, the command @kbd{M-x top-level} aborts all levels of
2678: recursive edits, returning immediately to the top-level command
2679: reader.  It also exits the minibuffer, if it is active.
2680: 
2681:   The text being edited inside the recursive edit need not be the same text
2682: that you were editing at top level.  It depends on what the recursive edit
2683: is for.  If the command that invokes the recursive edit selects a different
2684: buffer first, that is the buffer you will edit recursively.  In any case,
2685: you can switch buffers within the recursive edit in the normal manner (as
2686: long as the buffer-switching keys have not been rebound).  You could
2687: probably do all the rest of your editing inside the recursive edit,
2688: visiting files and all.  But this could have surprising effects (such as
2689: stack overflow) from time to time.  So remember to exit or abort the
2690: recursive edit when you no longer need it.
2691: 
2692:   In general, we try to minimize the use of recursive editing levels in
2693: GNU Emacs.  This is because they constrain you to go back in a
2694: particular order---from the innermost level toward the top level.  When
2695: possible, we present different activities in separate buffers so that
2696: you can switch between them as you please.  Some commands switch to a
2697: new major mode which provides a command to switch back.  These
2698: approaches give you more flexibility to go back to unfinished tasks in
2699: the order you choose.
2700: 
2701: @ignore
2702: @c Apart from edt and viper, this is all obsolete.
2703: @c (Can't believe we were saying "most other editors" into 2014!)
2704: @c There seems no point having a node just for those, which both have
2705: @c their own manuals.
2706: @node Emulation
2707: @section Emulation
2708: @cindex emulating other editors
2709: @cindex other editors
2710: @cindex EDT
2711: @cindex vi
2712: @cindex WordStar
2713: 
2714:   GNU Emacs can be programmed to emulate (more or less) most other
2715: editors.  Standard facilities can emulate these:
2716: 
2717: @table @asis
2718: @item CRiSP/Brief (PC editor)
2719: @findex crisp-mode
2720: @vindex crisp-override-meta-x
2721: @findex scroll-all-mode
2722: @cindex CRiSP mode
2723: @cindex Brief emulation
2724: @cindex emulation of Brief
2725: @cindex mode, CRiSP
2726: @kbd{M-x crisp-mode} enables key bindings to emulate the CRiSP/Brief
2727: editor.  Note that this rebinds @kbd{M-x} to exit Emacs unless you set
2728: the variable @code{crisp-override-meta-x}.  You can also use the
2729: command @kbd{M-x scroll-all-mode} or set the variable
2730: @code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature
2731: (scrolling all windows together).
2732: 
2733: @item EDT (DEC VMS editor)
2734: @findex edt-emulation-on
2735: @findex edt-emulation-off
2736: Turn on EDT emulation with @kbd{M-x edt-emulation-on}; restore normal
2737: command bindings with @kbd{M-x edt-emulation-off}.
2738: 
2739: Most of the EDT emulation commands are keypad keys, and most standard
2740: Emacs key bindings are still available.  The EDT emulation rebindings
2741: are done in the global keymap, so there is no problem switching
2742: buffers or major modes while in EDT emulation.
2743: 
2744: @item TPU (DEC VMS editor)
2745: @findex tpu-edt-on
2746: @cindex TPU
2747: @kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT.
2748: 
2749: @item vi (Berkeley editor)
2750: @findex viper-mode
2751: Viper is an emulator for vi.  It implements several levels of
2752: emulation; level 1 is closest to vi itself, while level 5 departs
2753: somewhat from strict emulation to take advantage of the capabilities of
2754: Emacs.  To invoke Viper, type @kbd{M-x viper-mode}; it will guide you
2755: the rest of the way and ask for the emulation level.  @inforef{Top,
2756: Viper, viper}.
2757: 
2758: @item vi (another emulator)
2759: @findex vi-mode
2760: @kbd{M-x vi-mode} enters a major mode that replaces the previously
2761: established major mode.  All of the vi commands that, in real vi, enter
2762: input mode are programmed instead to return to the previous major
2763: mode.  Thus, ordinary Emacs serves as vi's input mode.
2764: 
2765: Because vi emulation works through major modes, it does not work
2766: to switch buffers during emulation.  Return to normal Emacs first.
2767: 
2768: If you plan to use vi emulation much, you probably want to bind a key
2769: to the @code{vi-mode} command.
2770: 
2771: @item vi (alternate emulator)
2772: @findex vip-mode
2773: @kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi
2774: more thoroughly than @kbd{M-x vi-mode}.  Input mode in this emulator
2775: is changed from ordinary Emacs so you can use @key{ESC} to go back to
2776: emulated vi command mode.  To get from emulated vi command mode back to
2777: ordinary Emacs, type @kbd{C-z}.
2778: 
2779: This emulation does not work through major modes, and it is possible
2780: to switch buffers in various ways within the emulator.  It is not
2781: so necessary to assign a key to the command @code{vip-mode} as
2782: it is with @code{vi-mode} because terminating insert mode does
2783: not use it.
2784: 
2785: @inforef{Top, VIP, vip}, for full information.
2786: 
2787: @item WordStar (old wordprocessor)
2788: @findex wordstar-mode
2789: @kbd{M-x wordstar-mode} provides a major mode with WordStar-like
2790: key bindings.
2791: @end table
2792: @end ignore
2793: 
2794: 
2795: @node Hyperlinking
2796: @section Hyperlinking and Web Navigation Features
2797: 
2798:   The following subsections describe convenience features for handling
2799: URLs and other types of links occurring in Emacs buffer text.
2800: 
2801: @menu
2802: * EWW::                         A web browser in Emacs.
2803: * Embedded WebKit Widgets::     Embedding browser widgets in Emacs buffers.
2804: * Browse-URL::                  Following URLs.
2805: * Goto Address mode::           Activating URLs.
2806: * FFAP::                        Finding files etc. at point.
2807: @end menu
2808: 
2809: @node EWW
2810: @subsection Web Browsing with EWW
2811: 
2812: @findex eww
2813: @findex eww-open-file
2814:   @dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs.
2815: It allows browsing URLs within an Emacs buffer.  The command @kbd{M-x
2816: eww} will open a URL or search the web.  You can open a file
2817: using the command @kbd{M-x eww-open-file}.  You can use EWW as the
2818: web browser for @code{browse-url}, @pxref{Browse-URL}.  For full
2819: details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
2820: 
2821: @node Embedded WebKit Widgets
2822: @subsection Embedded WebKit Widgets
2823: @cindex xwidget
2824: @cindex webkit widgets
2825: @cindex embedded widgets
2826: 
2827: @findex xwidget-webkit-browse-url
2828: @findex xwidget-webkit-mode
2829: @cindex Xwidget-WebKit mode
2830:   If Emacs was compiled with the appropriate support packages, it is
2831: able to show browser widgets in its buffers.  The command @kbd{M-x
2832: xwidget-webkit-browse-url} asks for a URL to display in the browser
2833: widget.  The URL normally defaults to the URL at or before point, but
2834: if there is an active region (@pxref{Mark}), the default URL comes
2835: from the region instead, after removing any whitespace from it.  The
2836: command then creates a new buffer with the embedded browser showing
2837: the specified URL.  The buffer is put in the Xwidget-WebKit mode
2838: (similar to Image mode, @pxref{File Conveniences}), which provides
2839: one-key commands for scrolling the widget, changing its size, and
2840: reloading it.  Type @w{@kbd{C-h b}} in that buffer to see the key
2841: bindings.
2842: 
2843: @node Browse-URL
2844: @subsection  Following URLs
2845: @cindex World Wide Web
2846: @cindex Web
2847: @findex browse-url
2848: @findex browse-url-at-point
2849: @findex browse-url-at-mouse
2850: @cindex Browse-URL
2851: @cindex URLs
2852: 
2853: @table @kbd
2854: @item M-x browse-url @key{RET} @var{url} @key{RET}
2855: Load a URL into a Web browser.
2856: @end table
2857: 
2858:   The Browse-URL package allows you to easily follow URLs from within
2859: Emacs.  Most URLs are followed by invoking a web browser;
2860: @samp{mailto:} URLs are followed by invoking the @code{compose-mail}
2861: Emacs command to send mail to the specified address (@pxref{Sending
2862: Mail}).
2863: 
2864:   The command @kbd{M-x browse-url} prompts for a URL, and follows it.
2865: If point is located near a plausible URL, that URL is offered as the
2866: default.  The Browse-URL package also provides other commands which
2867: you might like to bind to keys, such as @code{browse-url-at-point} and
2868: @code{browse-url-at-mouse}.
2869: 
2870: @vindex browse-url-mailto-function
2871: @vindex browse-url-browser-function
2872:   You can customize Browse-URL's behavior via various options in the
2873: @code{browse-url} Customize group.  In particular, the option
2874: @code{browse-url-mailto-function} lets you define how to follow
2875: @samp{mailto:} URLs, while @code{browse-url-browser-function} lets you
2876: define how to follow other types of URLs.  For more information, view
2877: the package commentary by typing @kbd{C-h P browse-url @key{RET}}.
2878: 
2879: @node Goto Address mode
2880: @subsection Activating URLs
2881: @findex goto-address-mode
2882: @cindex mode, Goto Address
2883: @cindex Goto Address mode
2884: @cindex URLs, activating
2885: 
2886: @table @kbd
2887: @item M-x goto-address-mode
2888: Activate URLs and e-mail addresses in the current buffer.
2889: @end table
2890: 
2891: @kindex C-c RET @r{(Goto Address mode)}
2892: @findex goto-address-at-point
2893:   You can make Emacs mark out URLs specially in the current buffer, by
2894: typing @kbd{M-x goto-address-mode}.  When this buffer-local minor mode
2895: is enabled, it finds all the URLs in the buffer, highlights them, and
2896: turns them into clickable buttons.  You can follow the URL by typing
2897: @kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on
2898: its text; or by clicking with @kbd{mouse-2}, or by clicking
2899: @kbd{mouse-1} quickly (@pxref{Mouse References}).  Following a URL is
2900: done by calling @code{browse-url} as a subroutine
2901: (@pxref{Browse-URL}).
2902: 
2903:   It can be useful to add @code{goto-address-mode} to mode hooks and
2904: hooks for displaying an incoming message
2905: (e.g., @code{rmail-show-message-hook} for Rmail, and
2906: @code{mh-show-mode-hook} for MH-E).  This is not needed for Gnus,
2907: which has a similar feature of its own.
2908: 
2909: @node FFAP
2910: @subsection Finding Files and URLs at Point
2911: @findex find-file-at-point
2912: @findex ffap
2913: @findex dired-at-point
2914: @findex ffap-next
2915: @findex ffap-menu
2916: @cindex finding file at point
2917: 
2918:   The FFAP package replaces certain key bindings for finding files,
2919: such as @kbd{C-x C-f}, with commands that provide more sensible
2920: defaults.  These commands behave like the ordinary ones when given a
2921: prefix argument.  Otherwise, they get the default file name or URL
2922: from the text around point.  If what is found in the buffer has the
2923: form of a URL rather than a file name, the commands use
2924: @code{browse-url} to view it (@pxref{Browse-URL}).
2925: 
2926:   This feature is useful for following references in mail or news
2927: buffers, @file{README} files, @file{MANIFEST} files, and so on.  For
2928: more information, view the package commentary by typing @kbd{C-h P
2929: ffap @key{RET}}.
2930: 
2931: @cindex FFAP minor mode
2932: @findex ffap-mode
2933:   To enable FFAP, type @kbd{M-x ffap-bindings}.  This makes the
2934: following key bindings, and also installs hooks for additional FFAP
2935: functionality in Rmail, Gnus and VM article buffers.
2936: 
2937: @table @kbd
2938: @item C-x C-f @var{filename} @key{RET}
2939: @kindex C-x C-f @r{(FFAP)}
2940: Find @var{filename}, guessing a default from text around point
2941: (@code{find-file-at-point}).
2942: @item C-x C-r @var{filename} @key{RET}
2943: @kindex C-x C-r @r{(FFAP)}
2944: @code{ffap-read-only}, analogous to @code{find-file-read-only}.
2945: @item C-x C-v @var{filename} @key{RET}
2946: @kindex C-x C-v @r{(FFAP)}
2947: @code{ffap-alternate-file}, analogous to @code{find-alternate-file}.
2948: @item C-x d @var{directory} @key{RET}
2949: @kindex C-x d @r{(FFAP)}
2950: Start Dired on @var{directory}, defaulting to the directory at
2951: point (@code{dired-at-point}).
2952: @item C-x C-d @var{directory} @key{RET}
2953: @code{ffap-list-directory}, analogous to @code{list-directory}.
2954: @item C-x 4 f @var{filename} @key{RET}
2955: @kindex C-x 4 f @r{(FFAP)}
2956: @code{ffap-other-window}, analogous to @code{find-file-other-window}.
2957: @item C-x 4 r @var{filename} @key{RET}
2958: @code{ffap-read-only-other-window}, analogous to
2959: @code{find-file-read-only-other-window}.
2960: @item C-x 4 d @var{directory} @key{RET}
2961: @code{ffap-dired-other-window}, like @code{dired-other-window}.
2962: @item C-x 5 f @var{filename} @key{RET}
2963: @kindex C-x 5 f @r{(FFAP)}
2964: @code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
2965: @item C-x 5 r @var{filename} @key{RET}
2966: @code{ffap-read-only-other-frame}, analogous to
2967: @code{find-file-read-only-other-frame}.
2968: @item C-x 5 d @var{directory} @key{RET}
2969: @code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}.
2970: @item M-x ffap-next
2971: Search buffer for next file name or URL, then find that file or URL.
2972: @item S-mouse-3
2973: @kindex S-mouse-3 @r{(FFAP)}
2974: @code{ffap-at-mouse} finds the file guessed from text around the position
2975: of a mouse click.
2976: @item C-S-mouse-3
2977: @kindex C-S-mouse-3 @r{(FFAP)}
2978: Display a menu of files and URLs mentioned in current buffer, then
2979: find the one you select (@code{ffap-menu}).
2980: @end table
2981: 
2982: @node Amusements
2983: @section Games and Other Amusements
2984: @cindex boredom
2985: @cindex games
2986: 
2987: @findex animate-birthday-present
2988: @cindex animate
2989:   The @code{animate} package makes text dance (e.g., @kbd{M-x
2990: animate-birthday-present}).
2991: 
2992: @findex blackbox
2993: @findex mpuz
2994: @findex 5x5
2995: @cindex puzzles
2996:   @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles.
2997: @code{blackbox} challenges you to determine the location of objects
2998: inside a box by tomography.  @code{mpuz} displays a multiplication
2999: puzzle with letters standing for digits in a code that you must
3000: guess---to guess a value, type a letter and then the digit you think it
3001: stands for.  The aim of @code{5x5} is to fill in all the squares.
3002: 
3003: @findex bubbles
3004: @cindex bubbles
3005:   @kbd{M-x bubbles} is a game in which the object is to remove as many
3006: bubbles as you can in the smallest number of moves.
3007: 
3008: @findex decipher
3009: @cindex ciphers
3010: @cindex cryptanalysis
3011:   @kbd{M-x decipher} helps you to cryptanalyze a buffer which is
3012: encrypted in a simple monoalphabetic substitution cipher.
3013: 
3014: @findex dissociated-press
3015:   @kbd{M-x dissociated-press} scrambles the text in the current Emacs
3016: buffer, word by word or character by character, writing its output to
3017: a buffer named @file{*Dissociation*}.  A positive argument tells it to
3018: operate character by character, and specifies the number of overlap
3019: characters.  A negative argument tells it to operate word by word, and
3020: specifies the number of overlap words.  Dissociated Press produces
3021: results fairly like those of a Markov chain, but is however, an
3022: independent, ignoriginal invention; it techniquitously copies several
3023: consecutive characters from the sample text between random jumps,
3024: unlike a Markov chain which would jump randomly after each word or
3025: character.  Keep dissociwords out of your documentation, if you want
3026: it to be well userenced and properbose.
3027: 
3028: @findex dunnet
3029: @cindex dunnet
3030:   @kbd{M-x dunnet} runs a text-based adventure game.
3031: 
3032: @findex gomoku
3033: @cindex Go Moku
3034:   If you want a little more personal involvement, try @kbd{M-x gomoku},
3035: which plays the game Go Moku with you.
3036: 
3037: @cindex tower of Hanoi
3038: @findex hanoi
3039:   If you are a little bit bored, you can try @kbd{M-x hanoi}.  If you are
3040: considerably bored, give it a numeric argument.  If you are very, very
3041: bored, try an argument of 9.  Sit back and watch.
3042: 
3043: @findex life
3044: @cindex Life
3045:   @kbd{M-x life} runs Conway's Game of Life cellular automaton.
3046: 
3047: @findex morse-region
3048: @findex unmorse-region
3049: @findex nato-region
3050: @cindex Morse code
3051: @cindex --/---/.-./.../.
3052:   @kbd{M-x morse-region} converts the text in the region to Morse
3053: code; @kbd{M-x unmorse-region} converts it back.  @kbd{M-x
3054: nato-region} converts the text in the region to NATO phonetic
3055: alphabet; @kbd{M-x denato-region} converts it back.
3056: 
3057: @findex pong
3058: @cindex Pong game
3059: @findex tetris
3060: @cindex Tetris
3061: @findex snake
3062: @cindex Snake
3063:   @kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are
3064: implementations of the well-known Pong, Snake and Tetris games.
3065: 
3066: @findex solitaire
3067: @cindex solitaire
3068:   @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
3069: across other pegs.
3070: 
3071: @findex zone
3072: @cindex zone
3073:   The command @kbd{M-x zone} plays games with the display when Emacs
3074: is idle.
3075: 
3076: @findex butterfly
3077: @cindex butterfly
3078:   ``Real Programmers'' deploy @kbd{M-x butterfly}, which uses butterflies
3079: to flip a bit on the drive platter, see @uref{https://xkcd.com/378}.
3080: 
3081: @findex doctor
3082: @cindex Eliza
3083:   Finally, if you find yourself frustrated, try describing your
3084: problems to the famous psychotherapist Eliza.  Just do @kbd{M-x
3085: doctor}.  End each input by typing @key{RET} twice.
3086: 
3087: @ifnottex
3088: @lowersections
3089: @end ifnottex
3090: