Debian Codegraph @

doc/jove.nr

raw
1 .\"##########################################################################
2 .\"# This program is Copyright (C) 1986-2002 by Jonathan Payne. JOVE is #
3 .\"# provided by Jonathan and Jovehacks without charge and without #
4 .\"# warranty. You may copy, modify, and/or distribute JOVE, provided that #
5 .\"# this notice is included in all the source files and documentation. #
6 .\"##########################################################################
7 .TH JOVE 1 "24 June 1993"
8 .SH NAME
9 jove \- an interactive display-oriented text editor
10 .SH SYNOPSIS
11 .B jove
12 [
13 .BI \-d \ directory
14 ] [
15 .BI \-D \ debugfile
16 ] [
17 .BI \-l \ libdir
18 ] [
19 .BI \-s \ sharedir
20 ] [
21 .BI \-ls \ bothdir
22 ] [
23 .B \-J
24 ] [
25 .B \-j
26 ] [
27 .BI \-w n
28 ] [
29 .BI \-t \ tag
30 ] [
31 .B \-T
32 ] [
33 .BI + n\ file
34 ] [
35 .BI +/ pattern\ file
36 ] [
37 .BI \-p \ file
38 ] [
39 .IR file .\|.\|.
40 ]
41 .br
42 .B jove \-r
43 .SH DESCRIPTION
44 .hy 0
45 JOVE is Jonathan's Own Version of Emacs. It is based on the original EMACS
46 editor written at MIT by Richard Stallman. Although JOVE is meant to be
47 compatible with EMACS, there are some major differences between the two
48 editors and you shouldn't rely on their behaving identically.
49 .LP
50 JOVE aims to be small, and usable on a wide array of systems, so it works on
51 many reasonable display terminals like modern vt[12]-style terminals, and by
52 linking to a general terminal handling library such as
53 .I ncurses
54 (terminfo) or
55 .I termcap
56 (see TERMCAP(5)).
57
58 When you start up JOVE, it checks to see whether you have your
59 .I TERM
60 environment variable set. On most systems that will automatically be set up
61 for you, but if it's not JOVE will ask you what kind of terminal you are
62 using. To avoid having to type this every time you run JOVE you can set your
63 .I TERM
64 environment variable yourself. How you do this depends on which shell you
65 are running. If you are running the C Shell, as most of you are, you type
66 .sp 1
67 % setenv TERM
68 .I type
69 .sp 1
70 and with the Bourne Shell, you type
71 .sp 1
72 $ TERM=
73 .I type
74 ; export TERM
75 .sp 1
76 where
77 .I type
78 is the name of the kind of terminal you are using (e.g., vt100). If
79 neither of these works get somebody to help you.
80 .SH INVOKING JOVE
81 If you run JOVE with no arguments you will be placed in an empty buffer,
82 called
83 .I Main.
84 Otherwise, any arguments you supply are considered file names and each is
85 ``given'' its own buffer. Only the first file is actually read in \(em reading
86 other files is deferred until you actually try to use the buffers they are
87 attached to. This is for efficiency's sake: most of the time, when you run
88 JOVE on a big list of files, you end up editing only a few of them.
89 .LP
90 The names of all of the files specified on the command line are saved in a
91 buffer, called
92 .I *minibuf*.
93 The mini-buffer is a special JOVE buffer that is used when JOVE is prompting
94 for some input to many commands (for example, when JOVE is prompting for a
95 file name). When you are being prompted for a file name, you can type ^N
96 (that's Control-N) and ^P to cycle through the list of files that were
97 specified on the command line. The file name will be inserted where you are
98 typing and then you can edit it as if you typed it in yourself.
99 .LP
100 JOVE recognizes the following switches:
101 .TP
102 .BI \-d \ dirname
103 .I dirname
104 is taken to be the name of the current directory.
105 This is for systems that don't have a version of C shell that automatically
106 maintains the
107 .I CWD
108 environment variable. If
109 .B \-d
110 is not specified on a system without a modified C shell, JOVE will have to
111 figure out the current directory itself, and that can be slow. You
112 can simulate the modified C shell by putting the following lines in your
113 C shell initialization file (.cshrc):
114 .nf
115 .sp 1
116 alias cd 'cd \e!*; setenv CWD $cwd'
117 alias popd 'popd \e!*; setenv CWD $cwd'
118 alias pushd 'pushd \e!*; setenv CWD $cwd'
119 .fi
120 .TP
121 .BI \-D \ debugfile
122 .I debugfile
123 is created if missing, and some internal debug output is written to it.
124 Only for developers (or filing with bug reports on interactive-shell
125 misbehaviour)
126 .TP
127 .BI \-l \ libdir
128 Allows the user to specify the directory in which supporting
129 programs (recover, portsrv) required by JOVE can be found
130 (default <LIBDIR>). Within JOVE, this setting will be visible
131 as the
132 .I lib-dir-pathname
133 variable. If JOVE was built to fit on machines with
134 very little memory, without the features for post-crash recovery
135 or interactive processes, then this option is not relevant.
136 If
137 .I libdir
138 is a relative path, then the directory from which the running JOVE
139 binary was started will be prepended to it.
140 .TP
141 .BI \-s \ sharedir
142 Allows the user to specify the directory in which default
143 initialization files, command help and primary JOVE tutorial
144 can be found (default <SHAREDIR>). Within JOVE, this setting
145 will be visible as the
146 .I share-dir-pathname
147 variable.
148 If
149 .I sharedir
150 is a relative path, then the directory from which the running Jove
151 binary was started will be prepended to it.
152 .TP
153 .BI \-ls \ bothdir
154 Allows the user to specify the directory in which binary files and
155 initialization files required by JOVE can be found.
156 .B \-sl
157 is an alias for this option.
158 .TP
159 .B \-J
160 Inhibits reading of the system-wide initialization file (<SHAREDIR>/jove.rc).
161 .TP
162 .B \-j
163 Inhibits reading of the user's initialization file (~/.joverc).
164 .TP
165 .BI + n
166 Reads the file designated by the following argument, and positions point at
167 the
168 .I n'th
169 line instead of the (default) first line. This can be specified more than
170 once but it doesn't make sense to use it twice on the same file; in that
171 case the second one wins. If no numeric argument is given after the +,
172 the point is positioned at the end of the file.
173 .TP
174 .BI +/ pattern
175 Reads the file designated by the following argument, and positions point at
176 the first match of the pattern.
177 .TP
178 .BI \-p \ file
179 Parses the error messages in
180 .IR file .
181 The error messages are assumed to be in a format similar to the C compiler,
182 LINT, or GREP output.
183 .TP
184 .BI \-t \ tag
185 Runs the
186 .I find-tag
187 command on
188 .I tag
189 (see ctags(1)).
190 .TP
191 .B \-T
192 starts JOVE in
193 .I teach-jove
194 mode, loading the JOVE tutorial into a buffer (unsaved) with
195 the filename
196 .IR ~/teach-jove .
197 This replaces the old
198 .B teachjove
199 command.
200 .TP
201 .BI \-w n
202 Divides the window into
203 .I n
204 windows (if
205 .I n
206 is omitted, it is taken to be 2).
207 Subsequent files in the list are read in and displayed in succeeding windows.
208 .SH "RECOVERING BUFFERS AFTER A CRASH"
209 The
210 .B \-r
211 option of jove runs the JOVE recover program. Use this when the system
212 crashes, or JOVE crashes, or you accidentally get logged out while in JOVE.
213 If there are any buffers to be recovered, this will find them.
214 .LP
215 Recover looks for JOVE buffers that are left around and are
216 owned by you. (You cannot recover other peoples' buffers, obviously.)
217 If there were no buffers that were modified at the time of the
218 crash or there were but recover can't get its hands on them, you will be
219 informed with the message, ``There is nothing to recover.'' Otherwise,
220 recover prints the date and time of the version of the buffers it has,
221 and then waits for you type a command.
222 .LP
223 To get a list of the buffers recover knows about, use the
224 .I list
225 command. This will list all the buffers and the files and the number of
226 lines associated with them. Next to each buffer is a number. When you want
227 to recover a buffer, use the
228 .I get
229 command. The syntax is
230 .I get buffer filename
231 where
232 .I buffer
233 is either the buffer's name or the number at the beginning of the line. If
234 you don't type the buffer name or the filename, recover will prompt you
235 for them.
236 .LP
237 If there are a lot of buffers and you want to recover all of them, use the
238 .I recover
239 command. This will recover each buffer to the name of the buffer with ``.#''
240 prepended to the name (so that the original isn't over-written). It asks
241 for each file and if you want to restore that buffer to that name you type
242 ``yes''. If you want to recover the file but to a different name, just type
243 the new name in. If you type ``no'' recover will skip that file and go on
244 to the next one.
245 .LP
246 If you want to look at a buffer before deciding to recover it, use the
247 .I print
248 command. The syntax for this is
249 .I print buffer
250 where
251 .I buffer
252 again is either its name or the number. You can type ^C if you want to
253 abort printing the file to the terminal, and recover will respond with
254 an appropriate message.
255 .LP
256 When you're done and have all the buffers you want, type the
257 .I quit
258 command to leave. You will then be asked whether it's okay to delete the
259 tmp files. Most of the time that's okay and you should type ``yes''. When
260 you say that, JOVE removes all traces of those buffers and you won't be able
261 to look at them again. (If you recovered some buffers they will still be
262 around, so don't worry.) So, if you're not sure whether you've gotten all
263 the buffers, you should answer ``no'' so that you'll be able to run
264 recover again at a later time (presumably after you've figured out
265 which ones you want to save). If there were more than one crashed
266 JOVE session,
267 .I quit
268 will move you on to dealing with the next one instead of exiting.
269 .LP
270 If you type ^C at any time other than when you're printing a file to the
271 terminal, recover will exit without a word. If you do this but wish you
272 hadn't, just type ``jove \-r'' to the shell again, and you will be put back
273 with no loss.
274 .SH GETTING HELP
275 Once in JOVE, there are several commands available to get help. To execute
276 any JOVE command, you type ``<ESC> X command-name'' followed by <Return>. To
277 get a list of all the JOVE commands you type ``<ESC> X'' followed by ``?''.
278 The
279 .I describe-bindings
280 command can be used to get a list containing each key, and its associated
281 command (that is, the command that gets executed when you type that key).
282 If you want to save the list of bindings, you can set the jove variable
283 .I send-typeout-to-buffer
284 to ON (using the
285 .I set
286 command), and then execute the
287 .I describe-bindings
288 command. This will create a buffer and put in it the bindings list it
289 normally would have printed on the screen. Then you can save that buffer to
290 a file and print it to use as a quick reference card. (See VARIABLES below.)
291 .LP
292 Once you know the name of a command, you can find out what it does with the
293 .I describe-command
294 command, which you can invoke quickly by typing ``ESC ?''. The
295 .I apropos
296 command will give you a list of all the command with a specific string in
297 their names. For example, if you want to know the names of all the
298 commands that are concerned with windows, you can run ``apropos'' with the
299 keyword
300 .I window.
301 .LP
302 If the initialization file has provided specific keybindings for your
303 terminal, it should also be possible to view the keyboard layout with
304 the keychart macro.
305 .LP
306 If you're not familiar with the EMACS command set, it would be worth your
307 while to use run TEACHJOVE. Do do that, just type ``teachjove'' to your shell
308 and you will be placed in JOVE in a file which contains directions. I highly
309 recommend this for beginners; you may save yourself a lot of time and
310 headaches.
311 .SH KEY BINDINGS and VARIABLES
312 You can alter the key bindings in JOVE to fit your personal tastes. That
313 is, you can change what a key does every time you strike it. For example,
314 by default the ^N key is bound to the command
315 .I next-line
316 and so when you type it you move down a line. If you want to change a
317 binding or add a new one, you use the
318 .I bind-to-key
319 command. The syntax is ``bind-to-key <command> key''.
320 .LP
321 You can also change the way JOVE behaves in little ways by changing the
322 value of some variables with the
323 .I set
324 command. The syntax is ``set <variable> value'', where value is a number or a
325 string, or ``on'' or ``off'', depending on the context. For example, if you
326 want JOVE to make backup files, you set the ``make-backup-files'' variable to
327 ``on''. To see the value of a variable, use the ``print <variable>'' command.
328 .SH INITIALIZATION
329 JOVE first reads the system-wide initialization file (<SHAREDIR>/jove.rc)
330 which provides reasonable defaults for your installation and loads standard
331 macros. It will normally observe your TERM environment variable in order to
332 provide terminal-specific key bindings and a map of your keyboard (see the
333 standard ``keychart'' macro).
334 .LP
335 JOVE then automatically reads further commands from the initialization file
336 called ``.joverc'' (``jove.rc'' under MSDOS) in your HOME directory.
337 In this file you can place commands that you would normally type in JOVE.
338 If you like to rearrange the key bindings and
339 set some variables every time you get into JOVE, you should put them in your
340 initialization file. Here are a few lines from mine:
341 .nf
342 set match-regular-expressions on
343 1 auto-execute-command auto-fill /tmp/Re\e|.*drft
344 bind-to-key i-search-forward ^\e
345 bind-to-key i-search-reverse ^R
346 bind-to-key find-tag-at-point ^[^T
347 bind-to-key scroll-down ^C
348 bind-to-key grow-window ^Xg
349 bind-to-key shrink-window ^Xs
350 .fi
351 (Note that the Control Characters can be either two character sequences
352 (e.g. ^ and C together as ^C) or the actual control character. If you want
353 to use an ^ by itself you must BackSlash it (e.g., bind-to-key grow-window
354 ^X\e^ binds grow-window to ``^X^'').
355 .SH ENVIRONMENT
356 .LP
357 If the variable
358 .SB "LC_CTYPE"
359 (see
360 .BR environ (5))
361 is not set in the environment, the operational behavior of JOVE for the
362 .SB "LC_CTYPE"
363 locale category is determined by the value of the
364 .SB LANG
365 environment variable. If
366 .SB LC_ALL
367 is set, its contents are used to override both the
368 .SB LANG
369 and the
370 .SB "LC_CTYPE"
371 variable. If none of the above variables is set in the environment, the "C"
372 (U.S. style) locale determines how JOVE behaves.
373 .TP
374 .SB LC_CTYPE
375 Determines how JOVE handles characters. When
376 .SB LC_CTYPE
377 is set to a valid value, JOVE can display and handle text and filenames
378 containing valid characters for that locale. In particular, characters will
379 be correctly recognised as upper or lower case and displayed if printable.
380 However JOVE cannot display or handle Extended Unix Code (EUC) characters
381 which are more than 1 byte wide. In the "C" locale, only characters from
382 7-bit ASCII are valid (all characters with the eighth bit set being
383 displayed in octal). In the "iso_8859_1" locale (if supported by the OS),
384 the full Latin-1 alphabet is available. The JOVE variable ``lc-ctype'' can
385 be used to change the locale while JOVE is running.
386 .SH SOME MINOR DETAILS
387 You should type ^\e instead of ^S in many instances. For example, the way
388 to search for a string is documented as being ``^S'' but in reality you
389 should type ``^\e''. This is because ^S is the XOFF character (what gets
390 sent when you type the NO SCROLL key), and clearly that won't work. The XON
391 character is ``^Q'' (what gets sent when you type NO SCROLL again) which is
392 documented as the way to do a quoted-insert. The alternate key for this is
393 ``^^'' (typed as ``^`'' on vt100's and its look-alikes). If you want to
394 enable ^S and ^Q and you know what you are doing, you can put the line:
395 .nf
396 set allow-^S-and-^Q on
397 .fi
398 in your initialization file.
399 .LP
400 If your terminal has a metakey and you turn on the ``meta-key'' variable,
401 JOVE will use it to generate commands which would otherwise start with an
402 ESC. JOVE will automatically turn on ``meta-key'' if the METAKEY
403 environment variable exists. This is useful for if you have different
404 terminals (e.g., one at home and one at work) and one has a metakey and the
405 other doesn't. However, if a locale which recognises 8-bit characters is in
406 force, a metakey may be better used to generate the extra characters (so leave
407 the ``meta-key'' variable off).
408 .SH FILES
409 .nf
410 <SHAREDIR>/jove.rc \(em system-wide initialization file
411 .sp 0
412 <SHAREDIR>/jove.rc.$TERM \(em terminal-specific initialization file
413 .sp 0
414 <SHAREDIR>/keychart.$TERM \(em terminal-specific help file
415 .sp 0
416 <SHAREDIR>/macros \(em standard macros file
417 .sp 0
418 ~/.joverc \(em personal initialization file
419 .sp 0
420 <TMPDIR> \(em where temporary files are stored
421 .sp 0
422 <SHAREDIR>/teach-jove \(em the interactive tutorial
423 .sp 0
424 <LIBDIR>/recover \(em the recovery program
425 .sp 0
426 <LIBDIR>/portsrv \(em for running shells in windows (pdp11 only)
427 .SH ENVIRONMENT VARIABLES
428 .nf
429 TERM \(em your terminal type
430 .sp 0
431 METAKEY \(em if defined, sets the ``meta-key'' variable
432 .sp 0
433 SHELL \(em the shell to be used by the ``shell'' and other commands
434 .sp 0
435 COMSPEC \(em (on MSDOS) used if SHELL is not defined
436 .sp 0
437 MAIL \(em to initialize the ``mailbox'' variable
438 .sp 0
439 JOVELIB \(em overrides <LIBDIR> unless overridden by \-l or \-ls
440 .sp 0
441 JOVESHARE \(em overrides <SHAREDIR> unless overridden by \-s or \-ls
442 .sp 0
443 TMPDIR \(em overrides <TMPDIR> as directory for temporary files
444 .sp 0
445 LC_ALL, LC_CTYPE, LANG \(em to set the locale
446 .fi
447 .SH SEE ALSO
448 .nf
449 ctags(1) \(em to generate tags for the find-tag command and the \-t
450 command-line option
451 .sp 0
452 ed(1) \(em for a description of regular expressions
453 .sp 0
454 teachjove(1) \(em for an interactive JOVE tutorial.
455 .fi
456
457 .LP
458 Project resources and releases:
459 .I https://github.com/jonmacs/jove
460
461 .SH DIAGNOSTICS
462 JOVE diagnostics are meant to be self-explanatory, but you are advised
463 to seek help whenever you are confused. You can easily lose a lot of
464 work if you don't know EXACTLY what you are doing.
465
466 .SH BUGS / LIMITATIONS
467 .sp 1
468 Line lengths are limited to a fixed value set at compile time. The Default is 32768.
469
470 .sp 1
471 JOVE does not support multi-byte UTF-8 characters. In UTF-8 locales, non-ASCII
472 characters may display incorrectly. Use ASCII or single-byte encodings with
473 JOVE.
474
475 .sp 1
476 Searches can't cross line boundaries.
477
478 .SH AUTHOR
479 Jonathan Payne