-
Notifications
You must be signed in to change notification settings - Fork 6
/
intro.nr
3270 lines (3264 loc) · 136 KB
/
intro.nr
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
.\" ditroff -ms
.\"##########################################################################
.\"# This program is Copyright (C) 1986-2002 by Jonathan Payne. JOVE is #
.\"# provided by Jonathan and Jovehacks without charge and without #
.\"# warranty. You may copy, modify, and/or distribute JOVE, provided that #
.\"# this notice is included in all the source files and documentation. #
.\"##########################################################################
.
.\" intro.nr: the first half of the JOVE manual (not manpage!).
.\"
.\" To produce the whole manual,
.\" tbl intro.nr | [nt]roff -ms - cmds.nr contents.nr
.
.\" In troff, `\` tends to overlap the characters to its left or right. In
.\" this text, therefore, it is usually preceded and followed by '\' (a thin
.\" space, ignored in nroff). Exceptions are where it it adjacent to
.\" whitespace, and the specific cases '\"', '\|', '\1', '\)' and '\}' which
.\" appear better left alone.
.
.de IQ \" italics (here, in manual) or quote (in describe-command)
\&\\fI\\$1\\fP\\$2
..
.de BQ \" bold (here, in manual) or quote (in describe-command)
\&\\fB\\$1\\fP\\$2
..
.de dc
.NH 2
\\$1
.if '\\$2'(variable)' (variable)
.if !'\\$2'(variable)' (\\$2)
.XS \\n(PN 5n
\\*(SN
\\$1
.if '\\$2'(variable)' (variable)
.XE
.LP
..
.de HH
.nr Op \\n(PS
.RT
.ne 4.1
.if \\$1=1 .nr PS +4
.if \\$1=2 .nr PS +2
.NH \\$1
\\$2
.if \\$1=1 .XS
.if \\$1=2 .XS \\n(PN 5n
.if \\$1=3 .XS \\n(PN 10n
.if \\$1=4 .XS \\n(PN 15n
.ps 10
\\*(SN
\\$2
.XE
.nr PS \\n(Op
.ps \\n(PS
..
.
.\" Change the extra vertical spacing around .DS/.DE
.\" Does not work with groff's version of MS (GS is 1 iff groff MS)
.if !\n(GS .if n .nr DD 0v
.if !\n(GS .if t .nr DD \n(PD/2u
.
.nr LL 6.5i
.nr LT 6.5i
.nr Ww (\n(LL-30n-4n)/1n
.EH '%'JOVE User Manual''
.OH ''JOVE User Manual'%'
.TL
JOVE User Manual
.br
Version 4.17
.AU
Jonathan Payne
(with revisions by Doug Kingston, Mark Seiden, D. Hugh Redelmeieir, Mark Moraes and Charles Lindsey)
.AI
.AB no
.AE
.HH 1 "Introduction"
.LP
\s-2JOVE\s0*
.FS
*\s-2JOVE\s0 stands for Jonathan's Own Version of \s-2EMACS\s0.
.FE
is an advanced, self-documenting, customizable, display editor.
It (and this tutorial introduction) are based on the original \s-2EMACS\s0
editor and user manual written at M.I.T. by Richard Stallman\(dg.
.FS
\(dgAlthough \s-2JOVE\s0 is meant to be compatible with \s-2EMACS\s0,
and indeed many of the basic commands are very similar,
there are some major differences between the two editors,
and you should not rely on their behaving identically.
.FE
.LP
\s-2JOVE\s0 is considered a display
editor because normally the text being
edited is visible on the screen and is updated automatically as you
type your commands. What You See Is What You Get.
.KS
.LP
\s-2JOVE\s0 provides many facilities that go beyond
simple insertion and deletion. Some of the more advanced features are:
.DS
cut and paste (or kill and yank in our terminology);
search and replace using regular-expressions;
multiple files, buffers and windows available simultaneously;
filling of text, both on demand and as you type;
manipulation of words, lines, sentences and paragraphs;
automatic indentation of programs;
automatic location of procedure definitions;
executing programs, capturing their output in buffers;
automatic location of spelling and compilation errors;
parenthesis matching.
.DE
.KE
.LP
\s-2JOVE\s0 is self-documenting insofar as you can call up descriptions of
commands, variables and key bindings.
.KS
.LP
\s-2JOVE\s0 is customizable insofar as you can
.DS
change its behavior by changing appropriate variables;
change its behavior by setting appropriate modes;
automatically set the modes for a buffer from its filename;
define macros to perform complex tasks;
change the key bindings to match features of the particular keyboard.
.DE
.KE
All of these options can be exercised by the system administrator, or by the
user at startup, or even in the middle of a job.
.LP
Finally, mouse support
is available (on screens which support the X-Windows package from M.I.T.)
using the front end program \fIxjove\fP
(or alternatively via the mouse-reporting facilities of the terminal emulator
\fIxterm\fP).
.KS
.HH 1 "The Organization of the Screen"
.LP
\s-2JOVE\s0 divides the screen into several sections.
.TS
center;
=
|| L1 || L .
#include <stdio.h>
void main()
{
\ \ \ \ printf("Hello world!\^\e\^n");
\ \ \ \ return 0; <\ the Window
}
_
\fBJOVE\ (C OvrWt)\ \ \ [Main:1]\ \ "hello.c"\ \ \(**\ \ /home/foo\fP <\ the Mode Line
_
: write-file (default hello.c) aloha.c\^\(sq <\ the Message Line
=
.TE
.KE
.HH 2 "The Window"
.LP
The Window section is used to display the text you are editing.
The terminal's cursor shows the position of \fIpoint\fP,
the location at which editing takes place.
While the cursor appears to point \fIat\fP a character,
point should be thought of as between characters;
it points \fIbefore\fP the character that the cursor appears to be on top of.
Terminals have only one cursor,
and when output is in progress it must appear where the typing is being done.
This doesn't mean that point is moving;
it is only that \s-2JOVE\s0 has no way of
showing you the location of point except when the terminal is idle.
In the example, the user is in the middle of issuing a \fIwrite-file\fP
command, so the cursor is at the end of the message line.
.HH 3 "Typeout"
.LP
The lines of the window are usually available for displaying text but
sometimes are pre-empted by typeout from certain commands (such as a
listing of all the buffers).
You can always recognize such \fItypeout\fP because it is terminated by
either an \fB--end--\fP line or a \fB--more--\fP line.
Most of the time,
output from commands like these is only desired for a short period of time,
usually just long enough to glance at it.
When you have finished looking at the output,
you can type Space to make the text reappear
(usually a Space that you type inserts itself, but when there is typeout in
the window, it does nothing but get rid of that).
Any other command executes normally,
.I after
redrawing your text.
.LP
You will see \fB--more--\fP on the line above the last mode line
when typeout from a command is too long to fit on the screen.
It means that if you type a Space the next screenful of typeout will be
printed. If you are not interested, typing ^G will cause the rest of the
output to be discarded. Typing any other key will discard the rest of the
output and that key will be taken as the next keyboard input. Similarly,
\fB--end--\fP signifies that typeout is complete; the same responses are
accepted.
.LP
Sometimes you may wish to keep a permanent record of the typeout from these
commands. To do this, set the variable \fIsend-typeout-to-buffer\fP to
\fIon\fP. The typeout will then be put into a newly-created buffer, which
you can arrange to save to a permanent file.
.HH 2 "The Mode Line"
.LP
The Mode Line gives information about the window above it. There is a
variable \fImode-line\fP which determines the layout of the mode line. For
the example above, this was set as described in the section on customizing
\s-2JOVE\s0.
.LP
\fB(C OvrWt)\fP shows that \fBC\fP is the name of the current \fImajor
mode\fP and that the Over Write \fIminor mode\fP is turned on.
.LP
At any time, \s-2JOVE\s0 can be in only one major mode.
Currently there are four major modes: \fIFundamental\fP,
\fIText\fP, \fILisp\fP and \fIC\fP. New ones may be added in the future.
.KS
.LP
The words which indicate which minor modes are turned on are:
.DS
\fBAbbrev\fP meaning that \fIWord Abbrev\fP mode is on;
\fBAI\fP meaning that \fIAuto Indent\fP mode is on;
\fBFill\fP meaning that \fIAuto Fill\fP mode is on;
\fBOvrWt\fP meaning that \fIOver Write\fP mode is on;
\fBRO\fP meaning that \fIRead Only\fP mode is on.
\fBDBX\fP meaning that \fIDBX\fP mode is on.
\fBDef\fP meaning that you are in the process of defining a keyboard macro.
This is not really a mode, but it's useful to be reminded about it.
.DE
.KE
The meanings of these modes are described later in this document.
.LP
\fB[Main:1]\fP shows that the name of the currently selected \fIbuffer\fP
is \fBMain\fP and its number is \fB1\fP.
Each buffer has its own name and holds a file being edited,
which is how \s-2JOVE\s0 can hold several files at once.
But at any given time you are editing only one of them,
the \fIselected\fP buffer.
When we speak of what some command does to \*Qthe buffer\*U,
we are talking about the currently selected buffer.
Multiple buffers make it easy to switch around between several files,
and then it is very useful that
the mode line tells you which one you are editing at any time.
.LP
\fB"hello.c"\fP shows the name of the file being edited in buffer \fBMain\fP.
This is also the default filename for commands that expect a filename as
input, as can be seen in the message line which follows.
.LP
The \(** in the mode line means that there are changes in
the buffer that have not been saved in the file.
If the buffer had not been changed since it was read in or last saved,
there would be a minus instead.
.LP
Sometimes a file is changed ``behind \s-2JOVE\s0's back'': something
changes the file (not the buffer) after it has been loaded into or
saved from a buffer. This can be quite dangerous, so \s-2JOVE\s0
tests for this when it reads, writes, or finds the file.
\s-2JOVE\s0 indicates the problem by displaying a # before the
change indicator. It also asks for confirmation before performing
the read or write.
.LP
\fB/home/foo\fP shows the name of the current directory.
.LP
\fB15.23\fP shows the time.
.HH 2 "The Message Line"
.LP
The Message Line
is reserved for printing messages and for accepting input from the user,
such as filenames or search strings.
When
\s-2JOVE\s0
prompts for input,
the cursor will temporarily appear on the bottom line, waiting for you
to type a string.
When you have finished typing your input, you can
type a Return to send it to \s-2JOVE\s0.
If you change your mind about running the command that is waiting for input,
you can type ^G to abort,
and you can then continue with your editing.
.LP
The message line and the list of filenames from the shell command that
invoked \s-2JOVE\s0 are kept in a special buffer called
\fIMinibuf\fP that can be edited like any other buffer.
It is instructive to view the Minibuf in a window and to observe how it changes
as parameters to commands are typed, and as the ^N and ^P functions are
invoked.
.HH 2 "Multiple Windows"
.LP
The window area, described above, can in fact be split into several
\fIwindows\fP, each showing a different \fIbuffer\fP, or possibly different
parts of the same buffer. Each window has its own mode line beneath it. The
methods of creating and destroying windows will be described presently.
.HH 1 "Input Conventions"
.LP
.HH 2 "Keyboard Usage"
.LP
In this manual,
\*QControl\*U characters
(that is, characters that are typed with the Control key
and some other key at the same time)
are represented by a circumflex (^) followed by another character.
Thus,
^A is the character you get when you type A with the Control key
(sometimes labeled CTRL) held down.
Control characters in the \s-2JOVE\s0
buffer are displayed with a caret; thus, ^A for Control-A.
DEL is displayed as ^?, ESC as ^[.
.LP
If the keyboard has extra keys, such as Function keys, Arrow keys and the
like, then \s-2JOVE\s0 can be customized to use them.
.HH 2 "The Character Set"
.LP
\s-2JOVE\s0 normally accepts the ASCII character set, with its 95 printing
characters, including Space, (which appear on the screen as themselves) and
its 33 Control characters (which, except for TAB, appear on the screen as,
e.g. \*Q\^^C\*U). There are, however, two characters that may not appear.
One is the NL character (because it is always converted into a
\fIline-separator\fP, which is not quite a character) and the other is the
NUL character (^@) which is used internally
within \s-2JOVE\s0 to delimit lines (lines also have a maximum length,
which is 1023 in most systems).
.LP
However, \s-2JOVE\s0 is \*Q8-bit clean\*U, so if your keyboard is able to
produce all 256 8-bit characters, the extra ones will appear in octal (e.g.
\*Q\^\e\^277\*U). Moreover, if your
.UX
system supports the \fILocale\fP facility (as most modern ones do), you may
set the variable \fIlc-ctype\fP to \*QC\*U (the default, which corresponds
to pure ASCII), or to \*Qiso_8859_1\*U (which corresponds to the Latin-1
alphabet with a total of 192 printing characters, all of which \s-2JOVE\s0
should be able to display), or to any other \fILocale\fP available on your
system. The initial value of \fIlc-ctype\fP is taken from your LC_CTYPE
environment variable, and otherwise defaults to \*QC\*U. With each
\fILocale\fP \s-2JOVE\s0 will know which of the extra characters are
upper-case letters, lower-case letters, etc.
.HH 2 "Name Completion"
.LP
\s-2JOVE\s0 knows the names of all sorts of objects, such as \s-2JOVE\s0
Commands, \s-2JOVE\s0 Variables, Macros, Keymaps, Buffers and even (with
some help from the
.UX
directories) Files. Since names must be entered often, \s-2JOVE\s0
has features to make this easier.
.LP
For many names, \s-2JOVE\s0 is willing to supply a default if
you enter an empty answer. For example, when you are telling
.IQ select-buffer
which buffer to select, it will default to the previous buffer.
When the prompt mentions a default, this is the value that will
be used in place of an empty answer.
.LP
If the default isn't the name you want, name completion can help
you enter a name. When you are prompted for a name, you need type
only enough letters to make it unambiguous. At any point in the course of
typing the name, you can type question mark (?) to see a list of all the
relevant names which begin with the characters you have already typed; you
can type Tab to have \s-2JOVE\s0 supply as many characters as it can; or you
can type Return to terminate your input, or you can type Space to do both
(supply the characters and terminate). For example, you are typing a
Command and you have so far typed the letters \*Q\fIau\fP\*U and you then
type a question mark, you will see the list
.DS I
auto-execute-command
auto-execute-macro
auto-fill-mode
auto-indent-mode
.DE
If you type a Return at this point, \s-2JOVE\s0 will complain by ringing
the bell, because the letters you have typed do not unambiguously specify a
single command. But if you type Tab or Space, \s-2JOVE\s0 will supply the
characters \*Q\fIto-\fP\*U because all commands that begin \*Q\fIau\fP\*U also
begin \*Q\fIauto-\fP\*U. You could then type the letter \*Qf\*U followed
by either Space or Return, and \s-2JOVE\s0 would complete and obey the entire
command.
.LP
There are in fact two cases that can arise.
.IP 1.
.B
The name you are typing is supposed to exist already
.R
(Commands, Variables and Keymaps always, Macros and Buffers except when you
are trying to create a new one).
.br
If you type Return and what you have typed is not an unambiguous prefix of
any name of the right kind, you will hear the bell; otherwise, it will
complete what you have typed and then use it. Tab will complete what it can
(you can then type Return if it looks right). Space will complete what it
can and use it if it then matches.
.IP 2.
.B
The name you are typing may be a new one
.R
(Files always, Macros (including the Keyboard Macro) and Buffers if you are
allowed to create or rename one at that point).
.br
If you type Return, and it does not match any name, then it will take
exactly what you have typed as a new name. Tab and Space try to complete as
before.
.LP
If you type ^R, it will insert a name that might be useful. Even if
this name is not the one you wish to enter, it is often convenient
to edit this name into the desired one. The inserted name will be
the default (if there is one), or the current value (if there is
one). When \s-2JOVE\s0 is asking for a command or variable name, ^R
will insert the last one named.
.LP
Buffers, keymaps, and macros are also numbered (if you type \*Q?\*U when
first prompted, you will see the numbers as well as the possible names), and
the number may be used in place of the name.
.HH 3 "Filename Completion"
.LP
Whenever \s-2JOVE\s0 is prompting you for a filename, say in the
\fIfind-file\fP command, things happen as just described and Return always
accepts the name just as it is (because you might be wanting to create a new
file with a name similar to that of an existing one). The variable
\fIbad-filename-extensions\fP contains a list of words separated by spaces
which are to be considered bad filename extensions; any filename with one of
these extensions will not be counted in filename completion. The default
includes \*Q.o\*U so if you have jove.c and jove.o in the same directory,
the filename completion will not complain of an ambiguity because it will
ignore jove.o.
.LP
When \s-2JOVE\s0 is prompting for a \fIfilename\fP,
it has the following extra functions:
.IP "^N"
Insert the next filename from the argument list in the Minibuf.
.IP "^P"
Insert the previous filename from the argument list in the Minibuf.
.HH 1 "Commands and Variables"
.HH 2 "Commands"
.LP
\s-2JOVE\s0 uses \fIcommands\fP
which have long names such as
\fInext-line\fP.
Then \fIkeys\fP such as ^N are connected to
commands through the \fIcommand dispatch table\fP.
When we say that ^N moves the cursor down a line,
we are glossing over a distinction which is unimportant for ordinary use,
but essential for simple customization:
it is the command \fInext-line\fP which knows how to move down a line,
and ^N moves down a line because it is connected to that command.
The name for this connection is a \fIbinding\fP; we say that the key
^N \fIis bound to\fP the command \fInext-line\fP (or vice versa). \s-2JOVE\s0 has many
bindings already \fIbuilt-in\fP, but you (or your system administrator) may
also add your own, e.g. to make full use of any Function Keys provided on your
particular keyboard.
.LP
Thus there may be three ways to refer to a command \(em by its full name, or
by its standard (built-in) binding, or by your customized binding.
Throughout this manual, we shall always use the standard bindings,
followed by the full name (in italics). The standard bindings are designed
to work on any ASCII keyboard, and can always be used so long as you (or
your system administrator) have not actually changed them. But they
are hard to remember, so you may well prefer to use your own, particularly
if you always use the same terminal. See the section on Customization for
more details.
.LP
Some terminals and modems cannot accept characters flat out
at a reasonable baud rate, and therefore require the use of a flow control
protocol using the characters ^S and ^Q (see the variable
\fIallow-^S-and-^Q\fP). These characters cannot, therefore, be typed by the
user. It has therefore been arranged that whenever a standard binding
requires ^S (^Q) to be typed, a spare standard binding for that facility is
also provided in which ^\^\e (^^) can be typed in its place.
.LP
Not all commands are bound to keys. To invoke a command that isn't bound
to a key, you can type the sequence ESC\ X, which is bound to the command
\fIexecute-named-command\fP. You will then be able to type the name of
whatever command you want to execute on the message line.
.HH 2 "Prefix Characters"
.LP
Because there are more command names than keys,
\s-2JOVE\s0 allows a sequence of keystrokes to be bound to a command.
Usually, the first character of the sequence will be one of the two
\fIprefix characters\fP ^X or ESC.
When you type such a prefix character \s-2JOVE\s0 will wait
for the next character before deciding what to do.
If you wait more than a second or so,
\s-2JOVE\s0 will print the prefix character on the
message line as a reminder and leave the cursor down there while you type
the rest of the sequence.
Many \s-2JOVE\s0 commands are bound to a 2-stroke sequence starting with
^X or ESC.
How the next character is interpreted depends on which
of them you typed.
For example,
if you type ESC followed by B you will run \fIbackward-word\fP,
but if you type ^X followed by B you will run \fIselect-buffer\fP.
.HH 2 "Variables"
.LP
Sometimes the description of a command will say
\*Qto change this, set the variable \fImumble-foo\fP\*U.
A variable is a name used to remember a value.
\s-2JOVE\s0 contains variables which are there so that you can change
them if you want to customize.
The variable's value may be examined by some command,
and changing that value makes the command behave differently.
However, the facilities provided are pretty limited: you cannot invent new
variables, or use them for other than their built-in purposes, and their
values apply globally to all buffers irrespective of mode settings.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
set Sets the value of a variable.
print Displays the current value of a variable.
.TE
.LP
To set or change the value of a variable, type ESC\ X \fIset\fP <variable-name>
<value><return>. Values may be \fIon\fP of \fIoff\fP (for Boolean variables)
or numbers (numeric variables) or strings (string variables). To inspect the
current value of a variable, type ESC\ X print <variable-name><return>.
.HH 2 "Giving Numeric Arguments to \s-2JOVE\s0 Commands"
.LP
Many \s-2JOVE\s0 commands can be given a \fInumeric argument\fP.
Many commands interpret the argument as a repetition count (possibly
negative). For example,
giving an argument of ten to the ^F command (\fIforward-character\fP) moves forward
ten characters.
With these commands,
no argument is equivalent to an argument of 1.
.LP
Some commands use the value of the argument, or even just its presence or
absence, in highly idiosyncratic ways.
For example,
the commands which change the minor modes (such as \fIauto-fill-mode\fP)
toggle the mode if there is no argument, but turn the more off with a zero
argument, and on with any other argument.
.LP
The fundamental way of specifying an argument is to use ESC followed by the
digits of the argument, for example, ESC\ 123 ESC\ G to go to line 123.
Negative arguments are allowed, although not all commands know what
to do with them.
Unless otherwise stated, ESC\ Minus\ ... is equivalent to ESC\ Minus\ 1\ ...\ .
Note that when giving arguments to \fIsourced\fP commands
(described later under Customization) different rules apply.
.LP
Typing ^U means \*Qsupply an argument of 4\*U. Two such ^U's supply
sixteen. Thus, ^U ^U ^F moves forward sixteen characters.
This is a good way to move forward quickly,
since it moves about 1/4 of a line on most terminals.
Other useful combinations are:
^U ^U ^N (move down a good fraction of the screen),
and ^U ^U ^O (make \*Qa lot\*U of blank lines).
.LP
There are other,
terminal-dependent, ways of specifying arguments.
They have the same effect but may be easier to type.
If your terminal
has a numeric keypad which sends something recognizably different from
the ordinary digits,
it is possible to customize \s-2JOVE\s0 to allow use of
the numeric keypad for specifying arguments.
.HH 2 "Help"
.LP
To get a list of keys and their associated commands,
you type ESC\ X \fIdescribe-bindings\fP (warning: the list runs to many
screenfuls; type Space to see the next one, or ^G when you have seen enough).
If you want to describe a single key,
^X\ ? (\fIdescribe-key\fP) will work. A description of an
individual command is available by using ESC\ ? (\fIdescribe-command\fP),
and descriptions of variables by using ESC\ X \fIdescribe-variable\fP.
If you can't remember the name of the thing you want to know about,
ESC\ X \fIapropos\fP will tell you if a command or variable has a given
string in its name. For example, ESC\ X \fIapropos describe\fP will
list the names of the four describe commands just mentioned.
.HH 1 "Basic Editing Commands"
.LP
.HH 2 "Inserting Text"
.LP
To insert printing characters into the text,
just type them.
All such printing characters you type are inserted into the text at
the cursor (that is, at \fIpoint\fP),
and the cursor moves forward.
Any characters after the cursor move forward too.
If the text in the buffer is FOOBAR,
with the cursor before the B,
then if you type XX
you get FOOXXBAR,
with the cursor still before the B.
.LP
To correct text you have just inserted,
you can use DEL.
DEL deletes the character \fIbefore\fP the cursor (not the one that the
cursor is on top of or under; that is the character \fIafter\fP the
cursor).
The cursor and all characters after it move backwards.
Therefore,
if you typing a printing character and then type DEL,
they cancel out.
.LP
To end a line and start typing a new one, type Return. Return operates by
inserting a \fIline-separator\fP, so if you type Return in the middle of a
line, you break the line in two. Because a line-separator behaves like a
single character, you can type DEL at the beginning of a line to delete the
line-separator and join it with the preceding line. Note that the line
separator is \fBnot\fP a character (it is not the ASCII NL character, for
example) so that you cannot include it in search or replace strings.
.LP
As a special case, if you type Return at the end of a line and there are
two or more empty lines just below it, \s-2JOVE\s0 does not insert a
line-separator but instead merely moves to the next (empty) line. This
behavior is convenient when you want to add several lines of text in the
middle of a buffer. You can use the ^O (\fInewline-and-backup\fP)
command to \*Qopen\*U several empty lines at once; then you can insert the new
text, filling up these empty lines. The advantage is that \s-2JOVE\s0 does
not have to redraw the bottom part of the screen for each Return you type,
as it would ordinarily. That \*Qredisplay\*U can be both slow and distracting.
.LP
If you add too many characters to one line,
without breaking it with Return,
the line will grow too long to display on one screen line.
When this happens,
\s-2JOVE\s0 puts an \*Q!\*U at the extreme right margin,
and doesn't bother to display the rest of the line unless the
cursor happens to be in it.
The \*Q!\*U is not part of your text;
conversely,
even though you can't see the rest of your line,
it is still there,
and if you break the line,
the \*Q!\*U will go away.
.LP
Direct insertion works for printing characters and space,
but other
characters act as editing commands and do not insert themselves.
If you need to insert a control character,
ESC,
or DEL,
you must first \fIquote\fP it by typing the ^Q command (\fIquoted-insert\fP)
first, for example ^Q\ ^C to insert a genuine ^C.
.HH 2 "Moving the Cursor"
.LP
To do more than insert characters,
you have to know how to move the cursor.
Here are the commands for doing that.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
^A beginning-of-line Move to the beginning of the line.
^E end-of-line Move to the end of the line.
^F or \(-> forward-character Move forward over one character.
^B or \(<- backward-character Move backward over one character.
^N or \(da next-line T{
Move down one line, vertically.
If you start in the middle of one line,
you end in the middle of the next.
T}
^P or \(ua previous-line Move up one line, vertically.
ESC\ < beginning-of-file Move to the beginning of the entire buffer.
ESC\ > end-of-file Move to the end of the entire buffer.
ESC\ , beginning-of-window Move to the beginning of the visible window.
ESC\ \fB.\fP end-of-window Move to the end of the visible window.
^Z scroll-up T{
Move the lines in the window upwards. If this brings the cursor outside of
the window, it is automatically relocated.
T}
ESC\ Z scroll-down Move the lines in the window downwards.
.TE
Observe the use of the arrow keys (\(->, \(<-, \(da and \(ua) as alternatives
for ^F, ^B, ^N and ^P. These should be available on just about any terminal.
You (or your system administrator) may find it convenient to bind other
Function Keys available on your keyboard to some of these commands,
especially if those keys already have appropriate engravings on them.
See the section on Customizing \s-2JOVE\s0.
.HH 2 "Deleting Text"
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
DEL delete-previous-character Delete the character before the cursor.
^D delete-next-character Delete the character after the cursor.
ESC \e delete-white-space Delete spaces and tabs around point.
^X\ ^O delete-blank-lines Delete blank lines around the current line.
.TE
.LP
You already know about the DEL command which deletes the character
\fIbefore\fP the cursor. Another command,
^D,
deletes the character
\fIafter\fP the cursor, the one the cursor is \*Qon top of\*U or \*Qunderneath\*U,
causing the rest of the text on the line to shift left.
Line-separators act like normal characters when deleted,
so if ^D is typed at the end of a line,
that line and the next line are joined together.
.LP
The other delete commands are those which delete only formatting
characters:
spaces,
tabs,
and line-separators.
ESC\ \e (\fIdelete-white-space\fP)
deletes all the spaces and tab characters before and after point.
^X\ ^O (\fIdelete-blank-lines\fP) deletes all blank lines after the current line,
and if the current line is blank deletes all the blank
lines preceding the current line as well
(leaving one blank line, the current line).
.HH 2 "Files \(em Saving Your Work"
.LP
The commands above are sufficient for creating text in the \s-2JOVE\s0 buffer.
The more advanced \s-2JOVE\s0 commands just make things easier.
But to keep any text permanently you must put it into a \fIfile\fP.
Files are the objects which
.UX
uses for storing data for a length of time.
To tell \s-2JOVE\s0 to read text into a file,
choose a filename,
such as \fIfoo.bar\fP,
and type ^X\ ^F\ \fIfoo.bar\fP<return> (\fIfind-file\fP).
This reads the file \fIfoo.bar\fP so that its contents appear in a new
buffer on the screen for editing.
Alternatively, type ^X\ ^R \fIfoo.bar\fP<return> (\fIread-file\fP) to have the file appear in
an existing buffer.
You can make changes,
and then save the file by typing ^X\ ^S (\fIsave-file\fP).
This makes the changes permanent and actually changes the file \fIfoo.bar\fP.
Until then,
the changes are only inside \s-2JOVE\s0,
and the file \fIfoo.bar\fP is not really changed.
If the file \fIfoo.bar\fP does not exist,
and you want to create it,
read it as if it did exist.
When you save your text with ^X\ ^S, the file will be created then.
.HH 2 "Exiting and Pausing \(em Leaving \s-2JOVE\s0"
.LP
The command ^X\ ^C (\fIexit-jove\fP) will terminate the \s-2JOVE\s0
session and return to the shell. If there are modified but
unsaved buffers, \s-2JOVE\s0 will ask you for confirmation, and you
can abort the command, look at what buffers are
modified but unsaved using ^X\ ^B (\fIlist-buffers\fP), save the
valuable ones, and then exit. If what you want to do, on the other hand,
is to \fIpreserve\fP the editing session but return to the shell temporarily
you can (under most modern versions of
.UX )
issue the command ESC\ S (\fIpause-jove\fP), do your
.UX
work within your shell, and then return to \s-2JOVE\s0 using the
\fIfg\fP command to resume editing at the point where you paused.
Alternatively, for this sort of situation, you might consider using an
\fIinteractive shell\fP (that is, a shell in a \s-2JOVE\s0 window) which
lets you use the editor to issue your
.UX
commands and manipulate their output, while never leaving the editor
(the interactive shell feature is described later).
.HH 1 "Kill and Yank (or Cut and Paste)"
.LP
Any editor needs a facility for dealing with large blocks of text \(em
deleting them or moving them to other places. The usual terminology speaks
of \*QCut\*U (to remove a block of text), \*QPaste\*U (to replace it
somewhere else) and \*QCopy\*U (to copy it for subsequent pasting without
removal from its original place). For historical reasons, editors based on
\s-2EMACS\s0 use the terms Kill, Yank and Copy with essentially the same
meanings, and we shall continue to do so in this manual. However, it may be
sensible, if your keyboard has keys marked Cut, Paste and Copy, to bind
appropriate Kill, Yank and Copy commands to them as part of your local
customization.
.HH 2 "The Mark and the Region"
.LP
In general, a command that processes an arbitrary part of the buffer must
know where to start and where to stop. In \s-2JOVE\s0, such commands
usually operate on the text between \fIpoint\fP and \fIthe mark\fP. On most
terminals, the position of the mark is indicated by underlining. This body
of text is called \fIthe region\fP. To specify a region, you set point at
one end of it and mark at the other. It doesn't matter which one comes
earlier in the text.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
^@ set-mark Set the mark where point is.
^X\ ^X exchange-point-and-mark Interchange point and mark.
pop-mark Move to the previous mark in the ring.
.TE
.LP
The way to set the mark is with the ^@ command or (on some terminals) the
^Space command. They set the mark where point is. Then you can move point
away, leaving the mark behind. When the mark is set, \*Q[Point pushed]\*U
is printed on the message line.
.LP
For example,
if you wish to convert part of the buffer to all upper-case,
you can use the \fIcase-region-upper\fP command,
which operates on the text in the region.
You can first go to the beginning of the text to be capitalized,
put the mark there, move to the other end, and then type
ESC\ X \fIcase-region-upper\fP.
Or,
you can set the mark at the end of the text,
move to the beginning,
and then type the same thing.
.LP
On terminals with the requisite capabilities, the marked character is
underlined. Otherwise, you have to remember where it is (the usual method is
to set the mark and then use it soon). Alternatively, you can see where the
mark is with the command ^X\ ^X which puts the mark where point was and
point where the mark was. The extent of the region is unchanged, but the
cursor and point are now at the previous location of the mark.
.HH 2 "The Ring of Marks"
.LP
Aside from delimiting the region,
the mark is also useful for remembering a spot that you may want to go back to.
To make this feature more useful,
\s-2JOVE\s0 remembers 16 previous locations of the mark.
Most commands that set the mark push the old mark onto this stack.
To return to a marked location, use ^U\ ^@ (equivalent to \fIpop-mark\fP).
This moves point to where the mark was,
and restores the mark from the stack of former marks.
So repeated use of this command moves point to all of the old
marks on the stack,
one by one.
Since the stack is actually a ring,
enough uses of ^U\ ^@ bring point back to where it was originally.
.LP
Some commands whose primary purpose is to move point a great distance
take advantage of the stack of marks to give you a way to undo the
command.
The best example is ESC\ < (\fIbeginning-of-file\fP),
which moves to the beginning of the buffer.
If there are more than 22 lines between the beginning of
the buffer and point,
ESC\ < sets the mark first,
so that you can use ^U ^@ or ^X\ ^X to go back to where you were.
You can change the number of lines from 22 since it is kept in the variable \fImark-threshold\fP.
By setting it to 0,
you can make these commands always set the mark and
by setting it to a very large number you can make them never set it.
If a command decides to set the mark,
it prints the message [Point pushed].
.HH 2 "Killing and Moving Text"
.LP
The way of moving text with \s-2JOVE\s0 is to \fIkill\fP (cut) it,
and \fIyank\fP (paste) it back again later in one or more places.
This is very safe
because the last several pieces of killed text are all remembered,
and it is versatile
because the many commands for killing syntactic units
can also be used for moving those units.
.HH 3 "Deletion and Killing"
.LP
Most commands which erase text from the buffer save it so that you can
get it back if you change your mind, or you can
copy it to other parts of the buffer (even to a different buffer).
These commands are known as \fIkill\fP commands.
The rest of the commands that erase text do not save it;
they are known as \fIdelete\fP commands.
The delete commands include ^D and DEL,
which delete only one character at a time,
and those commands that delete only spaces or line-separators.
Commands that can destroy significant amounts of nontrivial data generally
kill. A command's
name and description will use the words \fIkill\fP or \fIdelete\fP to
say which it does.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
^D delete-next-character Delete next character.
DEL delete-previous-character Delete previous character.
ESC\ \e delete-white-space Delete spaces and tabs around point.
^X\ ^O delete-blank-lines Delete blank lines around the current line.
^K kill-to-end-of-line Kill rest of line or one or more lines.
^W kill-region Kill the region (from point to mark).
ESC\ D kill-next-word Kill word.
ESC\ DEL kill-previous-word Kill word backwards.
ESC\ K kill-to-end-of-sentence Kill to end of sentence.
^X\ DEL kill-to-beginning-of-sentence Kill to beginning of sentence.
ESC\ ^K kill-s-expression Kill from point to the end of an s-expression.
.TE
.HH 3 "Deletion"
.LP
The various delete commands have already been described.
Actually,
^D and DEL aren't always \fIdelete\fP commands;
if you give an argument,
they \fIkill\fP instead.
This prevents you from losing a great deal of text by typing a large
argument to a ^D or DEL.
.HH 3 "Killing (and Copying) the region, and Yanking it back again"
.LP
The commonest kill command is ^W (\fIkill-region\fP),
which kills everything between point and the mark*.
.FS
*Often users switch this binding from ^W to ^X\ ^K because it is too
easy to hit ^W accidentally.
.FE
With this command,
you can kill and save contiguous characters,
if you first set the mark at one end of them and then go to the other end.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
^W kill-region Kill everything between point and mark.
ESC\ W copy-region Save the region without killing.
.TE
.LP
Yanking (un-killing) is getting back text which was killed.
The usual way to
move or copy text is to kill or copy it and then yank it one or more times.
.TS
L2w(10)fR L2w(20)fI Lw(\n(Ww)fR .
^Y yank Yank (re-insert) the last killed text.
ESC\ Y yank-pop Replace re-inserted killed text with the previously killed text.
.TE
.LP
Killed text is pushed onto a \fIring buffer\fP called the \fIkill
ring\fP that remembers the last sixteen blocks of text that were killed
(why it is called a ring buffer will be explained below).
The command ^Y (\fIyank\fP) reinserts the text of the most recent kill.
The yanked text becomes the new region. Thus,
a single ^Y undoes the ^W and vice versa.
.LP
If you wish to copy a block of text,
you might want to use ESC\ W (\fIcopy-region\fP),
which copies the region into the kill ring without removing it from the buffer.
.LP
There is only one kill ring shared among all the buffers. After reading a
new file or selecting a new buffer, whatever was last killed in the previous
file or buffer is still on top of the kill ring. This is important for
moving text between buffers.
.HH 3 "Other Kill commands"
.LP
Other syntactic units can be killed, too;
words,
with ESC\ DEL (\fIkill-previous-word\fP) and ESC\ D (\fIkill-next-word\fP);
and sentences,
with ESC\ K (\fIkill-to-end-of-sentence\fP) and ^X\ DEL
(\fIkill-to-beginning-of-sentence\fP).
.HH 3 "Killing by Lines"
.LP
Another kill command is the ^K command (\fIkill-to-end-of-line\fP). If
issued at the beginning of a line, it kills all the text on the line,
leaving it blank. If given in the middle of a line, it kills all the text
up to the end of the line. If given on a line that is empty or contains
only white space (blanks and tabs) the line disappears. If ^K is done at
the end of a line, it joins that line and the next line. As a consequence,
if you go to the front of a non-blank line and type two ^K's, the line
disappears completely (but be careful, because one ^K is sufficient to
remove an empty line).
.LP
In general,
^K kills from point up to the end of the line,
unless it is at the end of a line,
in which case
it kills the line-separator following the line,
thus merging the next line into the current one.
Invisible spaces and tabs at the end of the line are ignored when
deciding which case applies,
so if point appears to be at the end of the line,
you can be sure the line-separator will be killed.
.LP
^K with an argument kills that many lines, including their line
separators (whether the lines are empty or not). Without an argument, ^K
behaves as described in the previous paragraph.
^U ^K kills four lines (but note that typing ^K four times
would kill only 2 lines)
.LP
^K with an argument of zero kills all the text before
point on the current line.
.HH 3 "Appending Kills"
.LP
Normally,
each kill command pushes a new block onto the kill ring.
However,
two or more kill commands immediately in a row (without any other
intervening commands) combine their text into a
single entry on the ring,
so that a single ^Y (\fIyank\fP) command gets it all back as it was before
it was killed. This means that you don't have to kill all the text in one
command; you can keep killing line after line,
or word after word,
until you have killed it all,
and you can still get it all back at once.
.LP
Commands that kill forward from point
add onto the end of the previously
killed text.
Commands that kill backward from point
add onto the beginning.
This way,
any sequence of mixed forward and backward kill
commands puts all the killed text into one entry without needing rearrangement.
.LP
Suppose, for example you have a line containing FOO\ BAR\ BAZ with the
cursor at the start of BAR. Type ESC\ D (\fIkill-next-word\fP), then
ESC\ DEL (\fIkill-previous-word\fP), then ESC\ F (\fIforward-word\fP) to put
the cursor after BAZ, and Space to insert a space. Then type ^Y (\fIyank\fP)
and your line will contain BAZ\ FOO\ BAR.
.HH 2 "The Kill Ring"
.LP
To recover killed text that is no longer the most recent kill,
you need the ESC\ Y (\fIyank-pop\fP) command.
The ESC\ Y command can be used
only immediately after a ^Y (\fIyank\fP) command or another ESC\ Y.
It takes the yanked
text inserted by the ^Y and replaces it with the text from an earlier
kill.
So,
to recover the text of the next-to-the-last kill,
you first use ^Y to recover the last kill,
and then discard it by use of ESC\ Y to move back to the previous one.
.LP
You can think of all the last few kills as living on a ring.
After a ^Y command,
the text at the front of the ring is still present in the buffer.
ESC\ Y \*Qrotates\*U the ring bringing the previous string of text to the front
and this text replaces the other text in the buffer as well.