summaryrefslogtreecommitdiff
path: root/etc/OTHER.EMACSES
blob: 13b27bf2793ad5daf2dcf0d535daa15ee7c9a473 (plain)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
How is this Emacs different from all other Emacses?  -*-Outline-*-

This file describes the differences between GNU Emacs 19, Twenex
Emacs, Gosling Emacs (including the commercial versions by Unipress)
and CCA Emacs.

* Copyright (c) 1985 Richard M. Stallman

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and permission notice are preserved,
   and that the distributor grants the recipient permission
   for further redistribution as permitted by this notice.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

Updated March 1993 for Emacs 19 by Eric S. Raymond


* How is this Emacs different from Twenex Emacs?

** Fundamental concepts.

*** There is no concept of "typeout" in GNU Emacs.

Any time that a command wants to display some output,
it creates a buffer (usually with a name surrounded by asterisks)
and displays it in a window.

This provides some advantages:
 you can edit some more while looking at the output;
 you can copy parts of the output into other buffers.

It also has a disadvantage that you must type a command
in order to make the output disappear.
You can use C-x 1 to get rid of all windows except the
selected one.  To be more selective, you can switch to
the window you want to get rid of and then type C-x 0
(delete-window).

You also need to type a command to scroll the other
window if not all the output fits in it.  Meta-Control-v
will usually do the job.

*** There is no concept of a "subsystem" in GNU Emacs.

Where Twenex Emacs would use a subsystem, GNU Emacs
instead creates a buffer and redefines commands in it.

For example, when you send mail in GNU Emacs, you use
a buffer named *mail* which is in Mail Mode.  You can
switch away from this buffer to any other buffer and
resume normal editing; then switch back and resume
composing mail.  You do not have to "exit" from
composing mail in order to do ordinary editing.

This has many advantages, but it also has a disadvantage:
Subsystems in Emacs tend to have "exit" commands that return you
to whatever you were doing before entering the subsystem.
In GNU Emacs the idea of what to return to is not well defined,
so it is not clear what an "exit" command should do.
The only way to "exit" in general is to type C-x b, C-x C-f, or
some other suitable command to switch buffers.  Some
subsystem-like major modes, such as Info and Mail mode, provide
commands to "exit" by switching to the previously selected
buffer.

*** Files are always visited in their own buffers.

Beginning users of Twenex Emacs were told how to edit
using a single buffer and reading one file after another
into that buffer.  Use of a new buffer for each file was
regarded as a more advanced mode.

In GNU Emacs, the idea of using a single buffer for various
files, one by one, has been dropped, given that the address
space is expected to be large enough for many buffers.  C-x
C-f (find-file), which behaves nearly the same as in Twenex
Emacs, is in GNU Emacs the canonical way for all users to
visit files.

Various commands need to read files into Emacs in the course
of their execution.  In Twenex Emacs the user must tell them
whether to reuse buffers or create new ones, using the variable
Tags Find File.  In GNU Emacs, these commands always use
C-x C-f.

The command C-x C-v does still exist; it kills the current
buffer and reads the specified file into a new buffer.
It is equivalent to kill-buffer followed by find-file.

Since there is no reusing of buffers, there is no point in
calling the initial buffer "main".  So the initial buffer
in GNU Emacs is called "*scratch*" and is intended for typing
Lisp expressions to be evaluated.

*** File name defaulting.

GNU Emacs records a separate working directory for each buffer.
Normally this is the directory on which the buffer's file
resides; for buffers not visiting any file, it is copied from
the buffer that was current when it was created.  The current buffer's
working directory can be printed with M-x pwd and set with M-x cd.

GNU Emacs shows you the default directory by inserting it in
the minibuffer when a file name is being read.  You can type
the filename you want at the end of the default as if the
default were not there, or you can edit and alter the default.

If you want file /lose/big when the default /foo/defaultdir/
has been inserted for you, you need not kill the default; simply
type at the end of it: /foo/defaultdir//lose/big.  Such a file
name is not ordinarily considered valid, but GNU Emacs
considers it equivalent to /lose/big.

Likewise, if you want file quux in your home directory, just add
~/quux to the end of the supplied text, to get
/foo/defaultdir/~/quux.  GNU Emacs sees "/~" and throws away
everything before the "~".

