mirrored from git://git.sv.gnu.org/emacs.git
/
misc.texi
2751 lines (2335 loc) · 110 KB
/
misc.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c This is part of the Emacs manual.
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands
This chapter contains several brief topics that do not fit anywhere
else: reading Usenet news, viewing PDFs and other such documents, web
browsing, running shell commands and shell subprocesses, using a
single shared Emacs for utilities that expect to run an editor as a
subprocess, printing, sorting text, editing binary files, saving an
Emacs session for later resumption, recursive editing level, following
hyperlinks, and various diversions and amusements.
@end iftex
@ifnottex
@raisesections
@end ifnottex
@node Gnus
@section Gnus
@cindex Gnus
@cindex Usenet news
@cindex newsreader
Gnus is an Emacs package primarily designed for reading and posting
Usenet news. It can also be used to read and respond to messages from
a number of other sources---email, remote directories, digests, and so
on. Here we introduce Gnus and describe several basic features.
@ifnottex
For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
@end ifnottex
@iftex
For full details on Gnus, type @kbd{C-h i} and then select the Gnus
manual.
@end iftex
@menu
* Buffers of Gnus:: The group, summary, and article buffers.
* Gnus Startup:: What you should know about starting Gnus.
* Gnus Group Buffer:: A short description of Gnus group commands.
* Gnus Summary Buffer:: A short description of Gnus summary commands.
@end menu
@node Buffers of Gnus
@subsection Gnus Buffers
Gnus uses several buffers to display information and to receive
commands. The three most commonly-used Gnus buffers are the
@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article
buffer}.
The @dfn{group buffer} contains a list of article sources (e.g.,
newsgroups and email inboxes), which are collectively referred to as
@dfn{groups}. This is the first buffer Gnus displays when it starts
up. It normally displays only the groups to which you subscribe and
that contain unread articles. From this buffer, you can select a
group to read.
The @dfn{summary buffer} lists the articles in a single group,
showing one article per line. By default, it displays each article's
author, subject, and line
@iftex
number.
@end iftex
@ifnottex
number, but this is customizable; @xref{Summary Buffer Format,,, gnus,
The Gnus Manual}.
@end ifnottex
The summary buffer is created when you select a group in the group
buffer, and is killed when you exit the group.
From the summary buffer, you can choose an article to view. The
article is displayed in the @dfn{article buffer}. In normal Gnus
usage, you view this buffer but do not select it---all useful Gnus
commands can be invoked from the summary buffer. But you can select
the article buffer, and execute Gnus commands from it, if you wish.
@node Gnus Startup
@subsection When Gnus Starts Up
@findex gnus
@cindex @file{.newsrc} file
If your system has been set up for reading Usenet news, getting
started with Gnus is easy---just type @kbd{M-x gnus}.
On starting up, Gnus reads your @dfn{news initialization file}: a
file named @file{.newsrc} in your home directory which lists your
Usenet newsgroups and subscriptions (this file is not unique to Gnus;
it is used by many other newsreader programs). It then tries to
contact the system's default news server, which is typically specified
by the @env{NNTPSERVER} environment variable.
If your system does not have a default news server, or if you wish
to use Gnus for reading email, then before invoking @kbd{M-x gnus} you
need to tell Gnus where to get news and/or mail. To do this,
customize the variables @code{gnus-select-method} and/or
@code{gnus-secondary-select-methods}.
@iftex
See the Gnus manual for details.
@end iftex
@ifnottex
@xref{Finding the News,,, gnus, The Gnus Manual}.
@end ifnottex
Once Gnus has started up, it displays the group buffer. By default,
the group buffer shows only a small number of @dfn{subscribed groups}.
Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or
@dfn{zombie}---are hidden. The first time you start Gnus, any group
to which you are not subscribed is made into a killed group; any group
that subsequently appears on the news server becomes a zombie group.
To proceed, you must select a group in the group buffer to open the
summary buffer for that group; then, select an article in the summary
buffer to view its article buffer in a separate window. The following
sections explain how to use the group and summary buffers to do this.
To quit Gnus, type @kbd{q} in the group buffer. This automatically
records your group statuses in the files @file{.newsrc} and
@file{.newsrc.eld}, so that they take effect in subsequent Gnus
sessions.
@node Gnus Group Buffer
@subsection Using the Gnus Group Buffer
The following commands are available in the Gnus group buffer:
@table @kbd
@kindex SPC @r{(Gnus Group mode)}
@findex gnus-group-read-group
@item @key{SPC}
Switch to the summary buffer for the group on the current line.
@kindex l @r{(Gnus Group mode)}
@kindex A s @r{(Gnus Group mode)}
@findex gnus-group-list-groups
@item l
@itemx A s
In the group buffer, list only the groups to which you subscribe and
which contain unread articles (this is the default listing).
@kindex L @r{(Gnus Group mode)}
@kindex A u @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item L
@itemx A u
List all subscribed and unsubscribed groups, but not killed or zombie
groups.
@kindex A k @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item A k
List killed groups.
@kindex A z @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item A z
List zombie groups.
@kindex u @r{(Gnus Group mode)}
@findex gnus-group-unsubscribe-current-group
@cindex subscribe groups
@cindex unsubscribe groups
@item u
Toggle the subscription status of the group on the current line
(i.e., turn a subscribed group into an unsubscribed group, or vice
versa). Invoking this on a killed or zombie group turns it into an
unsubscribed group.
@kindex C-k @r{(Gnus Group mode)}
@findex gnus-group-kill-group
@item C-k
Kill the group on the current line. Killed groups are not recorded in
the @file{.newsrc} file, and they are not shown in the @kbd{l} or
@kbd{L} listings.
@kindex DEL @r{(Gnus Group mode)}
@item @key{DEL}
Move point to the previous group containing unread articles.
@kindex n @r{(Gnus Group mode)}
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
Move point to the next unread group.
@kindex p @r{(Gnus Group mode)}
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
Move point to the previous unread group.
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q
Update your Gnus settings, and quit Gnus.
@end table
@node Gnus Summary Buffer
@subsection Using the Gnus Summary Buffer
The following commands are available in the Gnus summary buffer:
@table @kbd
@kindex SPC @r{(Gnus Summary mode)}
@findex gnus-group-read-group
@item @key{SPC}
If there is no article selected, select the article on the current
line and display its article buffer. Otherwise, try scrolling the
selected article buffer in its window; on reaching the end of the
buffer, select the next unread article.
Thus, you can read through all articles by repeatedly typing
@key{SPC}.
@kindex DEL @r{(Gnus Summary mode)}
@findex gnus-summary-prev-page
@item @key{DEL}
Scroll the text of the article backwards.
@kindex n @r{(Gnus Summary mode)}
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
Select the next unread article.
@kindex p @r{(Gnus Summary mode)}
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
Select the previous unread article.
@kindex s @r{(Gnus Summary mode)}
@findex gnus-summary-isearch-article
@item s
Do an incremental search on the selected article buffer, as if you
switched to the buffer and typed @kbd{C-s} (@pxref{Incremental
Search}).
@kindex M-s @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-forward
@item M-s @var{regexp} @key{RET}
Search forward for articles containing a match for @var{regexp}.
@kindex q @r{(Gnus Summary mode)}
@item q
Exit the summary buffer and return to the group buffer.
@end table
@node Network Security
@section Network Security
@cindex network security manager
@cindex NSM
@cindex encryption
@cindex SSL
@cindex TLS
@cindex STARTTLS
Whenever Emacs establishes any network connection, it passes the
established connection to the @dfn{Network Security Manager}
(@acronym{NSM}). @acronym{NSM} is responsible for enforcing the
network security under your control.
@vindex network-security-level
The @code{network-security-level} variable determines the security
level that @acronym{NSM} enforces. If its value is @code{low}, no
security checks are performed.
If this variable is @code{medium} (which is the default), a number of
checks will be performed. If as result @acronym{NSM} determines that
the network connection might not be trustworthy, it will make you
aware of that, and will ask you what to do about the network
connection.
You can decide to register a permanent security exception for an
unverified connection, a temporary exception, or refuse the connection
entirely.
Below is a list of the checks done on the @code{medium} level.
@table @asis
@item unable to verify a @acronym{TLS} certificate
If the connection is a @acronym{TLS}, @acronym{SSL} or
@acronym{STARTTLS} connection, @acronym{NSM} will check whether
the certificate used to establish the identity of the server we're
connecting to can be verified.
While an invalid certificate is often the cause for concern (there
could be a Man-in-the-Middle hijacking your network connection and
stealing your password), there may be valid reasons for going ahead
with the connection anyway. For instance, the server may be using a
self-signed certificate, or the certificate may have expired. It's up
to you to determine whether it's acceptable to continue with the
connection.
@item a self-signed certificate has changed
If you've previously accepted a self-signed certificate, but it has
now changed, that could mean that the server has just changed the
certificate, but it might also mean that the network connection has
been hijacked.
@item previously encrypted connection now unencrypted
If the connection is unencrypted, but it was encrypted in previous
sessions, this might mean that there is a proxy between you and the
server that strips away @acronym{STARTTLS} announcements, leaving the
connection unencrypted. This is usually very suspicious.
@item talking to an unencrypted service when sending a password
When connecting to an @acronym{IMAP} or @acronym{POP3} server, these
should usually be encrypted, because it's common to send passwords
over these connections. Similarly, if you're sending email via
@acronym{SMTP} that requires a password, you usually want that
connection to be encrypted. If the connection isn't encrypted,
@acronym{NSM} will warn you.
@end table
If @code{network-security-level} is @code{high}, the following checks
will be made, in addition to the above:
@table @asis
@item a validated certificate changes the public key
Servers change their keys occasionally, and that is normally nothing
to be concerned about. However, if you are worried that your network
connections are being hijacked by agencies who have access to pliable
Certificate Authorities which issue new certificates for third-party
services, you may want to keep track of these changes.
@item Diffie-Hellman low prime bits
When doing the public key exchange, the number of ``prime bits''
should be high to ensure that the channel can't be eavesdropped on by
third parties. If this number is too low, you will be warned.
@item @acronym{RC4} stream cipher
The @acronym{RC4} stream cipher is believed to be of low quality and
may allow eavesdropping by third parties.
@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3}
The protocols older than @acronym{TLS1.0} are believed to be
vulnerable to a variety of attacks, and you may want to avoid using
these if what you're doing requires higher security.
@end table
Finally, if @code{network-security-level} is @code{paranoid}, you will
also be notified the first time @acronym{NSM} sees any new
certificate. This will allow you to inspect all the certificates from
all the connections that Emacs makes.
The following additional variables can be used to control details of
@acronym{NSM} operation:
@table @code
@item nsm-settings-file
@vindex nsm-settings-file
This is the file where @acronym{NSM} stores details about connections.
It defaults to @file{~/.emacs.d/network-security.data}.
@item nsm-save-host-names
@vindex nsm-save-host-names
By default, host names will not be saved for non-@code{STARTTLS}
connections. Instead a host/port hash is used to identify connections.
This means that one can't casually read the settings file to see what
servers the user has connected to. If this variable is @code{t},
@acronym{NSM} will also save host names in the nsm-settings-file.
@end table
@node Document View
@section Document Viewing
@cindex DVI file
@cindex PDF file
@cindex PS file
@cindex PostScript file
@cindex OpenDocument file
@cindex Microsoft Office file
@cindex DocView mode
@cindex mode, DocView
@cindex document viewer (DocView)
@findex doc-view-mode
DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
OpenDocument, and Microsoft Office documents. It provides features
such as slicing, zooming, and searching inside documents. It works by
converting the document to a set of images using the @command{gs}
(GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands
and other external tools @footnote{For PostScript files, GhostScript
is a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm}
is needed. For OpenDocument and Microsoft Office documents, the
@code{unoconv} tool is needed.}, and displaying those images.
@findex doc-view-toggle-display
@findex doc-view-toggle-display
@cindex doc-view-minor-mode
When you visit a document file that can be displayed with DocView
mode, Emacs automatically uses DocView mode @footnote{The needed
external tools for the document type must be available, and Emacs must
be running in a graphical frame and have PNG image support. If any of
these requirements is not fulfilled, Emacs falls back to another major
mode.}. As an exception, when you visit a PostScript file, Emacs
switches to PS mode, a major mode for editing PostScript files as
text; however, it also enables DocView minor mode, so you can type
@kbd{C-c C-c} to view the document with DocView. In either DocView
mode or DocView minor mode, repeating @kbd{C-c C-c}
(@code{doc-view-toggle-display}) toggles between DocView and the
underlying file contents.
@findex doc-view-open-text
When you visit a file which would normally be handled by DocView
mode but some requirement is not met (e.g., you operate in a terminal
frame or emacs has no PNG support), you are queried if you want to
view the document's contents as plain text. If you confirm, the
buffer is put in text mode and DocView minor mode is activated. Thus,
by typing @kbd{C-c C-c} you switch to the fallback mode. With another
@kbd{C-c C-c} you return to DocView mode. The plain text contents can
also be displayed from within DocView mode by typing @kbd{C-c C-t}
(@code{doc-view-open-text}).
You can explicitly enable DocView mode with the command @code{M-x
doc-view-mode}. You can toggle DocView minor mode with @code{M-x
doc-view-minor-mode}.
When DocView mode starts, it displays a welcome screen and begins
formatting the file, page by page. It displays the first page once
that has been formatted.
To kill the DocView buffer, type @kbd{k}
(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q}
(@code{quit-window}).
@menu
* Navigation: DocView Navigation. Navigating DocView buffers.
* Searching: DocView Searching. Searching inside documents.
* Slicing: DocView Slicing. Specifying which part of a page is displayed.
* Conversion: DocView Conversion. Influencing and triggering conversion.
@end menu
@node DocView Navigation
@subsection DocView Navigation
In DocView mode, you can scroll the current page using the usual
Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
the arrow keys.
@vindex doc-view-continuous
By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
scrolling at the beginning and end of the current page, respectively.
However, if you change the variable @code{doc-view-continuous} to a
non-@code{nil} value, then @kbd{C-p} displays the previous page if you
are already at the beginning of the current page, and @kbd{C-n}
displays the next page if you are at the end of the current page.
@findex doc-view-next-page
@findex doc-view-previous-page
@kindex n @r{(DocView mode)}
@kindex p @r{(DocView mode)}
@kindex C-x ] @r{(DocView mode)}
@kindex C-x [ @r{(DocView mode)}
You can also display the next page by typing @kbd{n}, @key{next} or
@kbd{C-x ]} (@code{doc-view-next-page}). To display the previous
page, type @kbd{p}, @key{prior} or @kbd{C-x [}
(@code{doc-view-previous-page}).
@findex doc-view-scroll-up-or-next-page
@findex doc-view-scroll-down-or-previous-page
@kindex SPC @r{(DocView mode)}
@kindex DEL @r{(DocView mode)}
@key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient
way to advance through the document. It scrolls within the current
page or advances to the next. @key{DEL} moves backwards in a similar
way (@code{doc-view-scroll-down-or-previous-page}).
@findex doc-view-first-page
@findex doc-view-last-page
@findex doc-view-goto-page
@kindex M-< @r{(DocView mode)}
@kindex M-> @r{(DocView mode)}
To go to the first page, type @kbd{M-<}
(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
(@code{doc-view-last-page}). To jump to a page by its number, type
@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
@findex doc-view-enlarge
@findex doc-view-shrink
@vindex doc-view-resolution
@kindex + @r{(DocView mode)}
@kindex - @r{(DocView mode)}
You can enlarge or shrink the document with @kbd{+}
(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). These
commands work by reconverting the document at the new size. To
specify the default size for DocView, customize the variable
@code{doc-view-resolution}.
@node DocView Searching
@subsection DocView Searching
In DocView mode, you can search the file's text for a regular
expression (@pxref{Regexps}). The interface for searching is inspired
by @code{isearch} (@pxref{Incremental Search}).
@findex doc-view-search
@findex doc-view-search-backward
@findex doc-view-show-tooltip
To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular
expression using a minibuffer, then echoes the number of matches found
within the document. You can move forward and back among the matches
by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show
the match inside the page image; instead, it displays a tooltip (at
the mouse position) listing all matching lines in the current page.
To force display of this tooltip, type @kbd{C-t}
(@code{doc-view-show-tooltip}).
To start a new search, use the search command with a prefix
argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
for a backward search.
@node DocView Slicing
@subsection DocView Slicing
Documents often have wide margins for printing. They are annoying
when reading the document on the screen, because they use up screen
space and can cause inconvenient scrolling.
@findex doc-view-set-slice
@findex doc-view-set-slice-using-mouse
With DocView you can hide these margins by selecting a @dfn{slice}
of pages to display. A slice is a rectangle within the page area;
once you specify a slice in DocView, it applies to whichever page you
look at.
To specify the slice numerically, type @kbd{s s}
(@code{doc-view-set-slice}); then enter the top left pixel position
and the slice's width and height.
@c ??? how does this work?
A more convenient graphical way to specify the slice is with @kbd{s
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
select the slice. Simply press and hold the left mouse button at the
upper-left corner of the region you want to have in the slice, then
move the mouse pointer to the lower-right corner and release the
button.
The most convenient way is to set the optimal slice by using
BoundingBox information automatically determined from the document by
typing @kbd{s b} (@code{doc-view-set-slice-from-bounding-box}).
@findex doc-view-reset-slice
To cancel the selected slice, type @kbd{s r}
(@code{doc-view-reset-slice}). Then DocView shows the entire page
including its entire margins.
@node DocView Conversion
@subsection DocView Conversion
@vindex doc-view-cache-directory
@findex doc-view-clear-cache
For efficiency, DocView caches the images produced by @command{gs}.
The name of this directory is given by the variable
@code{doc-view-cache-directory}. You can clear the cache directory by
typing @code{M-x doc-view-clear-cache}.
@findex doc-view-kill-proc
@findex doc-view-kill-proc-and-buffer
To force reconversion of the currently viewed document, type @kbd{r}
or @kbd{g} (@code{revert-buffer}). To kill the converter process
associated with the current buffer, type @kbd{K}
(@code{doc-view-kill-proc}). The command @kbd{k}
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
the DocView buffer.
@node EWW
@section Web Browsing with EWW
@findex eww
@findex eww-open-file
@dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs.
It allows browsing URLs within an Emacs buffer. The command @kbd{M-x
eww} will open a URL or search the web. You can open a file
using the command @kbd{M-x eww-open-file}. You can use EWW as the
web browser for @code{browse-url}, @pxref{Browse-URL}. For full
details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
@node Shell
@section Running Shell Commands from Emacs
@cindex subshell
@cindex shell commands
Emacs has commands for passing single command lines to shell
subprocesses, and for running a shell interactively with input and
output to an Emacs buffer, and for running a shell in a terminal
emulator window.
@table @kbd
@item M-! @var{cmd} @key{RET}
Run the shell command @var{cmd} and display the output
(@code{shell-command}).
@item M-| @var{cmd} @key{RET}
Run the shell command @var{cmd} with region contents as input;
optionally replace the region with the output
(@code{shell-command-on-region}).
@item M-& @var{cmd} @key{RET}
Run the shell command @var{cmd} asynchronously, and display the output
(@code{async-shell-command}).
@item M-x shell
Run a subshell with input and output through an Emacs buffer. You can
then give commands interactively.
@item M-x term
Run a subshell with input and output through an Emacs buffer. You can
then give commands interactively. Full terminal emulation is
available.
@end table
@vindex exec-path
Whenever you specify a relative file name for an executable program
(either in the @var{cmd} argument to one of the above commands, or in
other contexts), Emacs searches for the program in the directories
specified by the variable @code{exec-path}. The value of this
variable must be a list of directory names; the default value is
initialized from the environment variable @env{PATH} when Emacs is
started (@pxref{General Variables}).
@kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It
is documented in its own manual.
@ifnottex
@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
@end ifnottex
@iftex
See the Eshell Info manual, which is distributed with Emacs.
@end iftex
@menu
* Single Shell:: How to run one shell command and return.
* Interactive Shell:: Permanent shell taking input via Emacs.
* Shell Mode:: Special Emacs commands used with permanent shell.
* Shell Prompts:: Two ways to recognize shell prompts.
* History: Shell History. Repeating previous commands in a shell buffer.
* Directory Tracking:: Keeping track when the subshell changes directory.
* Options: Shell Options. Options for customizing Shell mode.
* Terminal emulator:: An Emacs window as a terminal emulator.
* Term Mode:: Special Emacs commands used in Term mode.
* Remote Host:: Connecting to another computer.
* Serial Terminal:: Connecting to a serial port.
@end menu
@node Single Shell
@subsection Single Shell Commands
@kindex M-!
@findex shell-command
@kbd{M-!} (@code{shell-command}) reads a line of text using the
minibuffer and executes it as a shell command, in a subshell made just
for that command. Standard input for the command comes from the null
device. If the shell command produces any output, the output appears
either in the echo area (if it is short), or in an Emacs buffer named
@file{*Shell Command Output*}, displayed in another window (if the
output is long).
For instance, one way to decompress a file named @file{foo.gz} is to
type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally
creates the file @file{foo} and produces no terminal output.
A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!},
causes it to insert terminal output into the current buffer instead of
a separate buffer. It puts point before the output, and sets the mark
after the output. For instance, @kbd{M-1 M-! gunzip < foo.gz
@key{RET}} would insert the uncompressed form of the file
@file{foo.gz} into the current buffer.
Provided the specified shell command does not end with @samp{&}, it
runs @dfn{synchronously}, and you must wait for it to exit before
continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit;
this sends a @code{SIGINT} signal to terminate the shell command (this
is the same signal that @kbd{C-c} normally generates in the shell).
Emacs then waits until the command actually terminates. If the shell
command doesn't stop (because it ignores the @code{SIGINT} signal),
type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal,
which is impossible to ignore.
@kindex M-&
@findex async-shell-command
A shell command that ends in @samp{&} is executed
@dfn{asynchronously}, and you can continue to use Emacs as it runs.
You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
shell command asynchronously; this is exactly like calling @kbd{M-!}
with a trailing @samp{&}, except that you do not need the @samp{&}.
The default output buffer for asynchronous shell commands is named
@samp{*Async Shell Command*}. Emacs inserts the output into this
buffer as it comes in, whether or not the buffer is visible in a
window.
@vindex async-shell-command-buffer
If you want to run more than one asynchronous shell command at the
same time, they could end up competing for the output buffer. The
option @code{async-shell-command-buffer} specifies what to do about
this; e.g., whether to rename the pre-existing output buffer, or to
use a different buffer for the new command. Consult the variable's
documentation for more possibilities.
@kindex M-|
@findex shell-command-on-region
@kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
passes the contents of the region as the standard input to the shell
command, instead of no input. With a numeric argument, it deletes the
old region and replaces it with the output from the shell command.
For example, you can use @kbd{M-|} with the @command{gpg} program to
see what keys are in the buffer. If the buffer contains a GnuPG key,
type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
to @command{gpg}. This will output the list of keys to the
@file{*Shell Command Output*} buffer.
@vindex shell-file-name
The above commands use the shell specified by the variable
@code{shell-file-name}. Its default value is determined by the
@env{SHELL} environment variable when Emacs is started. If the file
name is relative, Emacs searches the directories listed in
@code{exec-path} (@pxref{Shell}).
To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}.
@vindex shell-command-default-error-buffer
By default, error output is intermixed with the regular output in
the output buffer. But if you change the value of the variable
@code{shell-command-default-error-buffer} to a string, error output is
inserted into a buffer of that name.
@node Interactive Shell
@subsection Interactive Subshell
@findex shell
To run a subshell interactively, type @kbd{M-x shell}. This creates
(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess
with input coming from and output going to that buffer. That is to
say, any terminal output from the subshell goes into the buffer,
advancing point, and any terminal input for the subshell comes from
text in the buffer. To give input to the subshell, go to the end of
the buffer and type the input, terminated by @key{RET}.
While the subshell is waiting or running a command, you can switch
windows or buffers and perform other editing in Emacs. Emacs inserts
the output from the subshell into the Shell buffer whenever it has
time to process it (e.g., while waiting for keyboard input).
@cindex @code{comint-highlight-input} face
@cindex @code{comint-highlight-prompt} face
In the Shell buffer, prompts are displayed with the face
@code{comint-highlight-prompt}, and submitted input lines are
displayed with the face @code{comint-highlight-input}. This makes it
easier to distinguish input lines from the shell output.
@xref{Faces}.
To make multiple subshells, invoke @kbd{M-x shell} with a prefix
argument (e.g., @kbd{C-u M-x shell}). Then the command will read a
buffer name, and create (or reuse) a subshell in that buffer. You can
also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
Subshells in different buffers run independently and in parallel.
@vindex explicit-shell-file-name
@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
To specify the shell file name used by @kbd{M-x shell}, customize
the variable @code{explicit-shell-file-name}. If this is @code{nil}
(the default), Emacs uses the environment variable @env{ESHELL} if it
exists. Otherwise, it usually uses the variable
@code{shell-file-name} (@pxref{Single Shell}); but if the default
directory is remote (@pxref{Remote Files}), it prompts you for the
shell file name.
Emacs sends the new shell the contents of the file
@file{~/.emacs_@var{shellname}} as input, if it exists, where
@var{shellname} is the name of the file that the shell was loaded
from. For example, if you use bash, the file sent to it is
@file{~/.emacs_bash}. If this file is not found, Emacs tries with
@file{~/.emacs.d/init_@var{shellname}.sh}.
To specify a coding system for the shell, you can use the command
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can
also change the coding system for a running subshell by typing
@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication
Coding}.
@cindex @env{INSIDE_EMACS} environment variable
Emacs sets the environment variable @env{INSIDE_EMACS} in the
subshell to @samp{@var{version},comint}, where @var{version} is the
Emacs version (e.g., @samp{24.1}). Programs can check this variable
to determine whether they are running inside an Emacs subshell.
@node Shell Mode
@subsection Shell Mode
@cindex Shell mode
@cindex mode, Shell
The major mode for Shell buffers is Shell mode. Many of its special
commands are bound to the @kbd{C-c} prefix, and resemble the usual
editing and job control characters present in ordinary shells, except
that you must type @kbd{C-c} first. Here is a list of Shell mode
commands:
@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
Send the current line as input to the subshell
(@code{comint-send-input}). Any shell prompt at the beginning of the
line is omitted (@pxref{Shell Prompts}). If point is at the end of
buffer, this is like submitting the command line in an ordinary
interactive shell. However, you can also invoke @key{RET} elsewhere
in the shell buffer to submit the current line as input.
@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@findex completion-at-point
@cindex shell completion
Complete the command name or file name before point in the shell
buffer (@code{completion-at-point}). This uses the usual Emacs
completion rules (@pxref{Completion}), with the completion
alternatives being file names, environment variable names, the shell
command history, and history references (@pxref{History References}).
For options controlling the completion, @pxref{Shell Options}.
@item M-?
@kindex M-? @r{(Shell mode)}
@findex comint-dynamic-list-filename@dots{}
Display temporarily a list of the possible completions of the file
name before point (@code{comint-dynamic-list-filename-completions}).
@item C-d
@kindex C-d @r{(Shell mode)}
@findex comint-delchar-or-maybe-eof
Either delete a character or send @acronym{EOF}
(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
buffer, this sends @acronym{EOF} to the subshell. Typed at any other
position in the buffer, this deletes a character as usual.
@item C-c C-a
@kindex C-c C-a @r{(Shell mode)}
@findex comint-bol-or-process-mark
Move to the beginning of the line, but after the prompt if any
(@code{comint-bol-or-process-mark}). If you repeat this command twice
in a row, the second time it moves back to the process mark, which is
the beginning of the input that you have not yet sent to the subshell.
(Normally that is the same place---the end of the prompt on this
line---but after @kbd{C-c @key{SPC}} the process mark may be in a
previous line.)
@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together. This
command inserts a newline before point, but does not send the preceding
text as input to the subshell---at least, not yet. Both lines, the one
before this newline and the one after, will be sent together (along with
the newline that separates them), when you type @key{RET}.
@item C-c C-u
@kindex C-c C-u @r{(Shell mode)}
@findex comint-kill-input
Kill all text pending at end of buffer to be sent as input
(@code{comint-kill-input}). If point is not at end of buffer,
this only kills the part of this text that precedes point.
@item C-c C-w
@kindex C-c C-w @r{(Shell mode)}
Kill a word before point (@code{backward-kill-word}).
@item C-c C-c
@kindex C-c C-c @r{(Shell mode)}
@findex comint-interrupt-subjob
Interrupt the shell or its current subjob if any
(@code{comint-interrupt-subjob}). This command also kills
any shell input pending in the shell buffer and not yet sent.
@item C-c C-z
@kindex C-c C-z @r{(Shell mode)}
@findex comint-stop-subjob
Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
This command also kills any shell input pending in the shell buffer and
not yet sent.
@item C-c C-\
@findex comint-quit-subjob
@kindex C-c C-\ @r{(Shell mode)}
Send quit signal to the shell or its current subjob if any
(@code{comint-quit-subjob}). This command also kills any shell input
pending in the shell buffer and not yet sent.
@item C-c C-o
@kindex C-c C-o @r{(Shell mode)}
@findex comint-delete-output
Delete the last batch of output from a shell command
(@code{comint-delete-output}). This is useful if a shell command spews
out lots of output that just gets in the way.
@item C-c C-s
@kindex C-c C-s @r{(Shell mode)}
@findex comint-write-output
Write the last batch of output from a shell command to a file
(@code{comint-write-output}). With a prefix argument, the file is
appended to instead. Any prompt at the end of the output is not
written.
@item C-c C-r
@itemx C-M-l
@kindex C-c C-r @r{(Shell mode)}
@kindex C-M-l @r{(Shell mode)}
@findex comint-show-output
Scroll to display the beginning of the last batch of output at the top
of the window; also move the cursor there (@code{comint-show-output}).
@item C-c C-e
@kindex C-c C-e @r{(Shell mode)}
@findex comint-show-maximum-output
Scroll to put the end of the buffer at the bottom of the window
(@code{comint-show-maximum-output}).
@item C-c C-f
@kindex C-c C-f @r{(Shell mode)}
@findex shell-forward-command
@vindex shell-command-regexp
Move forward across one shell command, but not beyond the current line
(@code{shell-forward-command}). The variable @code{shell-command-regexp}
specifies how to recognize the end of a command.
@item C-c C-b
@kindex C-c C-b @r{(Shell mode)}
@findex shell-backward-command
Move backward across one shell command, but not beyond the current line
(@code{shell-backward-command}).
@item M-x dirs
Ask the shell for its working directory, and update the Shell buffer's
default directory. @xref{Directory Tracking}.
@item M-x send-invisible @key{RET} @var{text} @key{RET}
@findex send-invisible
Send @var{text} as input to the shell, after reading it without
echoing. This is useful when a shell command runs a program that asks
for a password.
Please note that Emacs will not echo passwords by default. If you
really want them to be echoed, evaluate (@pxref{Lisp Eval}) the
following Lisp expression:
@example
(remove-hook 'comint-output-filter-functions
'comint-watch-for-password-prompt)
@end example
@item M-x comint-continue-subjob
@findex comint-continue-subjob
Continue the shell process. This is useful if you accidentally suspend
the shell process.@footnote{You should not suspend the shell process.
Suspending a subjob of the shell is a completely different matter---that
is normal practice, but you must use the shell to continue the subjob;
this command won't do it.}
@item M-x comint-strip-ctrl-m
@findex comint-strip-ctrl-m
Discard all control-M characters from the current group of shell output.
The most convenient way to use this command is to make it run
automatically when you get output from the subshell. To do that,
evaluate this Lisp expression:
@example
(add-hook 'comint-output-filter-functions
'comint-strip-ctrl-m)
@end example
@item M-x comint-truncate-buffer
@findex comint-truncate-buffer
This command truncates the shell buffer to a certain maximum number of
lines, specified by the variable @code{comint-buffer-maximum-size}.
Here's how to do this automatically each time you get output from the
subshell:
@example
(add-hook 'comint-output-filter-functions
'comint-truncate-buffer)
@end example
@end table
@cindex Comint mode
@cindex mode, Comint
Shell mode is a derivative of Comint mode, a general-purpose mode for
communicating with interactive subprocesses. Most of the features of
Shell mode actually come from Comint mode, as you can see from the
command names listed above. The special features of Shell mode include
the directory tracking feature, and a few user commands.
Other Emacs features that use variants of Comint mode include GUD
(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
@findex comint-run
You can use @kbd{M-x comint-run} to execute any program of your choice
in a subprocess using unmodified Comint mode---without the