~ubuntu-branches/ubuntu/karmic/emacs-snapshot/karmic

« back to all changes in this revision

Viewing changes to doc/emacs/misc.texi

  • Committer: Bazaar Package Importer
  • Author(s): Reinhard Tartler
  • Date: 2009-04-05 09:14:30 UTC
  • mto: This revision was merged to the branch mainline in revision 34.
  • Revision ID: james.westby@ubuntu.com-20090405091430-nw07lynn2arotjbe
Tags: upstream-20090320
ImportĀ upstreamĀ versionĀ 20090320

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
@c This is part of the Emacs manual.
2
2
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3
 
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
 
3
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
4
4
@c See file emacs.texi for copying conditions.
5
5
@iftex
6
6
@chapter Miscellaneous Commands
7
7
 
8
8
  This chapter contains several brief topics that do not fit anywhere
9
 
else: reading netnews, running shell commands and shell subprocesses,
10
 
using a single shared Emacs for utilities that expect to run an editor
11
 
as a subprocess, printing hardcopy, sorting text, narrowing display to
12
 
part of the buffer, editing double-column files and binary files,
13
 
saving an Emacs session for later resumption, following hyperlinks,
14
 
browsing images, emulating other editors, and various diversions and
15
 
amusements.
 
9
else: viewing ``document files'', reading netnews, running shell
 
10
commands and shell subprocesses, using a single shared Emacs for
 
11
utilities that expect to run an editor as a subprocess, printing
 
12
hardcopy, sorting text, narrowing display to part of the buffer,
 
13
editing double-column files and binary files, saving an Emacs session
 
14
for later resumption, following hyperlinks, browsing images, emulating
 
15
other editors, and various diversions and amusements.
16
16
 
17
17
@end iftex
18
18
 
20
20
@raisesections
21
21
@end ifnottex
22
22
 
23
 
@node Gnus, Shell, Calendar/Diary, Top
 
23
@node Document View, Gnus, Calendar/Diary, Top
 
24
@section Document Viewing
 
25
@cindex DVI file
 
26
@cindex PDF file
 
27
@cindex PS file
 
28
@cindex Postscript file
 
29
@cindex DocView mode
 
30
@cindex mode, DocView
 
31
@cindex document viewer (DocView)
 
32
@findex doc-view-mode
 
33
 
 
34
DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript
 
35
(PS), and PDF documents.  It provides features such as slicing,
 
36
zooming, and searching inside documents.  It works by converting the
 
37
document to a set of images using the @command{gs} (GhostScript)
 
38
command, and displaying those images.
 
39
 
 
40
@findex doc-view-toggle-display
 
41
@findex doc-view-toggle-display
 
42
@cindex doc-view-minor-mode
 
43
  When you visit a PDF or DVI file, Emacs automatically switches to
 
44
DocView mode.  When you visit a Postscript file, Emacs switches to PS
 
45
mode, a major mode for editing Postscript files as text; however, it
 
46
also enables DocView minor mode, so you can type @kbd{C-c C-c} to view
 
47
the document with DocView.  (PDF and DVI files, unlike Postscript
 
48
files, are not usually human-editable.)  In either case, repeating
 
49
@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView
 
50
and the file text.
 
51
 
 
52
  You can explicitly toggle DocView mode with the command @code{M-x
 
53
doc-view-mode}, and DocView minor mode with the command @code{M-x
 
54
doc-view-minor-mode}.
 
55
 
 
56
  When DocView mode starts, it displays a welcome screen and begins
 
57
formatting the file, page by page.  It displays the first page once
 
58
that has been formatted.
 
59
 
 
60
@findex doc-view-enlarge
 
61
@findex doc-view-shrink
 
62
@vindex doc-view-resolution
 
63
  When in DocView mode, you can enlarge or shrink the document with
 
64
@kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
 
65
(@code{doc-view-shrink}).  To specify the default size for DocView,
 
66
set or customize the variable @code{doc-view-resolution}.
 
67
 
 
68
  To kill the DocView buffer, type @kbd{k}
 
69
(@code{doc-view-kill-proc-and-buffer}).  To bury it, type @kbd{q}
 
70
(@code{quit-window}).
 
71
 
 
72
@menu
 
73
* Navigation::  Navigation inside DocView buffers.
 
74
* Searching::   Searching inside documents.
 
75
* Slicing::     Specifing which part of pages should be displayed.
 
76
* Conversion::  Influencing and triggering converison.
 
77
@end menu
 
78
 
 
79
@node Navigation
 
80
@subsection Navigation
 
81
 
 
82
When in DocView mode, you can scroll the current page using the usual
 
83
Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
 
84
the arrow keys.
 
85
 
 
86
@findex doc-view-next-page
 
87
@findex doc-view-previous-page
 
88
  To display the next page, type @kbd{n}, @key{next} or @kbd{C-x ]}
 
89
(@code{doc-view-next-page}).  To display the previous page, type
 