You can refer to environment variables also within file names.
$ followed by the environment variable name is replaced by the
variable's value.  The variable name should either be followed
by a nonalphanumeric character (which counts as part of the
file name) or be surrounded by braces {...} (which do not count
as part of the file name).  Thus, if variable USER has value "rms",
"x/$USER-foo" is expanded to "x/rms-foo", and "x${USER}foo"
is expanded to "xrmsfoo".  Note that this substitution is not
performed by the primitive file operation functions of GNU Emacs,
but rather by the interactive file name reader.  It is also
available as a separate primitive, in the function
substitute-in-file-name.

*** Exit commands C-z, C-x C-c and C-x C-z.

There are two ways to exit GNU Emacs: killing and suspending.
Killing is like what Control-c does to ordinary Unix programs.
In GNU Emacs, you type C-x C-c to kill it.  (This offers to
save any modified file buffers before really killing Emacs.)
Suspending is like what Control-z does to ordinary Unix programs.
To suspend GNU Emacs, type C-x C-z, or type just C-z.
Note that C-z suspends ordinary programs instantly, but
Emacs does not suspend until it reads the C-z.

Usually it is better to suspend: once a system is smart
enough to have job control, why ever kill an editor?
You'll just have to make a new one in a minute.
This is why the convenient command C-z is provided for
suspending.

C-c is used as a prefix key for mode-specific commands and for users'
own commands.  We deliberately do not make C-c ever kill Emacs,
because it should not be so easy to do something irreversible.

*** Quitting with C-g.

If you type C-g while GNU Emacs is waiting for input, it
is an ordinary command (which is defined to beep).  If you
type C-g while Lisp code is executing, it sets a flag which
causes a special signal, nearly the same as an error, to
happen at the next safe place in Lisp execution.  This usually
has the effect of aborting the current command in a safe way.

Because at times there have been bugs causing GNU Emacs to loop
without checking the quit flag, a special feature causes
GNU Emacs to be suspended immediately if you type a second C-g
while the flag is already set.  So you can always get out
of GNU Emacs.  Normally GNU Emacs recognizes and clears the quit flag
quickly enough to prevent this from happening.

When you resume GNU Emacs after a suspension caused by multiple C-g, it
asks two questions before resuming execution:
 Checkpoint?
 Dump core?
Answer each one with `y' or `n' and a Return.
 `y' to Checkpoint? causes immediate auto-saving of all
    buffers in which auto-saving is enabled.
 `y' to Dump core? causes an illegal instruction to be executed.
    This is to enable a wizard to figure out why GNU Emacs was
    looping without checking for quits.  Execution does not continue
    after a core dump.  If you answer `n', execution continues.
With luck, GNU Emacs will ultimately check the quit flag,
and quit normally.  If not, and you type another C-g, it
is suspended again.

If GNU Emacs is not really hung, just slow, you may invoke
the double C-g feature without really meaning to.  Then just
resume and answer `n' to both questions, and you will
arrive at your former state.  Presumably the quit you
wanted will finish happening soon.

These questions are not asked if you suspend GNU Emacs with the C-z
command.  Continuing GNU Emacs after a C-z takes you straight back
into editing.

*** Undoing with C-x u or C-_

You can undo many commands--up to 10,000 characters worth.
Each time you type C-x u or C-_, another command or batch of change
is undone.  Undo information is stored per buffer, and the undo
command always applies to the current buffer.  A numeric argument
serves as a repeat count.

Consecutive self-inserting characters are undone in groups of twenty.

*** Different character set.

GNU Emacs does not expect anyone ever to have a keyboard in which
the Control key sets an independent bit which may accompany any
character. The only control characters that can exist are the
ASCII control characters.

There is, as a result, no "control prefix" character.

*** Control-h is the Help character.

I'm amazed it took me so long to get this idea.  In Twenex Emacs, C-h
and C-b are equivalent commands, making C-h redundant.  C-h is not
only easy to type, it is mnemonic for "Help".  So in GNU Emacs the
Help character is C-h.

*** Completion is done by TAB, not ESC.

ESC in the minibuffer is a Meta prefix, same as at top level.

*** The string-argument reader is the minibuffer is an editor window.

In GNU Emacs, the line at the bottom of the screen is the minibuffer.
Commands that want string arguments always use this line to read them,
and you can use the ordinary Emacs editing commands to edit the
input.  You can terminate input with Return because Return is defined
as the exit-minibuffer command when in the minibuffer.  If you
are using a command that needs several arguments, terminate each
one with Return.  You cannot separate arguments with Escape
the way you would in Twenex Emacs.

