-
-
Notifications
You must be signed in to change notification settings - Fork 39
/
faq.texi
4485 lines (3531 loc) · 154 KB
/
faq.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
\input texinfo @c -*- mode: texinfo; -*-
@c %**start of header
@setfilename ../../info/efaq
@settitle GNU Emacs FAQ
@c %**end of header
@c This is used in many places
@set VER 23.2.90
@c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
@c Feel free to install changes without prior permission (but I'd
@c appreciate a notice if you do).
@copying
Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
2009, 2010 Free Software Foundation, Inc.@*
Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000
Reuven M. Lerner@*
Copyright @copyright{} 1992, 1993 Steven Byrnes@*
Copyright @copyright{} 1990, 1991, 1992 Joseph Brian Wells@*
@quotation
This list of frequently asked questions about GNU Emacs with answers
(``FAQ'') may be translated into other languages, transformed into other
formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
The same conditions apply to any derivative of the FAQ as apply to the FAQ
itself. Every copy of the FAQ must include this notice or an approved
translation, information on who is currently maintaining the FAQ and how to
contact them (including their e-mail address), and information on where the
latest version of the FAQ is archived (including FTP information).
The FAQ may be copied and redistributed under these conditions, except that
the FAQ may not be embedded in a larger literary work unless that work
itself allows free copying and redistribution.
[This version has been heavily edited since it was included in the Emacs
distribution.]
@end quotation
@end copying
@dircategory Emacs
@direntry
* Emacs FAQ: (efaq). Frequently Asked Questions about Emacs.
@end direntry
@c The @titlepage stuff only appears in the printed version
@titlepage
@sp 10
@center @titlefont{GNU Emacs FAQ}
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@node Top, FAQ notation, (dir), (dir)
@top The GNU Emacs FAQ
@c FIXME @today is just the day we ran `makeinfo'.
This is the GNU Emacs FAQ, last updated on @today{}.
This FAQ is maintained as a part of GNU Emacs. If you find any errors,
or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
them.
This is the version of the FAQ distributed with Emacs @value{VER}, and
mainly describes that version. Although there is some information on
older versions, details about very old releases (now only of historical
interest) have been removed. If you are interested in this, consult
either the version of the FAQ distributed with older versions of Emacs,
or the history of this document in the Emacs source repository.
Since Emacs releases are very stable, we recommend always running the
latest release.
This FAQ is not updated very frequently. When you have a question about
Emacs, the Emacs manual is often the best starting point.
@ifnottex
@insertcopying
@end ifnottex
@menu
* FAQ notation::
* General questions::
* Getting help::
* Status of Emacs::
* Common requests::
* Bugs and problems::
* Compiling and installing Emacs::
* Finding Emacs and related packages::
* Major packages and programs::
* Key bindings::
* Alternate character sets::
* Mail and news::
* Concept index::
@end menu
@c ------------------------------------------------------------
@node FAQ notation
@chapter FAQ notation
@cindex FAQ notation
This chapter describes notation used in the GNU Emacs FAQ, as well as in
the Emacs documentation. Consult this section if this is the first time
you are reading the FAQ, or if you are confused by notation or terms
used in the FAQ.
@menu
* Basic keys::
* Extended commands::
* Emacs manual::
* File-name conventions::
* Common acronyms::
@end menu
@node Basic keys
@section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
@cindex Basic keys
@cindex Control key, notation for
@cindex @key{Meta} key, notation for
@cindex Control-Meta characters, notation for
@cindex @kbd{C-h}, definition of
@cindex @kbd{C-M-h}, definition of
@cindex @key{DEL}, definition of
@cindex @key{ESC}, definition of
@cindex @key{LFD}, definition of
@cindex @key{RET}, definition of
@cindex @key{SPC}, definition of
@cindex @key{TAB}, definition of
@cindex Notation for keys
@itemize @bullet
@item
@kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
@item
@kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
(if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
@item
@kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
and @key{Meta}
@item
@kbd{C-M-x}: a synonym for the above
@item
@key{LFD}: Linefeed or Newline; same as @kbd{C-j}
@item
@key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
@item
@key{DEL}: @key{Delete}, usually @strong{not} the same as
@key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
deleting invokes Emacs help)
@item
@key{ESC}: Escape; same as @kbd{C-[}
@item
@key{TAB}: Tab; same as @kbd{C-i}
@item
@key{SPC}: Space bar
@end itemize
Key sequences longer than one key (and some single-key sequences) are
written inside quotes or on lines by themselves, like this:
@display
@kbd{M-x frobnicate-while-foo RET}
@end display
@noindent
Any real spaces in such a key sequence should be ignored; only @key{SPC}
really means press the space key.
The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
that would be sent by pressing just @key{x} minus 96 (or 64 for
upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
@acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
@key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
7@footnote{
DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
pressed.}.
@kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
@kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
@c FIXME I cannot understand the previous sentence.
@inforef{Keys, Keys, emacs}, for more information. (@xref{Emacs
manual}, for more information about Info.)
@node Extended commands
@section What does @file{M-x @var{command}} mean?
@cindex Extended commands
@cindex Commands, extended
@cindex M-x, meaning of
@kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
what @kbd{M-x} and @key{RET} mean.)
@kbd{M-x} (by default) invokes the command
@code{execute-extended-command}. This command allows you to run any
Emacs command if you can remember the command's name. If you can't
remember the command's name, you can type @key{TAB} and @key{SPC} for
completion, @key{?} for a list of possibilities, and @kbd{M-p} and
@kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered.
An Emacs @dfn{command} is an @dfn{interactive} Emacs function.
@cindex @key{Do} key
Your system administrator may have bound other key sequences to invoke
@code{execute-extended-command}. A function key labeled @kbd{Do} is a
good candidate for this, on keyboards that have such a key.
If you need to run non-interactive Emacs functions, see @ref{Evaluating
Emacs Lisp code}.
@node Emacs manual
@section How do I read topic XXX in the Emacs manual?
@cindex Emacs manual, reading topics in
@cindex Reading topics in the Emacs manual
@cindex Finding topics in the Emacs manual
@cindex Info, finding topics in
When we refer you to some @var{topic} in the Emacs manual, you can
read this manual node inside Emacs (assuming nothing is broken) by
typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
This invokes Info, the GNU hypertext documentation browser. If you don't
already know how to use Info, type @key{?} from within Info.
If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
@key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
If these commands don't work as expected, your system administrator may
not have installed the Info files, or may have installed them
improperly. In this case you should complain.
If you are reading this FAQ in Info, you can simply press @key{RET} on a
reference to follow it.
@xref{Getting a printed manual}, if you would like a paper copy of the
Emacs manual.
@node File-name conventions
@section What are @file{etc/GNU}, @file{src/config.h}, @file{site-lisp/default.el}, etc.?
@cindex File-name conventions
@cindex Conventions for file names
@cindex Directories and files that come with Emacs
These are files that come with Emacs. The Emacs distribution is divided
into subdirectories; e.g. @file{etc}, @file{lisp}, and @file{src}.
Some of these (e.g. @file{etc} and @file{lisp}) are present both in
an installed Emacs and in the sources, but some (e.g. @file{src}) are
only found in the sources.
If you use Emacs, but don't know where it is kept on your system, start
Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
name displayed by this will be the full pathname of the installed
@file{etc} directory. (This full path is recorded in the Emacs variable
@code{data-directory}, and @kbd{C-h v} displays the value and the
documentation of a variable.)
The location of your Info directory (i.e., where Info documentation
is stored) is kept in the variable @code{Info-default-directory-list}. Use
@kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
this variable, which will be a list of directory names. The last
directory in that list is probably where most Info files are stored. By
default, Emacs Info documentation is placed in @file{/usr/local/share/info}.
For information on some of the files in the @file{etc} directory,
@pxref{Informational files for Emacs}.
@node Common acronyms
@section What are FSF, LPF, GNU, RMS, FTP, and GPL?
@cindex FSF, definition of
@cindex LPF, definition of
@cindex GNU, definition of
@cindex RMS, definition of
@cindex Stallman, Richard, acronym for
@cindex Richard Stallman, acronym for
@cindex FTP, definition of
@cindex GPL, definition of
@cindex Acronyms, definitions for
@cindex Common acronyms, definitions for
@table @asis
@item FSF
Free Software Foundation
@item LPF
League for Programming Freedom
@item GNU
GNU's Not Unix
@item RMS
Richard Matthew Stallman
@item FTP
File Transfer Protocol
@item GPL
GNU General Public License
@end table
Avoid confusing the FSF and the LPF. The LPF opposes
look-and-feel copyrights and software patents. The FSF aims to make
high quality free software available for everyone.
The word ``free'' in the title of the Free Software Foundation refers to
``freedom,'' not ``zero cost.'' Anyone can charge any price for
GPL-covered software that they want to. However, in practice, the
freedom enforced by the GPL leads to low prices, because you can always
get the software for less money from someone else, since everyone has
the right to resell or give away GPL-covered software.
@c ------------------------------------------------------------
@node General questions
@chapter General questions
@cindex General questions
This chapter contains general questions having to do with Emacs, the
Free Software Foundation, and related organizations.
@menu
* The LPF::
* Real meaning of copyleft::
* Guidelines for newsgroup postings::
* Newsgroup archives::
* Reporting bugs::
* Unsubscribing from Emacs lists::
* Contacting the FSF::
@end menu
@node The LPF
@section What is the LPF?
@cindex LPF, description of
@cindex League for Programming Freedom
@cindex Software patents, opposition to
@cindex Patents for software, opposition to
The LPF opposes the expanding danger of software patents and
look-and-feel copyrights. More information on the LPF's views is
available at @uref{http://progfree.org/, the LPF home page}.
@node Real meaning of copyleft
@section What is the real legal meaning of the GNU copyleft?
@cindex Copyleft, real meaning of
@cindex GPL, real meaning of
@cindex General Public License, real meaning of
@cindex Discussion of the GPL
The real legal meaning of the GNU General Public License (copyleft) will
only be known if and when a judge rules on its validity and scope.
There has never been a copyright infringement case involving the GPL to
set any precedents. Although legal actions have been brought against
companies for violating the terms of the GPL, so far all have been
settled out of court (in favour of the plaintiffs). Please take any
discussion regarding this issue to the newsgroup
@uref{news:gnu.misc.discuss}, which was created to hold the extensive
flame wars on the subject.
RMS writes:
@quotation
The legal meaning of the GNU copyleft is less important than the spirit,
which is that Emacs is a free software project and that work pertaining
to Emacs should also be free software. ``Free'' means that all users
have the freedom to study, share, change and improve Emacs. To make
sure everyone has this freedom, pass along source code when you
distribute any version of Emacs or a related program, and give the
recipients the same freedom that you enjoyed.
@end quotation
@node Guidelines for newsgroup postings
@section What are appropriate messages for the various Emacs newsgroups?
@cindex Newsgroups, appropriate messages for
@cindex GNU newsgroups, appropriate messages for
@cindex Usenet groups, appropriate messages for
@cindex Mailing lists, appropriate messages for
@cindex Posting messages to newsgroups
@cindex GNU mailing lists
The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
mailing list (@pxref{Informational files for Emacs}). For those lists
which are gatewayed with newsgroups, it lists both the newsgroup name
and the mailing list address. The Emacs mailing lists are also
described at @uref{http://savannah.gnu.org/mail/?group=emacs, the Emacs
Savannah page}.
The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
in general. The newsgroup @uref{news:gnu.emacs.help} is specifically
for GNU Emacs. It therefore makes no sense to cross-post to both
groups, since only one can be appropriate to any question.
Messages advocating ``non-free'' software are considered unacceptable on
any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
which was created to hold the extensive flame-wars on the subject.
``Non-free'' software includes any software for which the end user can't
freely modify the source code and exchange enhancements. Be careful to
remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
posting a followup that recommends such software.
@uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
@node Newsgroup archives
@section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
@cindex Archived postings from @code{gnu.emacs.help}
@cindex Usenet archives for GNU groups
@cindex Old Usenet postings for GNU groups
The FSF has maintained archives of all of the GNU mailing lists for many
years, although there may be some unintentional gaps in coverage. The
archive can be browsed over the web at
@uref{http://lists.gnu.org/archive/html/, the GNU mail archive}. Raw
files can be downloaded from @uref{ftp://lists.gnu.org/}.
Web-based Usenet search services, such as
@uref{http://groups.google.com/groups/dir?q=gnu&, Google}, also
archive the @code{gnu.*} groups.
You can also read the archives of the @code{gnu.*} groups and post new
messages at @uref{http://gmane.org/, Gmane}. Gmane is a service that
presents mailing lists as newsgroups (even those without a traditional
mail-to-news gateway).
@node Reporting bugs
@section Where should I report bugs and other problems with Emacs?
@cindex Bug reporting
@cindex Good bug reports
@cindex How to submit a bug report
@cindex Reporting bugs
The correct way to report Emacs bugs is to use the command
@kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
essential information and the correct e-mail address, which is
@email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
news to submit the bug report. This ensures a reliable return address
so you can be contacted for further details.
Be sure to read the ``Bugs'' section of the Emacs manual before reporting
a bug! The manual describes in detail how to submit a useful bug
report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
(@xref{Emacs manual}, if you don't know how to read the manual.)
RMS says:
@quotation
Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
it takes the time of an unnecessarily large group of people, most of
whom are just users and have no idea how to fix these problem.
@email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
who are more likely to know what to do and have expressed a wish to
receive more messages about Emacs than the others.
@end quotation
RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
@quotation
If you have reported a bug and you don't hear about a possible fix,
then after a suitable delay (such as a week) it is okay to post on
@code{gnu.emacs.help} asking if anyone can help you.
@end quotation
If you are unsure whether you have found a bug, consider the following
non-exhaustive list, courtesy of RMS:
@quotation
If Emacs crashes, that is a bug. If Emacs gets compilation errors
while building, that is a bug. If Emacs crashes while building, that
is a bug. If Lisp code does not do what the documentation says it
does, that is a bug.
@end quotation
@node Unsubscribing from Emacs lists
@section How do I unsubscribe from a mailing list?
@cindex Unsubscribing from GNU mailing lists
@cindex Removing yourself from GNU mailing lists
If you are receiving a GNU mailing list named @var{list}, you should be
able to unsubscribe from it by sending a request to the address
@email{@var{list}-request@@gnu.org}. Mailing lists mails normally
contain information in either the message header
(@samp{List-Unsubscribe:}) or as a footer that tells you how to
unsubscribe.
@node Contacting the FSF
@section What is the current address of the FSF?
@cindex Snail mail address of the FSF
@cindex Postal address of the FSF
@cindex Contracting the FSF
@cindex Free Software Foundation, contacting
For up-to-date information, see
@uref{http://www.fsf.org/about/contact.html, the FSF contact web-page}.
@table @asis
@item E-mail
info@@fsf.org
@item Telephone
+1-617-542-5942
@item Fax
+1-617-542-2652
@item World Wide Web
@uref{http://www.fsf.org/}
@item Postal address
Free Software Foundation@*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301@*
USA@*
@end table
@cindex Ordering GNU software
For details on how to order items directly from the FSF, see the
@uref{http://shop.fsf.org/, FSF on-line store}.
@c ------------------------------------------------------------
@node Getting help
@chapter Getting help
@cindex Getting help
This chapter tells you how to get help with Emacs.
@menu
* Basic editing::
* Learning how to do something::
* Getting a printed manual::
* Emacs Lisp documentation::
* Installing Texinfo documentation::
* Printing a Texinfo file::
* Viewing Info files outside of Emacs::
* Informational files for Emacs::
* Help installing Emacs::
* Obtaining the FAQ::
@end menu
@node Basic editing
@section I'm just starting Emacs; how do I do basic editing?
@cindex Basic editing with Emacs
@cindex Beginning editing
@cindex Tutorial, invoking the
@cindex Self-paced tutorial, invoking the
@cindex Help system, entering the
Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
@kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
is available in many foreign languages such as French, German, Japanese,
Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
to choose your language and start the tutorial.
Your system administrator may have changed @kbd{C-h} to act like
@key{DEL} to deal with local keyboards. You can use @kbd{M-x
help-for-help} instead to invoke help. To discover what key (if any)
invokes help on your system, type @kbd{M-x where-is @key{RET}
help-for-help @key{RET}}. This will print a comma-separated list of key
sequences in the echo area. Ignore the last character in each key
sequence listed. Each of the resulting key sequences (e.g. @key{F1} is
common) invokes help.
Emacs help works best if it is invoked by a single key whose value
should be stored in the variable @code{help-char}.
@node Learning how to do something
@section How do I find out how to do something in Emacs?
@cindex Help for Emacs
@cindex Learning to do something in Emacs
@cindex Reference card for Emacs
@cindex Overview of help systems
There are several methods for finding out how to do things in Emacs.
@itemize @bullet
@cindex Reading the Emacs manual
@item
The complete text of the Emacs manual is available via the Info
hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
Typing @key{h} immediately after entering Info will provide a short
tutorial on how to use it.
@cindex Lookup a subject in a manual
@cindex Index search in a manual
@item
To quickly locate the section of the manual which discusses a certain
issue, or describes a command or a variable, type @kbd{C-h i m emacs
@key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
topic, the command, or the variable which you are looking for. If this
does not land you on the right place in the manual, press @kbd{,}
(comma) repeatedly until you find what you need. (The @kbd{i} and
@kbd{,} keys invoke the index-searching functions, which look for the
@var{topic} you type in all the indices of the Emacs manual.)
@cindex Apropos
@item
You can list all of the commands whose names contain a certain word
(actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
command-apropos}).
@cindex Command description in the manual
@item
The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
for the name of a command, and then attempts to find the section in the
Emacs manual where that command is described.
@cindex Finding commands and variables
@item
You can list all of the functions and variables whose names contain a
certain word using @kbd{M-x apropos}.
@item
You can list all of the functions and variables whose documentation
matches a regular expression or a string, using @kbd{M-x
apropos-documentation}.
@item
You can order a hardcopy of the manual from the FSF. @xref{Getting a
printed manual}.
@cindex Reference cards, in other languages
@item
You can get a printed reference card listing commands and keys to
invoke them. You can order one from the FSF for $2 (or 10 for $18),
or you can print your own from the @file{etc/refcards/refcard.tex} or
@file{etc/refcards/refcard.pdf} files in the Emacs distribution.
Beginning with version 21.1, the Emacs distribution comes with
translations of the reference card into several languages; look for
files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
is a two-letter code of the language. For example, the German version
of the reference card is in the files @file{etc/refcards/de-refcard.tex}
and @file{etc/recards/de-refcard.pdf}.
@item
There are many other commands in Emacs for getting help and
information. To get a list of these commands, type @samp{?} after
@kbd{C-h}.
@end itemize
@node Getting a printed manual
@section How do I get a printed copy of the Emacs manual?
@cindex Printed Emacs manual, obtaining
@cindex Manual, obtaining a printed or HTML copy of
@cindex Emacs manual, obtaining a printed or HTML copy of
You can order a printed copy of the Emacs manual from the FSF. For
details see the @uref{http://shop.fsf.org/, FSF on-line store}.
The full Texinfo source for the manual also comes in the @file{doc/emacs}
directory of the Emacs distribution, if you're daring enough to try to
print out this several-hundred-page manual yourself (@pxref{Printing a Texinfo
file}).
If you absolutely have to print your own copy, and you don't have @TeX{},
you can get a PostScript or PDF (or HTML) version from
@uref{http://www.gnu.org/software/emacs/manual/}
@xref{Learning how to do something}, for how to view the manual from Emacs.
@node Emacs Lisp documentation
@section Where can I get documentation on Emacs Lisp?
@cindex Documentation on Emacs Lisp
@cindex Function documentation
@cindex Variable documentation
@cindex Emacs Lisp Reference Manual
@cindex Reference manual for Emacs Lisp
Within Emacs, you can type @kbd{C-h f} to get the documentation for a
function, @kbd{C-h v} for a variable.
For more information, the Emacs Lisp Reference Manual is available
in Info format (@pxref{Top, Emacs Lisp,, elisp, The
Emacs Lisp Reference Manual}).
You can also order a hardcopy of the manual from the FSF, for details
see the @uref{http://shop.fsf.org/, FSF on-line store}. (This manual is
not always in print.)
An HTML version of the Emacs Lisp Reference Manual is available at
@uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
@node Installing Texinfo documentation
@section How do I install a piece of Texinfo documentation?
@cindex Texinfo documentation, installing
@cindex Installing Texinfo documentation
@cindex New Texinfo files, installing
@cindex Documentation, installing new Texinfo files
@cindex Info files, how to install
Emacs releases come with pre-built Info files, and the normal install
process places them in the correct location. This is true for most
applications that provide Info files. The following section is only
relevant if you want to install extra Info files by hand.
First, you must turn the Texinfo source files into Info files. You may
do this using the stand-alone @file{makeinfo} program, available as part
of the Texinfo package at
@uref{http://www.gnu.org/software/texinfo/}
For information about the Texinfo format, read the Texinfo manual which
comes with the Texinfo package. This manual also comes installed in
Info format, so you can read it from Emacs; type @kbd{C-h i m texinfo
@key{RET}}.
@c FIXME is this a complete alternative?
@c Probably not, given that we require makeinfo to build Emacs.
Alternatively, you could use the Emacs command @kbd{M-x
texinfo-format-buffer}, after visiting the Texinfo source file of the
manual you want to convert.
Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
resulting Info files in Emacs's Info tree. To install Info files,
perform these steps:
@enumerate
@item
Move the files to the @file{info} directory in the installed Emacs
distribution. @xref{File-name conventions}, if you don't know where that
is.
@item
Run the @code{install-info} command, which is part of the Texinfo
distribution, to update the main Info directory menu, like this:
@example
install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
@end example
@noindent
where @var{dir-path} is the full path to the directory where you copied
the produced Info file(s), and @var{file} is the name of the Info file
you produced and want to install.
If you don't have the @code{install-info} command installed, you can
edit the file @file{info/dir} in the installed Emacs distribution, and
add a line for the top level node in the Info package that you are
installing. Follow the examples already in this file. The format is:
@example
* Topic: (relative-pathname). Short description of topic.
@end example
@end enumerate
If you want to install Info files and you don't have the necessary
privileges, you have several options:
@itemize @bullet
@item
Info files don't actually need to be installed before being used.
You can use a prefix argument for the @code{info} command and specify
the name of the Info file in the minibuffer. This goes to the node
named @samp{Top} in that file. For example, to view a Info file named
@file{@var{info-file}} in your home directory, you can type this:
@example
@kbd{C-u C-h i ~/@var{info-file} @key{RET}}
@end example
Alternatively, you can feed a file name to the @code{Info-goto-node}
command (invoked by pressing @key{g} in Info mode) by typing the name
of the file in parentheses, like this:
@example
@kbd{C-h i g (~/@var{info-file}) @key{RET}}
@end example
@item
You can create your own Info directory. You can tell Emacs where that
Info directory is by adding its pathname to the value of the variable
@code{Info-default-directory-list}. For example, to use a private Info
directory which is a subdirectory of your home directory named @file{Info},
you could put this in your @file{.emacs} file:
@lisp
(add-to-list 'Info-default-directory-list "~/Info")
@end lisp
You will need a top-level Info file named @file{dir} in this directory
which has everything the system @file{dir} file has in it, except it
should list only entries for Info files in that directory. You might
not need it if (fortuitously) all files in this directory were
referenced by other @file{dir} files. The node lists from all
@file{dir} files in @code{Info-default-directory-list} are merged by the
Info system.
@end itemize
@node Printing a Texinfo file
@section How do I print a Texinfo file?
@cindex Printing a Texinfo file
@cindex Texinfo file, printing
@cindex Printing documentation
You can't get nicely printed output from Info files; you must still have
the original Texinfo source file for the manual you want to print.
Assuming you have @TeX{} installed on your system, follow these steps:
@enumerate
@item
Make sure the first line of the Texinfo file looks like this:
@example
\input texinfo
@end example
You may need to change @samp{texinfo} to the full pathname of the
@file{texinfo.tex} file, which comes with Emacs as
@file{doc/misc/texinfo.tex} (or copy or link it into the current directory).
@item
Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
the name of the Texinfo source file for which you want to produce a
printed copy. The @samp{texi2dvi} script is part of the GNU Texinfo
distribution.
Alternatively, @samp{texi2pdf} produces PDF files.
@item
Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
printing DVI files at your site. For example, if you have a PostScript
printer, run the @code{dvips} program to print the DVI file on that
printer.
@end enumerate
To get more general instructions, retrieve the latest Texinfo package
(@pxref{Installing Texinfo documentation}).
@node Viewing Info files outside of Emacs
@section Can I view Info files without using Emacs?
@cindex Viewing Info files
@cindex Info file viewers
@cindex Alternative Info file viewers
Yes. Here are some alternative programs:
@itemize @bullet
@item
@code{info}, a stand-alone version of the Info program, comes as part of
the Texinfo package. @xref{Installing Texinfo documentation}, for
details.
@item
Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
You can get Tkinfo at
@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
@end itemize
@node Informational files for Emacs
@section What informational files are available for Emacs?
@cindex Informational files included with Emacs
@cindex Files included with Emacs
@cindex @file{COPYING}, description of file
@cindex @file{DISTRIB}, description of file
@cindex @file{GNU}, description of file
@cindex @file{INTERVIEW}, description of file
@cindex @file{MACHINES}, description of file
@cindex @file{MAILINGLISTS}, description of file
@cindex @file{NEWS}, description of file
This isn't a frequently asked question, but it should be! A variety of
informational files about Emacs and relevant aspects of the GNU project
are available for you to read.
The following files (and others) are available in the @file{etc}
directory of the Emacs distribution (see @ref{File-name conventions}, if
you're not sure where that is). Many of these files are available via
the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} (@kbd{M-x
help-for-help}).
@table @file
@item COPYING
GNU General Public License
@item DISTRIB
Emacs Availability Information
@item GNU
The GNU Manifesto
@item INTERVIEW
Richard Stallman discusses his public-domain UNIX-compatible software
system with BYTE editors
@item MACHINES
Status of Emacs on Various Machines and Systems
@item MAILINGLISTS
GNU Project Electronic Mailing Lists
@item NEWS
Emacs news, a history of recent user-visible changes
@end table
More GNU information, including back issues of the @cite{GNU's
Bulletin}, are at
@uref{http://www.gnu.org/bulletins/bulletins.html} and
@uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
@node Help installing Emacs
@section Where can I get help in installing Emacs?
@cindex Installation help
@cindex Help installing Emacs
@xref{Installing Emacs}, for some basic installation hints, and see
@ref{Problems building Emacs}, if you have problems with the installation.
@uref{http://www.fsf.org/resources/service/, The GNU Service directory}
lists companies and individuals willing to sell you help in installing
or using Emacs and other GNU software.
@node Obtaining the FAQ
@section Where can I get the latest version of this FAQ?
@cindex FAQ, obtaining the
@cindex Latest FAQ version, obtaining the
The Emacs FAQ is distributed with Emacs in Info format. You can read it
by selecting the @samp{Emacs FAQ} option from the @samp{Help} menu of
the Emacs menu bar at the top of any Emacs frame, or by typing @kbd{C-h
C-f} (@kbd{M-x view-emacs-FAQ}). The very latest version is available
in the Emacs development repository (@pxref{Latest version of Emacs}).
@c ------------------------------------------------------------
@node Status of Emacs
@chapter Status of Emacs
@cindex Status of Emacs
This chapter gives you basic information about Emacs, including the
status of its latest version.
@menu
* Origin of the term Emacs::
* Latest version of Emacs::
* New in Emacs 23::
* New in Emacs 22::
* New in Emacs 21::
* New in Emacs 20::
@end menu
@node Origin of the term Emacs
@section Where does the name ``Emacs'' come from?
@cindex Origin of the term ``Emacs''
@cindex Emacs name origin
@cindex TECO
@cindex Original version of Emacs
Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
the name Emacs because @key{E} was not in use as an abbreviation on ITS at
the time.'' The first Emacs was a set of macros written in 1976 at MIT
by RMS for the editor TECO (Text Editor and COrrector, originally Tape
Editor and COrrector) under ITS (the Incompatible Timesharing System) on
a PDP-10. RMS had already extended TECO with a ``real-time''
full-screen mode with reprogrammable keys. Emacs was started by
@email{gls@@east.sun.com, Guy Steele} as a project to unify the many
divergent TECO command sets and key bindings at MIT, and completed by
RMS.
Many people have said that TECO code looks a lot like line noise; you
can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
implementation in Emacs Lisp (to find it, see @ref{Packages that do not
come with Emacs}); it would be an interesting project to run the
original TECO Emacs inside of Emacs.
@cindex Why Emacs?