90
@kbd{p}, @key{prior} or @kbd{C-x [} (@code{doc-view-previous-page}).
 
91
 
 
92
@findex doc-view-scroll-up-or-next-page
 
93
@findex doc-view-scroll-down-or-previous-page
 
94
  The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a
 
95
convenient way to advance through the document.  It scrolls within the
 
96
current page or advances to the next.  @key{DEL} moves backwards in a
 
97
similar way (@code{doc-view-scroll-down-or-previous-page}).
 
98
 
 
99
@findex doc-view-first-page
 
100
@findex doc-view-last-page
 
101
@findex doc-view-goto-page
 
102
  To go to the first page, type @kbd{M-<}
 
103
(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
 
104
(@code{doc-view-last-page}).  To jump to a page by its number, type
 
105
@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
 
106
 
 
107
@node Searching
 
108
@subsection Searching
 
109
 
 
110
While in DocView mode, you can search the file's text for a regular
 
111
expression (@pxref{Regexps}).  The interface for searching is inspired
 
112
by @code{isearch} (@pxref{Incremental Search}).
 
113
 
 
114
@findex doc-view-search
 
115
@findex doc-view-search-backward
 
116
@findex doc-view-show-tooltip
 
117
  To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
 
118
@kbd{C-r} (@code{doc-view-search-backward}).  This reads a regular
 
119
expression using a minibuffer, then echoes the number of matches found
 
120
within the document.  You can move forward and back among the matches
 
121
by typing @kbd{C-s} and @kbd{C-r}.  DocView mode has no way to show
 
122
the match inside the page image; instead, it displays a tooltip (at
 
123
the mouse position) listing all matching lines in the current page.
 
124
To force display of this tooltip, type @kbd{C-t}
 
125
(@code{doc-view-show-tooltip}).
 
126
 
 
127
  To start a new search, use the search command with a prefix
 
128
argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
 
129
for a backward search.
 
130
 
 
131
@node Slicing
 
132
@subsection Slicing
 
133
 
 
134
Documents often have wide margins for printing.  They are annoying
 
135
when reading the document on the screen, because they use up screen
 
136
space and can cause inconvenient scrolling.
 
137
 
 
138
@findex doc-view-set-slice
 
139
@findex doc-view-set-slice-using-mouse
 
140
  With DocView you can hide these margins by selecting a @dfn{slice}
 
141
of pages to display.  A slice is a rectangle within the page area;
 
142
once you specify a slice in DocView, it applies to whichever page you
 
143
look at.
 
144
 
 
145
  To specify the slice numerically, type @kbd{s s}
 
146
(@code{doc-view-set-slice}); then enter the top left pixel position
 
147
and the slice's width and height.
 
148
@c ??? how does this work?
 
149
                
 
150
  A more convenient graphical way to specify the slice is with @kbd{s
 
151
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
 
152
select the slice.
 
153
@c ??? How does this work?
 
154
 
 
155
@findex doc-view-reset-slice
 
156
  To cancel the selected slice, type @kbd{s r}
 
157
(@code{doc-view-reset-slice}).  Then DocView shows the entire page
 
158
including its entire margins.
 
159
 
 
160
@node Conversion
 
161
@subsection Conversion
 
162
 
 
163
@vindex doc-view-cache-directory
 
164
@findex doc-view-clear-cache
 
165
For efficiency, DocView caches the images produced by @command{gs}.
 
166
The name of this directory is given by the variable
 
167
@code{doc-view-cache-directory}.  You can clear the cache directory by
 
168
typing @code{M-x doc-view-clear-cache}.
 
169
 
 
170
@findex doc-view-kill-proc
 
171
@findex doc-view-kill-proc-and-buffer
 
172
  To force a reconversion of the currently viewed document, type
 
173
@kbd{r} or @kbd{g} (@code{revert-buffer}).  To kill the converter
 
174
process associated with the current buffer, type @kbd{K}
 
175
(@code{doc-view-kill-proc}).  The command @kbd{k}
 
176
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
 
177
the DocView buffer.
 
178
 
 
179
  The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
 
180
(@code{doc-view-shrink}) need to reconvert the document at the new
 
181
size.  The current page is converted first.
 
182
 
 
183
@node Gnus, Shell, Document View, Top
24
184
@section Gnus
25
185
@cindex Gnus
26
186
@cindex reading netnews
1270
1430
@cindex server, using Emacs as
1271
1431
@cindex @env{EDITOR} environment variable
1272
1432
 
1273
 
  Various programs such as @code{mail} can invoke your choice of editor
1274
 
to edit a particular piece of text, such as a message that you are
1275
 
sending.  By convention, most of these programs use the environment
1276
 
variable @env{EDITOR} to specify which editor to run.  If you set
1277
 
@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
1278
 
inconvenient fashion, by starting a new, separate Emacs process.  This
1279
 
is inconvenient because it takes time and because the new Emacs process
1280
 
doesn't share the buffers with any existing Emacs process.
1281
 
 
1282
 
  You can arrange to use your existing Emacs process as the editor for
1283
 
programs like @code{mail} by using the Emacs client program and the
1284
 
server that is part of Emacs.  Here is how.
 
1433
  Various programs such as @command{mail} can invoke your choice of
 
1434
editor to edit a particular piece of text, such as a message that you
 
1435
are sending.  By convention, most of these programs use the
 
1436
environment variable @env{EDITOR} to specify which editor to run.  If
 
1437
you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
 
1438
inconvenient way, by starting a new Emacs process.  This is
 
1439
inconvenient because the new Emacs process doesn't share buffers, a
 
1440
command history, or other kinds of information with any existing Emacs
 
1441
process.
 
1442
 
 
1443
  You can solve this problem by setting up Emacs as an @dfn{edit
 
1444
server}, so that it ``listens'' for external edit requests and acts
 
1445
accordingly.  There are two ways to start an Emacs server:
 
1446
 
 
1447
@findex server-start
 
1448
  The first is to run the command @code{server-start} in an existing
 
1449
Emacs process: either type @kbd{M-x server-start}, or put the
 
1450
expression @code{(server-start)} in your initialization file
 
1451
(@pxref{Init File}).  The existing Emacs process is the server; when
 
1452
you exit Emacs, the server dies with the Emacs process.
 
1453
 
 
1454
@cindex daemon, Emacs
 
1455
  The second way to start an Emacs server is to run Emacs as a
 
1456
@dfn{daemon}, using the @samp{--daemon} command-line option.
 
1457
@xref{Initial Options}.  When Emacs is started this way, it calls
 
1458
@code{server-start} after initialization, and returns control to the
 
1459
calling terminal instead of opening an initial frame; it then waits in
 
1460
the background, listening for edit requests.
1285
1461
 
1286
1462
@cindex @env{TEXEDIT} environment variable
1287
 
@findex server-start
1288
 
  First, the preparations.  Within Emacs, call the function
1289
 
@code{server-start}.  (Your @file{.emacs} init file can do this
1290
 
automatically if you add the expression @code{(server-start)} to it,
1291
 
see @ref{Init File}.)  Then, outside Emacs, set the @env{EDITOR}
1292
 
environment variable to @samp{emacsclient}.  (Note that some programs
1293
 
use a different environment variable; for example, to make @TeX{} use
1294
 
@samp{emacsclient}, you should set the @env{TEXEDIT} environment
1295
 
variable to @samp{emacsclient +%d %s}.)
1296
 
 
1297
 
@pindex emacs.bash
1298
 
@cindex Bash command to use Emacs server
1299
 
  As an alternative to using @code{emacsclient}, the file
1300
 
@file{etc/emacs.bash} defines a Bash command @code{edit} which will
1301
 
communicate with a running Emacs session, or start one if none exist.
 
1463
  Once an Emacs server is set up, you can use a shell command called
 
1464
@command{emacsclient} to connect to the existing Emacs process and
 
1465
tell it to visit a file.  If you set the @env{EDITOR} environment
 
1466
variable to @samp{emacsclient}, programs such as @command{mail} will
 
1467
use the existing Emacs process for editing.@footnote{Some programs use
 
1468
a different environment variable; for example, to make @TeX{} use
 
1469
@samp{emacsclient}, set the @env{TEXEDIT} environment variable to
 
1470
@samp{emacsclient +%d %s}.}
 
1471
 
 
1472
@vindex server-name
 
1473
  You can run multiple Emacs servers on the same machine by giving
 
1474
each one a unique ``server name'', using the variable
 
1475
@code{server-name}.  For example, @kbd{M-x set-variable @key{RET}
 
1476
server-name @key{RET} foo @key{RET}} sets the server name to
 
1477
@samp{foo}.  The @code{emacsclient} program can specify a server by
 
1478
name, using the @samp{-s} option (@pxref{emacsclient Options}).
 
1479
 
 
1480
@menu
 
1481
* Invoking emacsclient:: Connecting to the Emacs server.
 
1482
* emacsclient Options::  Emacs client startup options.
 
1483
@end menu
 
1484
 
 
1485
@node Invoking emacsclient
 
1486
@subsection Invoking @code{emacsclient}
 
1487
@cindex @code{emacsclient} invocation
 
1488
 
 
1489
  The simplest way to use the @command{emacsclient} program is to run
 
1490
the shell command @samp{emacsclient @var{file}}, where @var{file} is a
 
1491
file name.  This connects to an Emacs server, and tells that Emacs
 
1492
process to visit @var{file} in one of its existing frames---either a
 
1493
graphical frame, or one in a text-only terminal (@pxref{Frames}).  You
 
1494
can then select that frame to begin editing.
 
1495
 
 
1496
  If there is no Emacs server, the @command{emacsclient} program halts
 
1497
with an error message.  If the Emacs process has no existing
 
1498
frame---which can happen if it was started as a daemon (@pxref{Emacs
 
1499
Server})---then Emacs opens a frame on the terminal in which you
 
1500
called @command{emacsclient}, as though you had used the @samp{-t}
 
1501
option (@pxref{emacsclient Options}).
 
1502
 
 
1503
  On a graphical display, switching to the Emacs server is
 
1504
straightforward---just select its (system-level) window.  If you are
 
1505
using a text-only terminal, there are two ways to switch between
 
1506
@command{emacsclient}'s shell and the Emacs server: (i) run the Emacs
 
1507
server and @command{emacsclient} on different virtual terminals, and
 
1508
switch to the Emacs server's virtual terminal after calling
 
1509
@command{emacsclient}; or (ii) call @command{emacsclient} from within
 
1510
the Emacs server itself, using Shell mode (@pxref{Interactive Shell})
 
1511
or Term mode (@pxref{Term Mode}); @code{emacsclient} blocks only the
 
1512
subshell under Emacs, and you can still use Emacs to edit the file.
1302
1513
 
1303
1514
@kindex C-x #
1304
1515
@findex server-edit
1305
 
  Now, whenever any program invokes your specified @env{EDITOR}
1306
 
program, the effect is to send a message to your principal Emacs telling
1307
 
it to visit a file.  (That's what the program @code{emacsclient} does.)
1308
 
Emacs displays the buffer immediately and you can immediately begin
1309
 
editing it in the already running Emacs session.
1310
 
 
1311
 
  When you've finished editing that buffer, type @kbd{C-x #}
1312
 
(@code{server-edit}).  This saves the file and sends a message back to
1313
 
the @code{emacsclient} program telling it to exit.  The programs that
1314
 
use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
1315
 
to exit.  @kbd{C-x #} also checks for other pending external requests
1316
 
to edit various files, and selects the next such file.
1317
 
 
1318
 
  You can switch to a server buffer manually if you wish; you don't
1319
 
have to arrive at it with @kbd{C-x #}.  But @kbd{C-x #} is the way to
1320
 
say that you are finished with one.
 
1516
  When you finish editing @var{file} in the Emacs server, type
 
1517
@kbd{C-x #} (@code{server-edit}) in its buffer.  This saves the file
 
1518
and sends a message back to the @command{emacsclient} program, telling
 
1519
it to exit.  Programs that use @env{EDITOR} usually wait for the
 
1520
``editor''---in the case @command{emacsclient}---to exit before doing
 
1521
something else.
 
1522
 
 
1523
  You can also call @command{emacsclient} with multiple file name
 
1524
arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
 
1525
Emacs server to visit @var{file1}, @var{file2}, and so forth.  Emacs
 
1526
selects the buffer visiting @var{file1}, and buries the other buffers
 
1527
at the bottom of the buffer list (@pxref{Buffers}).  The
 
1528
@command{emacsclient} program exits once all the specified files are
 
1529
finished (i.e., once you have typed @kbd{C-x #} in each server
 
1530
buffer).
1321
1531
 
1322
1532
@vindex server-kill-new-buffers
1323
1533
@vindex server-temp-file-regexp
1324
1534
  Finishing with a server buffer also kills the buffer, unless it
1325
 
already existed in the Emacs session before the server asked to create
1326
 
it.  However, if you set @code{server-kill-new-buffers} to @code{nil},
1327
 
then a different criterion is used: finishing with a server buffer
1328
 
kills it if the file name matches the regular expression
 
1535
already existed in the Emacs session before the server was asked to
 
1536
create it.  However, if you set @code{server-kill-new-buffers} to
 
1537
@code{nil}, then a different criterion is used: finishing with a
 
1538
server buffer kills it if the file name matches the regular expression
1329
1539
@code{server-temp-file-regexp}.  This is set up to distinguish certain
1330
1540
``temporary'' files.
1331
1541
 
 
1542
  Each @kbd{C-x #} checks for other pending external requests to edit
 
1543
various files, and selects the next such file.  You can switch to a
 
1544
server buffer manually if you wish; you don't have to arrive at it
 
1545
with @kbd{C-x #}.  But @kbd{C-x #} is the way to tell
 
1546
@command{emacsclient} that you are finished.
 
1547
 
1332
1548
@vindex server-window
1333
1549
  If you set the variable @code{server-window} to a window or a frame,
1334
 
@kbd{C-x #} displays the server buffer in that window or in that frame.
1335
 
 
1336
 
@vindex server-name
1337
 
  You can run multiple Emacs servers on the same machine by giving
1338
 
each one a unique ``server name'', using the variable
1339
 
@code{server-name}.  For example, @kbd{M-x set-variable @key{RET}
1340
 
server-name @key{RET} foo @key{RET}} sets the server name to
1341
 
@samp{foo}.  The @code{emacsclient} program can specify a server by
1342
 
name using the @samp{-s} option.  @xref{Invoking emacsclient}.
1343
 
 
1344
 
  While @code{mail} or another application is waiting for
1345
 
@code{emacsclient} to finish, @code{emacsclient} does not read terminal
1346
 
input.  So the terminal that @code{mail} was using is effectively
1347
 
blocked for the duration.  In order to edit with your principal Emacs,
1348
 
you need to be able to use it without using that terminal.  There are
1349
 
three ways to do this:
1350
 
 
1351
 
@itemize @bullet
1352
 
@item
1353
 
Using a window system, run @code{mail} and the principal Emacs in two
1354
 
separate windows.  While @code{mail} is waiting for @code{emacsclient},
1355
 
the window where it was running is blocked, but you can use Emacs by
1356
 
switching windows.
1357
 
 
1358
 
@item
1359
 
Using virtual terminals, run @code{mail} in one virtual terminal
1360
 
and run Emacs in another.
1361
 
 
1362
 
@item
1363
 
Use Shell mode or Term mode in Emacs to run the other program such as
1364
 
@code{mail}; then, @code{emacsclient} blocks only the subshell under
1365
 
Emacs, and you can still use Emacs to edit the file.
1366
 
@end itemize
1367
 
 
1368
 
  If you run @code{emacsclient} with the option @samp{--no-wait}, it
1369
 
returns immediately without waiting for you to ``finish'' the buffer
1370
 
in Emacs.  Note that server buffers created in this way are not killed
1371
 
automatically when you finish with them.
1372
 
 
1373
 
@menu
1374
 
* Invoking emacsclient:: Emacs client startup options.
1375
 
@end menu
1376
 
 
1377
 
@node Invoking emacsclient,, Emacs Server, Emacs Server
1378
 
@subsection Invoking @code{emacsclient}
1379
 
@cindex @code{emacsclient} invocation and options
1380
 
 
1381
 
  To run the @code{emacsclient} program, specify file names as arguments,
1382
 
and optionally line numbers as well, like this:
 
1550
@kbd{C-x #} always displays the next server buffer in that window or
 
1551
in that frame.
 
1552
 
 
1553
@node emacsclient Options
 
1554
@subsection @code{emacsclient} Options
 
1555
@cindex @code{emacsclient} options
 
1556
 
 
1557
  You can pass some optional arguments to the @command{emacsclient}
 
1558
program, such as:
1383
1559
 
1384
1560
@example
1385
 
emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
 
1561
emacsclient -c +12 @var{file1} +4:3 @var{file2}
1386
1562
@end example
1387
1563
 
1388
1564
@noindent
1389
 
This tells Emacs to visit each of the specified files; if you specify a
1390
 
line number for a certain file, Emacs moves to that line in the file.
1391
 
If you specify a column number as well, Emacs puts point on that column
1392
 
in the line.
1393
 
 
1394
 
  Ordinarily, @code{emacsclient} does not return until you use the
1395
 
@kbd{C-x #} command on each of these buffers.  When that happens,
1396
 
Emacs sends a message to the @code{emacsclient} program telling it to
1397
 
return.
1398
 
 
1399
 
  If you invoke @code{emacsclient} for more than one file, the
1400
 
additional client buffers are buried at the bottom of the buffer list
1401
 
(@pxref{Buffers}).  If you call @kbd{C-x #} after you are done editing
1402
 
a client buffer, the next client buffer is automatically selected.
1403
 
 
1404
 
  But if you use the option @samp{-n} or @samp{--no-wait} when running
1405
 
@code{emacsclient}, then it returns immediately.  (You can take as
1406
 
long as you like to edit the files in Emacs.)
1407
 
 
1408
 
  The option @samp{-a @var{command}} or
1409
 
@samp{--alternate-editor=@var{command}} specifies a command to run if
1410
 
@code{emacsclient} fails to contact Emacs.  This is useful when
1411
 
running @code{emacsclient} in a script.  For example, the following
1412
 
setting for the @env{EDITOR} environment variable will always give you
1413
 
an editor, even if no Emacs server is running:
 
1565
The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments
 
1566
specify line numbers, or line and column numbers, for the next file
 
1567
argument.  These behave like the command line arguments for Emacs
 
1568
itself.  @xref{Action Arguments}.
 
1569
 
 
1570
  The other optional arguments recognized by @command{emacsclient} are
 
1571
listed below:
 
1572
 
 
1573
@table @samp
 
1574
@item -a @var{command}
 
1575
@itemx --alternate-editor=@var{command}
 
1576
Specify a command to run if @code{emacsclient} fails to contact Emacs.
 
1577
This is useful when running @code{emacsclient} in a script.  If
 
1578
@var{command} is the empty string, then start Emacs in daemon mode and
 
1579
try connecting again.  For example, the following setting for the
 
1580
@env{EDITOR} environment variable will always give you an editor, even
 
1581
if no Emacs server is running:
1414
1582
 
1415
1583
@example
1416
1584
EDITOR="emacsclient --alternate-editor emacs +%d %s"
1418
1586
 
1419
1587
@noindent
1420
1588
@cindex @env{ALTERNATE_EDITOR} environment variable
1421
 
The environment variable @env{ALTERNATE_EDITOR} has the same effect, with
1422
 
the value of the @samp{--alternate-editor} option taking precedence.
1423
 
 
1424
 
If you use several displays, you can tell Emacs on which display to
1425
 
open the given files with the @samp{-d @var{display}} or
1426
 
@samp{--display=@var{display}} option to @code{emacsclient}.  This is
1427
 
handy when connecting from home to an Emacs session running on your
1428
 
machine at your workplace.
1429
 
 
1430
 
If there is more than one Emacs server running, you can specify a
1431
 
server name with the @samp{-s @var{name}} or
1432
 
@samp{--socket-name=@var{name}} option to @code{emacsclient}.  (This
1433
 
option is not supported on MS-Windows.)
1434
 
 
1435
 
You can also use @code{emacsclient} to execute any piece of Emacs Lisp
1436
 
code, using the @samp{-e} or @samp{--eval} option.  When this option
1437
 
is given, the rest of the arguments is interpreted as a list of
1438
 
expressions to evaluate, not a list of files to visit.
1439
 
 
 
1589
The environment variable @env{ALTERNATE_EDITOR} has the same effect,
 
1590
with the value of the @samp{--alternate-editor} option taking
 
1591
precedence.
 
1592
 
 
1593
@item -c
 
1594
Create a new graphical frame, instead of using an existing Emacs
 
1595
frame.  Emacs 23 can create a graphical frame even if it was started
 
1596
in a text-only terminal, provided it is able to connect to a graphical
 
1597
display.  If no graphical display is available, Emacs creates a new
 
1598
text-only terminal frame (@pxref{Frames}).  If you omit a filename
 
1599
argument while supplying the @samp{-c} option, the new frame displays
 
1600
the @samp{*scratch*} buffer (@pxref{Buffers}).
 
1601
 
 
1602
@item -d @var{display}
 
1603
@itemx --display=@var{display}
 
1604
Tell Emacs to open the given files on the X display @var{display}
 
1605
(assuming there is more than one X display available).
 
1606
 
 
1607
@item -e
 
1608
@itemx --eval
 
1609
Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
 
1610
files.  When this option is given, the arguments to
 
1611
@command{emacsclient} are interpreted as a list of expressions to
 
1612
evaluate, @emph{not} as a list of files to visit.
 
1613
 
 
1614
@item -f @var{server-file}
 
1615
@itemx --server-file=@var{server-file}
1440
1616
@cindex @env{EMACS_SERVER_FILE} environment variable
1441
 
When you start the Emacs server (by calling @code{server-start}),
1442
 
Emacs creates a file with information about TCP connection to the
1443
 
server: the host where Emacs is running, the port where it is
1444
 
listening, and an authentication string.  @code{emacsclient} uses this
1445
 
information if it needs to connect to the server via TCP.  By default,
1446
 
the file goes in the @file{~/.emacs.d/server/} directory@footnote{On
1447
 
MS-Windows, if @env{HOME} is not set or the TCP configuration file
1448
 
cannot be found there, Emacs also looks for the file in the
1449
 
@file{.emacs.d/server/} subdirectory of the directory pointed to by
1450
 
the @env{APPDATA} environment variable.}.  You can specify the file
1451
 
name to use with the @samp{-f @var{file}} or
1452
 
@samp{--server-file=@var{file}} options, or by setting
1453
 
@env{EMACS_SERVER_FILE} environment variable to the file name.
 
1617
@cindex server file
 
1618
@vindex server-use-tcp
 
1619
@vindex server-host
 
1620
Specify a @dfn{server file} for connecting to an Emacs server via TCP.
 
1621
 
 
1622
An Emacs server usually uses an operating system feature called a
 
1623
``local socket'' to listen for connections.  Some operating systems,
 
1624
such as Microsoft Windows, do not support local sockets; in that case,
 
1625
Emacs uses TCP instead.  When you start the Emacs server, Emacs
 
1626
creates a server file containing some TCP information that
 
1627
@command{emacsclient} needs for making the connection.  By default,
 
1628
the server file is in @file{~/.emacs.d/server/}.  On Microsoft
 
1629
Windows, if @command{emacsclient} does not find the server file there,
 
1630
it looks in the @file{.emacs.d/server/} subdirectory of the directory
 
1631
pointed to by the @env{APPDATA} environment variable.  You can tell
 
1632
@command{emacsclient} to use a specific server file with the @samp{-f}
 
1633
or @samp{--server-file} option, or by setting the
 
1634
@env{EMACS_SERVER_FILE} environment variable.
 
1635
 
 
1636
Even if local sockets are available, you can tell Emacs to use TCP by
 
1637
setting the variable @code{server-use-tcp} to @code{t}.  One advantage
 
1638
of TCP is that the server can accept connections from remote machines.
 
1639
For this to work, you must (i) set the variable @code{server-host} to
 
1640
the hostname or IP address of the machine on which the Emacs server
 
1641
runs, and (ii) provide @command{emacsclient} with the server file.
 
1642
(One convenient way to do the latter is to put the server file on a
 
1643
networked file system such as NFS.)
 
1644
 
 
1645
@item -n
 
1646
@itemx --no-wait
 
1647
Let @command{emacsclient} exit immediately, instead of waiting until
 
1648
all server buffers are finished.  You can take as long as you like to
 
1649
edit the server buffers within Emacs, and they are @emph{not} killed
 
1650
when you type @kbd{C-x #} in them.
 
1651
 
 
1652
@item -s @var{server-name}
 
1653
@itemx --socket-name=@var{server-name}
 
1654
Connect to the Emacs server named @var{server-name}.  The server name
 
1655
is given by the variable @code{server-name} on the Emacs server.  If
 
1656
this option is omitted, @command{emacsclient} connects to the first
 
1657
server it finds.  (This option is not supported on MS-Windows.)
 
1658
 
 
1659
@item -t
 
1660
@itemx --tty
 
1661
@itemx -nw
 
1662
Create a new Emacs frame on the current text-only terminal, instead of
 
1663
using an existing Emacs frame.  Emacs 23 can open a text-only terminal
 
1664
even if it was started in another text-only terminal, or on a
 
1665
graphical display.  If you omit a filename argument while supplying
 
1666
this option, the new frame displays the @samp{*scratch*} buffer.
 
1667
@xref{Buffers}.
 
1668
@end table
 
1669
 
 
1670
  If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
 
1671
Emacs frame created with @command{emacsclient}, via the @samp{-c} or
 
1672
@samp{-t} options, Emacs deletes the frame instead of killing the
 
1673
Emacs process itself.  On a text-only terminal frame created with the
 
1674
@samp{-t} option, this returns control to the terminal.  Emacs also
 
1675
marks all the server buffers for the client as finished, as though you
 
1676
had typed @kbd{C-x #} in all of them.
 
1677
 
 
1678
  When Emacs is started as a daemon, all frames are considered client
 
1679
frames, so @kbd{C-x C-c} will never kill Emacs.  To kill the Emacs
 
1680
process, type @kbd{M-x kill-emacs}.
1454
1681
 
1455
1682
@node Printing, Sorting, Emacs Server, Top
1456
1683
@section Printing Hard Copies
1533
1760
Print hardcopy of the current region in PostScript form, showing the
1534
1761
faces used in the text.
1535
1762
@item M-x ps-spool-buffer
1536
 
Generate PostScript for the current buffer text.
 
1763
Generate and spool a PostScript image for the current buffer text.
1537
1764
@item M-x ps-spool-region
1538
 
Generate PostScript for the current region.
 
1765
Generate and spool a PostScript image for the current region.
1539
1766
@item M-x ps-spool-buffer-with-faces
1540
 
Generate PostScript for the current buffer, showing the faces used.
 
1767
Generate and spool a PostScript image for the current buffer, showing the faces used.
1541
1768
@item M-x ps-spool-region-with-faces
1542
 
Generate PostScript for the current region, showing the faces used.
 
1769
Generate and spool a PostScript image for the current region, showing the faces used.
 
1770
@item M-x ps-despool
 
1771
Send the spooled PostScript to the printer.
1543
1772
@item M-x handwrite
1544
 
Generates/prints PostScript for the current buffer as if handwritten.
 
1773
Generate/print PostScript for the current buffer as if handwritten.
1545
1774
@end table
1546
1775
 
1547
1776
@findex ps-print-region
1554
1783
corresponding @samp{-with-faces} commands,
1555
1784
@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
1556
1785
use PostScript features to show the faces (fonts and colors) in the text
1557
 
properties of the text being printed.
 
1786
properties of the text being printed.  The @samp{-with-faces} commands only
 
1787
work if they are used in a window system, so it has a way to determine color
 
1788
values.
 
1789
 
 
1790
  Interactively, when you use a prefix argument (@kbd{C-u}), the command
 
1791
prompts the user for a file name, and saves the PostScript image in that file
 
1792
instead of sending it to the printer.
 
1793
 
 
1794
  Noninteractively, the argument @var{filename} is treated as follows: if it is
 
1795
@code{nil}, send the image to the printer.  If @var{filename} is a string, save
 
1796
the PostScript image in a file with that name.
1558
1797
 
1559
1798
  If you are using a color display, you can print a buffer of program
1560
1799
code with color highlighting by turning on Font-Lock mode in that
1564
1803
@findex ps-spool-buffer
1565
1804
@findex ps-spool-region-with-faces
1566
1805
@findex ps-spool-buffer-with-faces
1567
 
  The commands whose names have @samp{spool} instead of @samp{print}
 
1806
  The commands whose names have @samp{spool} instead of @samp{print},
1568
1807
generate the PostScript output in an Emacs buffer instead of sending
1569
1808
it to the printer.
1570
1809
 
 
1810
  Use the command @code{ps-despool} to send the spooled images to the printer.
 
1811
 
 
1812
@findex ps-despool
 
1813
  This command sends the PostScript generated by  @samp{-spool-} commands (see
 
1814
commands above) to the printer.
 
1815
 
 
1816
  Interactively, when you use a prefix argument (@kbd{C-u}), the command
 
1817
prompts the user for a file name, and saves the spooled PostScript image in
 
1818
that file instead of sending it to the printer.
 
1819
 
 
1820
  Noninteractively, the argument @var{filename} is treated as follows: if it is
 
1821
@code{nil}, send the image to the printer.  If @var{filename} is a string, save
 
1822
the PostScript image in a file with that name.
 
1823
 
1571
1824
@findex handwrite
1572
1825
@cindex handwriting
1573
1826
@kbd{M-x handwrite} is more frivolous.  It generates a PostScript
1608
1861
with shades of gray.  This might produce illegible output, even if your
1609
1862
screen colors only use shades of gray.
1610
1863
 
 
1864
  Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to
 
1865
print colors on black/white printers.
 
1866
 
1611
1867
@vindex ps-use-face-background
1612
1868
  By default, PostScript printing ignores the background colors of the
1613
1869
faces, unless the variable @code{ps-use-face-background} is
2295
2551
 
2296
2552
@menu
2297
2553
* Browse-URL::                  Following URLs.
2298
 
* Goto-address::                Activating URLs.
 
2554
* Goto Address mode::           Activating URLs.
2299
2555
* FFAP::                        Finding files etc. at point.
2300
2556
@end menu
2301
2557
 
2336
2592
Browse-URL, so that the customization options for Browse-URL will
2337
2593
affect all browsing in Emacs.
2338
2594
 
2339
 
@node Goto-address
 
2595
@node Goto Address mode
2340
2596
@subsection Activating URLs
2341
 
@findex goto-address
2342
 
@cindex Goto-address
 
2597
@findex goto-address-mode
 
2598
@cindex Goto Address mode
2343
2599
@cindex URLs, activating
2344
2600
 
2345
2601
@table @kbd
2346
 
@item M-x goto-address
 
2602
@item M-x goto-address-mode
2347
2603
Activate URLs and e-mail addresses in the current buffer.
2348
2604
@end table
2349
2605
 
2350
2606
  You can make URLs in the current buffer active with @kbd{M-x
2351
 
goto-address}.  This finds all the URLs in the buffer, and establishes
2352
 
bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them.  After
2353
 
activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL
2354
 
and type @kbd{C-c @key{RET}}, that will display the web page that the URL
2355
 
specifies.  For a @samp{mailto} URL, it sends mail instead, using your
2356
 
selected mail-composition method (@pxref{Mail Methods}).
2357
 
 
2358
 
  It can be useful to add @code{goto-address} to mode hooks and the
2359
 
hooks used to display an incoming message.
2360
 
@code{rmail-show-message-hook} is the appropriate hook for Rmail, and
2361
 
@code{mh-show-mode-hook} for MH-E.  This is not needed for Gnus,
2362
 
which has a similar feature of its own.
2363
 
 
 
2607
goto-address-mode}.  This minor mode finds all the URLs in the buffer,
 
2608
highlights them, and turns them into @dfn{buttons}: if you click on a
 
2609
URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or
 
2610
move to the URL and type @kbd{C-c @key{RET}}, that displays the web
 
2611
page that the URL specifies.  For a @samp{mailto} URL, it sends mail
 
2612
instead, using your selected mail-composition method (@pxref{Mail
 
2613
Methods}).
 
2614
 
 
2615
  It can be useful to add @code{goto-address-mode} to mode hooks and
 
2616
the hooks used to display an incoming message (e.g.,
 
2617
@code{rmail-show-message-hook} for Rmail, and @code{mh-show-mode-hook}
 
2618
for MH-E).  This is not needed for Gnus, which has a similar feature
 
2619
of its own.
2364
2620
 
2365
2621
@node FFAP
2366
2622
@subsection Finding Files and URLs at Point
2457
2713
gibberish, it insists on a certain amount of overlap between the end of
2458
2714
one run of consecutive words or characters and the start of the next.
2459
2715
That is, if it has just output `president' and then decides to jump
2460
 
to a different point in the file, it might spot the `ent' in `pentagon'
 
2716
to a different point in the buffer, it might spot the `ent' in `pentagon'
2461
2717
and continue from there, producing `presidentagon'.@footnote{This
2462
2718
dissociword actually appeared during the Vietnam War, when it was very
2463
2719
appropriate.  Bush has made it appropriate again.}  Long sample texts
2479
2735
chain based on a frequency table constructed from the sample text.  It
2480
2736
is, however, an independent, ignoriginal invention.  Dissociated Press
2481
2737
techniquitously copies several consecutive characters from the sample
2482
 
between random choices, whereas a Markov chain would choose randomly
2483
 
for each word or character.  This makes for more plausible sounding
2484
 
results, and runs faster.
 
2738
text between random jumps, unlike a Markov chain which would jump
 
2739
randomly after each word or character.  This makes for more plausible
 
2740
sounding results, and runs faster.
2485
2741
 
2486
2742
@cindex outragedy
2487
2743
@cindex buggestion