The minibuffer window does not overlay other editor windows;
it is a nearly ordinary editor window which lacks a mode line
and is "turned off" when not in use.  While it IS in use, you
can switch windows to and from the minibuffer, kill text in other
windows and yank in the minibuffer, etc.

You can even issue a command that uses the minibuffer while in the
minibuffer.  This gets you temporarily into a recursive minibuffer.
However, this is allowed only if you enable it, since it could be
confusing for beginners.

When you exit the minibuffer, the cursor immediately moves back to
column zero of the minibuffer line, to show you that the exit
command has been obeyed.  The minibuffer contents remain on the screen
until the end of the command, unless some other text is displayed there.

A single Control-g exits the minibuffer.

*** There are no &'s or ^R's or spaces in function names.

For example, the function which is called ^R Forward Word
in Twenex Emacs is called forward-word in GNU Emacs.

*** The extension language is Lisp rather than TECO.

Libraries must be written in Lisp.  Meta-ESC reads a Lisp
expression, evaluates it, and prints the result.  Note that
Meta-ESC is "disabled" by default, so that beginning users
do not get into the minibuffer by accident in a confusing way.

Data types available include integers (which double as characters),
strings, symbols, lists, vectors, buffers, buffer pointers,
windows, and process channels.

For now, to learn about writing Lisp code for GNU Emacs, read some of
the source code, which is in directory ../lisp.  Read the GNU Emacs Lisp
Reference Manual.  Also, all Lisp primitives have self-documentation you can
read with C-h f.

*** Enabling the error handler.

GNU Emacs has a Lisp debugger/stepper/trace package, but normally
errors do not enter the debugger because that is slow, and unlikely to
be of interest to most users.  Set the variable debug-on-error to t to
cause errors to invoke the debugger.  Set debug-on-quit to cause quit
signals (caused by C-g) to invoke the debugger.

** Other changes.

*** More than two windows are allowed.

C-x 2 splits the current window into two windows,
  one above the other.  Initially they both display
  the same buffer.

  C-x 2 now accepts a numeric argument to specify the number of
  lines to give to the uppermost of the two windows it makes.

C-x 0 kills the current window, making all others larger.
C-x 1 kills all windows except the current one.
C-x O switches to the next window down.
  It rotates from the bottom one to the top one.
  An argument serves as a repeat count; negative arguments
  circulate in the reverse order.

If the same buffer is displayed in several windows,
changes made in it are redisplayed in all of them.

*** Side by side windows are supported.

The command C-x 3 splits the current window into
two side-by-side windows.

