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