C-x } makes the selected window ARG columns wider at the
expense of the windows at its sides.  C-x { makes the selected
window ARG columns narrower.  An argument to C-x 5 specifies
how many columns to give to the leftmost of the two windows made.

*** Horizontal scrolling of the lines in a window is implemented.

C-x < (scroll-left) scrolls all displayed lines left,
with the numeric argument (default 1) saying how far to scroll.
When the window is scrolled left, some amount of the beginning
of each nonempty line is replaced by an "$".
C-x > scrolls right.  If a window has no text hidden at the left
margin, it cannot be scrolled any farther right than that.
When nonzero leftwards scrolling is in effect in a window.
lines are automatically truncated at the window's right margin
regardless of the value of the variable truncate-lines in the
buffer being displayed.

*** Return key does not use up empty lines.

In Twenex Emacs, the Return command advances over an existing
empty line in some cases.  In GNU Emacs, the Return command always
makes inserts a newline.  Twenex Emacs was designed at a time when
most display terminals did not have the ability to scroll part
of the screen, and using existing empty lines made redisplay faster.
Nowadays, terminals that cannot scroll part of the screen are rare,
so there is no need to make Return behave in a more complicated manner.

*** Help m.

Typing C-h m displays documentation of the current major mode.,
telling you what special commands and features are available
and how to use them or get more information on them.

This is simply the documentation, as a function, of the
symbol which is the value of major-mode.  Each major mode
function has been given documentation intended for C-h m.

*** Display-hiding features.

**** Hiding indented lines

The command C-x $ with numeric argument N causes lines indented by N
or more columns to become invisible.  All you see is " ..."  appended
to the previous line, in place of any number of consecutive invisible
lines.

**** Outline Mode.

Outline mode is designed for editing outline-structured
files, such as this one.

Headings should be lines starting with one or more asterisks.
Major headings have one asterisk, subheadings two, etc.
Lines not starting with asterisks are body text.

You can make the body under a heading, or the subheadings
under a heading, temporarily invisible, or visible again.
Invisible lines are attached to the end of the previous line
so they go with it if you kill it and yank it back.

Commands:
Meta-}   next-visible-heading      move by visible headings
Meta-{   previous-visible-heading  move by visible headings

Meta-x hide-body	make all body text invisible (not headings).
Meta-x show-all		make everything in buffer visible.

The remaining commands are used when dot is on a heading line.
They apply to some of the body or subheadings of that heading.
C-c C-h  hide-subtree	make text and subheadings invisible.
C-c C-s  show-subtree	make text and subheadings visible.
C-c C-i  show-children	make direct subheadings visible.
		 No effect on body, or subheadings 2 or more levels down.
		 With arg N, affects subheadings N levels down.
M-x hide-entry	make immediately following body invisible.
M-x show-entry	make it visible.
M-x hide-leaves	 make text under heading and under its subheadings invisible.
		 The subheadings remain visible.
M-x show-branches  make all subheadings at all levels visible.

*** C mode is fancy.

C mode assumes that you put the initial open-brace of
a function definition at the beginning of a line.
If you use the popular indenting style that puts this
open-brace at the end of a line containing a type declaration,
YOU WILL LOSE: C mode does not know a function starts there.

Open-brace at the beginning of a line makes it possible
for C mode to find function boundaries with total reliability;
something I consider vital and which cannot be done
if the other style is used.

The Tab command indents C code very cleverly.
I know of only one cases in which Tab does not indent C code nicely:
 Expressions continued over several lines with few parentheses.
 Tab does not know the precedences of C operators, so it does
 not know which lines of the expression should go where.
 Using parentheses to indicate the nesting of operators
 except within a line makes this problem go away.

The indenting algorithm is entirely written in Lisp.

Tab with a numeric argument in Twenex Emacs indents
that many lines.  It is different in GNU Emacs: it means
to shift all the lines of a bracketed expression by the
same amount as the line being indented.  For example, if you have
    if (foo)
        {
	    hack ();
	     /** Well? */
	}
and type C-u Tab on the line with the open brace, you get
    if (foo)
      {
	  hack ();
	   /* Well? */
      }
from indenting the brace line and then shifting the
lines within the braces rigidly with the first one.

Meta-Control-q works as in Lisp mode; it should be
used with dot just before a bracketed grouping, and
indents each line INSIDE that grouping using Tab.
If used instead of C-u Tab in the previous example, it makes
    if (foo)
        {
	  hack ();
	  /* Well? */
	}

Meta-Control-h puts mark at the end of the current C function
and puts dot before it.

Most other Meta-Control commands intended for Lisp expressions
work usefully in C mode as well.

*** Meta-g (fill-region) is different.

In Twenex Emacs, Meta-g fills the region with no paragraph
boundaries except for blank and indented lines.  In GNU Emacs,
it divides the region into paragraphs in the same manner as
Meta-], and fills each paragraph separately.  There is also
the function fill-region-as-paragraph which fills the region
regarding at as a single paragraph regardless even of blank
or indented lines.

*** Indented Text Mode instead of Edit Indented Text.

Twenex Emacs has a command Edit Indented Text which temporarily
alters some commands for editing indented paragraphs.
GNU Emacs has instead a separate major mode, Indented Text Mode,
which is different from ordinary Text Mode in just the same
alterations.  Specifically, in Indented Text Mode,
Tab runs the function indent-relative, and auto filling indents
the newly created lines.

*** But rectangle commands are implemented.

C-x r r stores the rectangle described by dot and mark
into a register; it reads the register name from the keyboard.
C-x r g, the command to insert the contents of a register,
can be used to reinsert the rectangle elsewhere.

Other rectangle commands include
  open-rectangle:
    insert a blank rectangle in the position and size
    described by dot and mark, at its corners;
    the existing text is pushed to the right.
  clear-rectangle:
    replace the rectangle described by dot ane mark
    with blanks.  The previous text is deleted.
  delete-rectangle:
    delete the text of the specified rectangle,
    moving the text beyond it on each line leftward.
  kill-rectangle
    like delete-rectangle but also stores the text of
    the rectangle in the "rectangle kill buffer".
    More precisely, it stores the text as a list of strings
    (one string for each line) in the variable killed-rectangle.
  yank-rectangle
    inserts the text of the last killed rectangle.
  extract-rectangle and delete-extract-rectangle
    these functions return the text of a rectangle
    as a list of strings.  They are for use in writing
    other functions that operate on rectangles.   

*** Keyboard Macros

The C-x ( command for defining a keyboard macro can in GNU Emacs
be given a numeric argument, which means that the new macro
starts out not empty but rather as the same as the last
keyboard macro entered.  In addition, that last keyboard
macro is replayed when the C-x ( is typed.  C-x ( with an
argument is thus equivalent to typing plain C-x ( and then
retyping the last keyboard macro entered.

The command write-kbd-macro and append-kbd-macro can be used to
save a keyboard macro definition in a file.  It is represented as
a Lisp expression which, when evaluated, will define the keyboard
macro.  write-kbd-macro writes the specified file from scratch,
whereas append-kbd-macro adds to any existing text in the file.
Both expect the keyboard macro to be saved to be specified by
name; this means you must use the command name-last-kbd-macro to
give the macro a name before you can save it.

*** The command to resume a terminated tags-search or tags-query-replace

is Meta-comma in GNU Emacs.

*** Auto Save is on by default.

Auto Save mode is enabled by default in all buffers
that are visiting files.

The file name used for auto saving is made by prepending
"#" to the file name visited.

*** Backup files.

Since Unix stupidly fails to have file version numbers,
GNU Emacs compensates slightly in the customary fashion:
when a file is modified and saved for the first time in
a particular GNU Emacs run, the original file is renamed,
appending "~" to its name.  Thus, foo.c becomes foo.c~.

Emacs can also put a version number into the name of the backup file,
as in foo.c.~69~ for version number 69.  This is an optional feature
that the user has to enable.

*** Mode Line differences.

Each window in GNU Emacs has its own mode line, which always
displays the status of that window's buffer and nothing else.
The mode line appears at the bottom of the window.  It is
full of dashes, to emphasize the boundaries between windows,
and is displayed in inverse video if the terminal supports it.
The information usually available includes:

*** Local Modes feature changed slightly.

GNU Emacs supports local mode lists much like those in Twenex Emacs,
but you can only set variables, not commands.  You write

Local variables:
tab-width:      10
end:

in the last page of a file, if you want to make tab-width be ten in a
file's buffer.  The value you specify must be a Lisp object!
It will be read, but not evaluated.  So, to specify a string,
you MUST use doublequotes.  For "false", in variables whose
meanings are true or false, you MUST write  nil  .

Two variable names are special: "mode" and "eval".
Mode is used for specifying the major mode (as in Twenex Emacs).

mode: text

specifies text mode.  Eval is used for requesting the evaluation
of a Lisp expression; its value is ignored.  Thus,

eval: (set-syntax-table lisp-mode-syntax-table)

causes Lisp Mode syntax to be used.


Note that GNU Emacs looks for the string "Local variables:"
whereas Twenex Emacs looks for "Local modes:".  This incompatibility
id deliberate, so that neither one will see local settings
intended for the other.

*** Lisp code libraries.

Libraries of commands, and init files, are written in Lisp.
libraries conventionally have names ending in .el, while the
init file is named .emacs and is in your home directory.

Use  Meta-x load-library  to load a library.  Most standard libraries
load automatically if you try to use the commands in them.

Meta-x byte-compile-file filename
compiles the file into byte code which loads and runs faster
than Lisp source code.  The file of byte code is given a name
made by appending "c" to the end of the input file name.

Meta-x byte-recompile-directory directoryname
compiles all files in the specified directory (globbing not allowed)
which have been compiled before but have been changed since then.

Meta-x load-library automatically checks for a compiled file
before loading the source file.

Libraries once loaded do not retain their identity within GNU
Emacs.  Therefore, you cannot tell just what was loaded from a
library, and you cannot un-load a library.  Normally, libraries
are written so that loading one has no effect on the editing
operations that you would have used if you had not loaded the
library.

*** Dired features.

You can do dired on partial directories --- any pattern
the shell can glob.  Dired creates a buffer named after
the directory or pattern, so you can dired several different
directories.  If you repeat dired on the same directory or
pattern, it just reselects the same buffer.  Use Meta-x Revert
on that buffer to read in the current contents of the directory.

*** Directory listing features.

C-x C-d now uses the default output format of `ls',
which gives just file names in multiple columns.
C-u C-x C-d passes the -l switch to `ls'.

Both read a directory spec from the minibuffer.  It can
be any pattern that the shell can glob.

*** Compiling other programs.

Meta-x compile allows you to run make, or any other compilation
command, underneath GNU Emacs.  Error messages go into a buffer whose
name is *compilation*.  If you get error messages, you can use the
command C-x ` (that is a backquote) to find the text of the next
error message.

You must specify the command to be run as an argument to M-x compile.
A default is placed in the minibuffer; you can kill it and start
fresh, edit it, or just type Return if it is what you want.
The default is the last compilation command you used; initially,
it is "make -k".

*** Searching multiple files.

Meta-x grep searches many files for a regexp by invoking grep
and reading the output of grep into a buffer.  You can then
move to the text lines that grep found, using the C-x ` command
just as after M-x compile.

*** Running inferior shells.

Do Meta-x shell to make an inferior shell together with a buffer
which serves to hold "terminal" input and output of the shell.
The shell used is specified by the environment variable ESHELL,
or by SHELL if ESHELL is not set.

Use C-h m whilst in the *shell* buffer to get more detailed info.

The inferior shell loads the file .emacs_csh or.emacs_sh
(or similar using whatever name the shell has) when it starts up.

M-! executes a shell command in an inferior shell
and displays the output from it.  With a prefix argument,
it inserts the output in the current buffer after dot
and sets the mark after the output.  The shell command
gets /dev/null as its standard input.

M-| is like M-! but passes the contents of the region
as input to the shell command.  A prefix argument makes
the output from the command replace the contents of the region.

*** Sending mail.

Once you enter Mail Mode using C-x m or C-x 4 m or M-x mail,
C-c becomes a prefix character for mail-related editing commands.
C-c C-s is vital; that's how you send the message.  C-c C-c sends
and then switches buffers or kills the current window.
Use C-h m to get a list of the others.

*** Regular expressions.

GNU Emacs has regular expression facilities like those of most
Unix editors, but more powerful:

****		-- + --

+ specifies repetition of the preceding expression 1 or more
times.  It is in other respect like *, which specifies repetition
0 or more times.

****		-- ? --

?  is like * but matches at most one repetition of the preceding
expression.

****		-- \| --

\| specifies an alternative.  Two regular expressions A and B with \| in
between form an expression that matches anything that either A or B will
match.  Thus, "foo\|bar" matches either "foo" or "bar" but no other
string.

\| applies to the larges possible surrounding expressions.  Only a
surrounding \( ... \) grouping can limit the grouping power of \|.

Full backtracking capability exists when multiple \|'s are used.

****		-- \( ... \) --

\( ... \) are a grouping construct that serves three purposes:

1.  To enclose a set of \| alternatives for other operations.
    Thus, "\(foo\|bar\)x" matches either "foox" or "barx".
2.  To enclose a complicated expression for * to operate on.
    Thus, "ba\(na\)*" matches "bananana", etc., with any number
    of na's (zero or more).
3.  To mark a matched substring for future reference.

Application 3 is not a consequence of the idea of a parenthetical
grouping; it is a separate feature which happens to be assigned as a
second meaning to the same \( ... \) construct because there is no
conflict in practice between the two meanings.  Here is an explanation
of this feature.

		-- \digit --

After the end of a \( ... \) construct, the matcher remembers the
beginning and end of the text matched by that construct.  Then, later on
in the regular expression, you can use \ followed by a digit to mean,
``match the same text matched this time by the \( ... \) construct.''
The first nine \( ... \) constructs that appear in a regular expression
are assigned numbers 1 through 9 in order of their beginnings.  \1
through \9 can be used to refer to the text matched by the corresponding
\( ... \) construct.

For example, "\(.*\)\1" matches any string that is composed of two
identical halves.  The "\(.*\)" matches the first half, which can be
anything, but the \1 that follows must match the same exact text.

****		-- \` --

Matches the empty string, but only if it is at the beginning of the buffer.

****		-- \' --

Matches the empty string, but only if it is at the end of the buffer.

****		-- \b --

Matches the empty string, but only if it is at the beginning or end of
a word.  Thus, "\bfoo\b" matches any occurrence of "foo" as a separate word.
"\bball\(s\|\)\b" matches "ball" or "balls" as a separate word.

****		-- \B --

Matches the empty string, provided it is NOT at the beginning or end of
a word.

****		-- \< --

Matches the empty string, provided it is at the beginning of a word.

****		-- \> --

Matches the empty string, provided it is at the end of a word.

****		-- \w --

Matches any word-constituent character.  The editor syntax table determines
which characters these are.

****		-- \W --

Matches any character that is not a word-constituent.

****		-- \s<code> --

Matches any character whose syntax is <code>.  <code> is a letter that
represents a syntax code: thus, "w" for word constituent, "-" for
whitespace, "(" for open-parenthesis, etc.  Thus, "\s(" matches any
character with open-parenthesis syntax.

****		-- \S<code> --

Matches any character whose syntax is not <code>.

* How is this Emacs different from Gosling Emacs?

** Advantages of Gosling Emacs:

1. The program itself is much smaller.
GNU Emacs uses about 250k more pure storage.
As a result, Gosling Emacs can run on machines
that cannot run GNU Emacs.  There is not much difference
in the amount of impure storage in the two programs.

2. In some versions there is support for other forks to
establish communications channels to Emacs (using sockets?).

3. There is a direct interface to dbm (data bases).

** Advantages of GNU Emacs:

*** True Lisp, not Mocklisp.

GNU Emacs's extension language has real symbols, lists
and vectors.  Many extensions are much simpler, and some
become possible that were nearly impossible in Gosling Emacs.
Many primitives can have cleaner interfaces, and some features
need not be put in as special primitives because you can do
them easily yourself.

*** But Mocklisp still works.

An automatic conversion package plus a run-time library
allows you to convert a Mocklisp library into a Lisp library.

*** Commands are better crafted.

For example, nearly every editing function for which a
numeric argument would make sense as a repeat count does
accept a repeat count, and does handle a negative argument
in the way you would expect.

*** The manual is clearer.

Everyone tells me it is a very good manual.

*** Better on-line documentation.

Both functions and variables have documentation strings that
describe exactly how to use them.

*** C mode is smart.

It really knows how to indent each line correctly,
for most popular indentation styles.  (Some variables
control which style is used; popular named styles are also supported.)

*** Compatible with PDP-10 Emacs, Multics Emacs and Zmacs.

The commands in GNU Emacs are nearly the same as in the
original Emacs and the other Emacses which imitated it.
(A few have been changed to fit the Unix environment better.)

*** Support for Gosling's Emacs commands.

M-x set-gosmacs-bindings rebinds many editing commands for
compatibility with Gosling's Emacs.
M-x set-gnu-bindings reverses the change.

*** Side-by-side windows.

You can split a GNU Emacs window either horizontally or
vertically.

*** Redisplay is faster.

GNU Emacs sends about the same stuff to the terminal that
Gosling's does, but GNU Emacs uses much less CPU time to
decide what to do.

*** Entirely termcap-driven.

GNU Emacs has nearly no special code for any terminal type.  Various
new termcap strings make it possible to handle all terminals nearly as
fast as they could be handled by special-case code.

*** Display-hiding features.

For example, Outline Mode makes it possible for you to edit
an outline, making entire sub-branches of the outline visible
or invisible when you wish.

*** You can interrupt with Control-G.

Even a looping Lisp program can be stopped this way.
And even a loop in C code does not stop you from killing
Emacs and getting back to your shell.

*** Per-buffer Undo.

You can undo the last several changes, in each buffer
independently.

*** The editor code itself is clean.

Many people have remarked on how much they enjoy reading
the code for GNU Emacs.

One other note: The program etc/cvtmail that comes with GNU Emacs can
be used to convert a mail directory for Gosling Emacs's Rmail into a
Unix mail file that you could read into GNU Emacs's Rmail.

* How is this Emacs different from CCA Emacs?

** GNU Emacs Lisp vs CCA Elisp.

GNU Emacs Lisp does not have a distinction between Lisp functions
and Emacs functions, or between Lisp variables and Emacs variables.
The Lisp and the editor are integrated.  A Lisp function defined
with defun is callable as an editor command if you put an
interactive calling spec in it; for example, 
  (defun forward-character (n)
    (interactive "p")
    (goto-char (+ (point) n)))
defines a function of one argument that moves point forward by
a specified number of characters.  Programs could call this function,
as in (forward-character 6), or it could be assigned to a key,
in which case the "p" says to pass the prefix numeric arg as
the function's argument.  As a result of this feature, you often
need not have two different functions, one to be called by programs
and another to read arguments from the user conveniently; the same
function can do both.

CCA Elisp tries to be a subset of Common Lisp and tries to
have as many Common Lisp functions as possible (though it is still
only a small fraction of full Common Lisp).  GNU Emacs Lisp
is somewhat similar to Common Lisp just because of my Maclisp
and Lisp Machine background, but it has several distinct incompatibilities
in both syntax and semantics.  Also, I have not attempted to
provide many Common Lisp functions that you could write in Lisp,
or others that provide no new capability in the circumstances.

GNU Emacs Lisp does not have packages, readtables, or character objects
(it uses integers to represent characters).

On the other hand, windows, buffers, relocatable markers and processes
are first class objects in GNU Emacs Lisp.  You can get information about them
and do things to them in a Lispy fashion.  Not so in CCA Emacs.

In GNU Emacs Lisp, you cannot open a file and read or write characters
or Lisp objects from it.  This feature is painful to support, and
is not fundamentally necessary in an Emacs, because instead you
can read the file into a buffer, read or write characters or
Lisp objects in the buffer, and then write the buffer into the file.

On the other hand, GNU Emacs Lisp does allow you to rename, delete, add
names to, and copy files; also to find out whether a file is a
directory, whether it is a symbolic link and to what name, whether
you can read it or write it, find out its directory component,
expand a relative pathname, find completions of a file name, etc.,
which you cannot do in CCA Elisp.

GNU Emacs Lisp uses dynamic scope exclusively.  This enables you to
bind variables which affect the execution of the editor, such as
indent-tabs-mode.

GNU Emacs Lisp code is normally compiled into byte code.  Most of the
standard editing commands are written in Lisp, and many are
dumped, pure, in the Emacs that users normally run.

GNU Emacs allows you to interrupt a runaway Lisp program with
Control-g.

** GNU Emacs Editing Advantages

GNU Emacs is faster for many things, especially insertion of text
and file I/O.

GNU Emacs allows you to undo more than just the last command
with the undo command (C-x u, or C-_).  You can undo quite a ways back.
Undo information is separate for each buffer; changes in one buffer
do not affect your ability to undo in another buffer.

GNU Emacs commands that want to display some output do so by putting
it in a buffer and displaying that buffer in a window.  This
technique comes from Gosling Emacs.  It has both advantages and
disadvantages when compared with the technique, copied by CCA Emacs
from my original Emacs which inherited it from TECO, of having "type
out" which appears on top of the text in the current window but
disappears automatically at the next input character.

GNU Emacs does not use the concept of "subsystems".  Instead, it uses
highly specialized major modes.  For example, dired in GNU Emacs has
the same commands as dired does in other versions of Emacs, give or
take a few, but it is a major mode, not a subsystem.  The advantage
of this is that you do not have to "exit" from dired and lose the
state of dired in order to edit files again.  You can simply switch
to another buffer, and switch back to the dired buffer later.  You
can also have several dired buffers, looking at different directories.

It is still possible to write a subsystem--your own command loop--
in GNU Emacs, but it is not recommended, since writing a major mode
for a special buffer is better.

Recursive edits are also rarely used, for the same reason: it is better
to make a new buffer and put it in a special major mode.  Sending
mail is done this way.

GNU Emacs expects everyone to use find-file (C-x C-f) for reading
in files; its C-x C-v command kills the current buffer and then finds
the specified file.

As a result, users do not need to think about the complexities
of subsystems, recursive edits, and various ways to read in files
or what to do if a buffer contains changes to some other file.

GNU Emacs uses its own format of tag table, made by the "etags"
program.  This format makes finding a tag much faster.

Dissociated Press is supported.


** GNU Emacs Editing Disadvantages.

GNU Emacs does not display the location of the mark.

GNU Emacs does not have a concept of numbers of buffers,
or a permanent ordering of buffers, or searching through multiple
buffers.  The tags-search command provides a way to search
through several buffers automatically.

GNU Emacs does not provide commands to visit files without
setting the buffer's default directory.  Users can write such
commands in Lisp by copying the code of the standard file
visiting commands and modifying them.

GNU Emacs does not support "plus options" in the command
arguments or in buffer-selection commands, except for line numbers.

GNU Emacs does not support encryption.  Down with security!

GNU Emacs does not support replaying keystroke files,
and does not normally write keystroke files.


** Neutral Differences

GNU Emacs uses TAB, not ESC, to complete file names, buffer names,
command names, etc.

GNU Emacs uses LFD to terminate searches, instead of
the C-d uses by CCA Emacs.  (Actually, this character is controlled
by a parameter in GNU Emacs.)  C-M-s in GNU Emacs is an interactive
regular expression search, but you can get to a noninteractive
one by typing ESC right after the C-M-s.

In GNU Emacs, C-x s asks, for each modified file buffer, whether
to save it.

GNU Emacs indicates line continuation with "\" and line
truncation (at either margin) with "$".

The command to resume a tags-search or tags-query-replace in
GNU Emacs is Meta-Comma.