joe-3.1jupp31.tgz (die zweite Klappeā€¦)
[alioth/jupp.git] / joe.1.in
1 .\" $MirOS: contrib/code/jupp/joe.1.in,v 1.25 2017/08/09 00:59:09 tg Exp $
2 .\"-
3 .TH JOE 1
4 .SH Name
5 joe \- Joe's Own Editor
6 .SH Syntax
7 .B joe [global-options] [ [local-options] filename ]...
8
9 .B jstar [global-options] [ [local-options] filename ]...
10
11 .B jmacs [global-options] [ [local-options] filename ]...
12
13 .B rjoe [global-options] [ [local-options] filename ]...
14
15 .B jpico [global-options] [ [local-options] filename ]...
16
17 .B jupp [global-options] [ [local-options] filename ]...
18 .SH Description
19 JOE is a powerful ASCII-text screen editor.  It has a "mode-less" user
20 interface which is similar to many user-friendly PC editors.  Users of
21 Micro-Pro's WordStar or Borland's "Turbo" languages will feel at home.  JOE
22 is a full featured UNIX screen-editor though, and has many features for
23 editing programs and text.
24
25 JOE also emulates several other editors.  JSTAR is a close imitation of
26 WordStar with many "JOE" extensions.  JPICO is a close imitation of the
27 Pine mailing system's PICO editor, but with many extensions and
28 improvements.  JMACS is a GNU-EMACS imitation.  RJOE is a restricted
29 version of JOE, which allows you to edit only the files specified on the
30 command line.
31
32 Although JOE is actually six different editors, it still requires only one
33 executable, but one with six different names.  The name of the editor with
34 an "rc" appended gives the name of JOE's initialisation file, which
35 determines the personality of the editor.
36
37 JUPP is free software; you can distribute it and/or modify it under the
38 terms of the GNU General Public License, Version 1, as published by the
39 Free Software Foundation.  (main.c contains more detailed exceptions.)
40 I have no plans for turning JOE into a commercial or share-ware product.
41 See the source code for exact authorship and licencing information.
42 JOE is available over the Internet from \fBhttp://joe-editor.sf.net/\fR.
43 JUPP is available at \fBhttp://mirbsd.de/jupp\fR.
44
45 .SH Usage
46
47 To start the editor, type \fBjoe\fR followed by zero or more names of files
48 you want to edit.  Each file name may be preceded by a local option setting
49 (see the local options table which follows).  Other global options, which
50 apply to the editor as a whole, may also be placed on the command line (see
51 the global options table which follows).  If you are editing a new file, you
52 can either give the name of the new file when you invoke the editor, or in
53 the editor when you save the new file.  A modified syntax for file names is
54 provided to allow you to edit program output, standard input/output, or
55 sections of files or devices.  See the section \fBFilenames\fR below for
56 details.
57
58 On cygwin32 systems, the special option \fB\-CYGhack\fR is replaced by
59 anything that comes past it (and separating whitespace) on the command
60 line as \fIone\fR option (to work around a Cygwin bug as it cannot
61 correctly be passed a UNC pathname with spaces as one argument from
62 Explorer \fIat all\fR).
63
64 Once you are in the editor, you can type in text and use special
65 control-character sequences to perform other editing tasks.  To find out
66 what the control-character sequences are, read the rest of this man page or
67 type \fB^K H\fR for help in the editor.
68
69 Now for some obscure computer-lore:
70
71 The \fB^\fR means that you hold down the \fBControl\fR key while pressing
72 the following key (the same way the \fBShift\fR key works for uppercase
73 letters).  A number of control-key sequences are duplicated on other keys,
74 so that you don't need to press the control key: \fBESC\fR will work in
75 place of \fB^[\fR, \fBDel\fR will work in place of \fB^?\fR, \fBBackspace\fR
76 will work in place of \fB^H\fR, \fBTab\fR will work in place of \fB^I\fR,
77 \fBReturn\fR or \fBEnter\fR will work in place of \fB^M\fR and
78 \fBLinefeed\fR will work in place of \fB^J\fR.  Some keyboards may give you
79 trouble with some control keys.  \fB^_\fR, \fB^^\fR and \fB^@\fR can usually
80 be entered without pressing shift (I.E., try \fB^-\fR, \fB^6\fR and
81 \fB^2\fR).  Other keyboards may reassign these to other keys.  Try:
82 \fB^.\fR, \fB^,\fR and \fB^/\fR.  \fB^SPACE\fR can usually be used in place
83 of \fB^@\fR.  \fB^\\\fR and \fB^]\fR are interpreted by many communication
84 programs, including telnet and kermit.  Usually you just hit the key twice
85 to get it to pass through the communication program.
86
87 Once you have typed \fB^K H\fR, the first help window appears at the top of
88 the screen.  You can continue to enter and edit text while the help window
89 is on.  To page through other topics, hit ^[, and ^[. (that is, ESC , and
90 ESC .).  Use \fB^K H\fR to dismiss the help window.
91
92 You can customise the keyboard layout, the help screens and a number of
93 behavior defaults by copying JOE's initialisation file (@joeinitfile@)
94 to \fB.joerc\fR in your home directory and then by modifying it.
95 See the section \fBjoerc\fR below.
96 The filename is actually \fB.\fIname\fBrc\fR where \fIname\fR is the
97 \fBargv[0]\fR the editor is called with.
98
99 Custom syntax files are loaded from \fB.jupp/syntax/\fIname\fB.jsf\fR
100 in your home directory and \fB.jupp/charmaps/\fIname\fR holds custom
101 charmaps (\fIname\fR here is the name of the syntax or charmap).
102
103 To have JOE used as your default editor for e-mail and News, you need to set
104 the \fBEDITOR\fR and \fBVISUAL\fR environment variables in your shell
105 initialisation file (\fB.cshrc\fR or \fB.profile\fR) to refer to JOE (the
106 joe binary usually resides as \fB@joeresides@\fR).
107
108 There are a number of other obscure invocation parameters which may have to
109 be set, particularly if your terminal screen is not updating as you think it
110 should.  See the section \fBEnvironment variables\fR below.
111
112 .SH Command Line Options
113
114 The following global options may be specified on the command line:
115
116 .IP -asis
117 Characters with codes above 127 will be sent to the terminal as-is, instead
118 of as inverse of the corresponding character below 128.  If this does not
119 work, check your terminal server.
120
121 .IP -backpath\ path
122 If this option is given, backup files will be stored in the specified
123 directory instead of in each file's original directory.
124
125 .IP -baud\ nnn
126 Set the baud rate for the purposes of terminal screen optimisation.  Joe
127 inserts delays for baud rates below 19200, which bypasses tty buffering so
128 that typeahead will interrupt the screen output.  Scrolling commands will
129 not be used for 38400 baud.  This is useful for X-terms and other console
130 ttys which really aren't going over a serial line.
131
132 .IP -beep
133 Joe will beep on command errors and when the cursor goes past extremes.
134
135 .IP -columns\ nnn
136 Sets the number of screen columns.
137
138 .IP -csmode
139 Continued search mode: a search immediately following a search will repeat
140 the previous search instead of prompting for new string.  This is useful for
141 the the ^[S and ^[R commands and for when joe is trying to be emacs.
142
143 .IP -dopadding
144 Joe usually assumes that there is some kind of flow control between it and
145 the tty.  If there isn't, this option will make joe output extra ^@s to the
146 tty as specified by the termcap entry.  The extra ^@s allow the terminal to
147 catch up after long terminal commands.
148
149 .IP -exask
150 This option makes ^KX verify the file name that it's about to write.
151
152 .IP -force
153 This option makes sure that the last line of the file has a line-feed which
154 it's saved.
155
156 .IP -help
157 The editor will start with the help screen on if this option is given.
158
159 .IP -keepup
160 Normally the column number and control-key prefix fields of the status lines
161 are on a one second delay to reduce CPU consumption, but with this option
162 they are updated after each key-stroke.
163
164 .IP -lightoff
165 The block highlighting will go away after any block command if this option
166 is given.
167
168 .IP -lines\ nnn
169 Sets the number of screen lines.
170
171 .IP -marking
172 Text between ^KB and the cursor is highlighted (use with \-lightoff and a
173 modified joerc file to have drop-anchor style block selection).
174
175 .IP -mid
176 If this option is set and the cursor moves off the window, the window will
177 be scrolled so that the cursor is in the center.  This option is forced on
178 slow terminals which don't have scrolling commands.
179
180 .IP -nobackups
181 This option prevents backup files.
182
183 .IP -nonotice
184 This option prevent the copyright notice from being displayed when the
185 editor starts.
186
187 .IP -nosta
188 This option eliminates the top-most status line.  It's nice for when you
189 only want to see your text on the screen or if you're using a vt52.
190
191 .IP -noxon
192 Attempt to turn off ^S/^Q processing.  This is useful for when joe is trying
193 to be WordStar or EMACS.
194
195 .IP -orphan
196 When this option is active, extra files on the command line will be placed
197 in orphaned buffers instead of in extra windows.  This is useful for when
198 joe is trying to be emacs.
199
200 .IP -pg\ nnn
201 This specifies the number of lines to keep after PgUp/PgDn (^U/^V).  If \-1
202 is given, half the window is kept.
203
204 .IP -skiptop\ nnn
205 Don't use the top nnn lines of the screen.  Useful for when joe is used as a
206 BBS editor.
207
208 .LP
209 Each of these options may be specified in the joerc file as well.  In
210 addition, the NOXON, BAUD, LINES, COLUMNS and DOPADDING options may be
211 specified with environment variables.
212 See the section \fBEnvironment variables\fR below.
213
214 The following options may be specified before each filename on the command
215 line:
216
217 .IP +nnn
218 The cursor starts on the specified line.
219
220 .IP -crlf
221 Joe uses CR-LF as the end of line sequence instead of just LF.  This is for
222 editing MS-DOS or VMS files.
223
224 .IP -hex
225 Sets the buffer to hex edit mode.
226
227 .IP -wordwrap
228 Joe wraps the previous word when you type past the right margin.
229
230 .IP -autoindent
231 When you hit Return on an indented line, the indentation is duplicated onto
232 the new line.
233
234 .IP -overwrite
235 Typing overwrites existing characters instead of inserting before them.
236
237 .IP -lmargin\ nnn
238 Sets the left margin.
239
240 .IP -rmargin\ nnn
241 Sets the right margin.
242
243 .IP -tab\ nnn
244 Sets the tab width.
245
246 .IP -indentc\ nnn
247 Sets the indentation character for ^K, and ^K. (32 for SPACE, 9 for TAB).
248
249 .IP -istep\ nnn
250 Sets the indentation step for ^K, and ^K..
251
252 .IP -linums
253 Line numbers are displayed before each line.
254
255 .IP -rdonly
256 The file is read only.
257
258 .IP -keymap\ name
259 Use an alternate section of the joerc file for the key sequence bindings.
260 For example,
261 .B joe, jstar, rjoe
262 and
263 .B jupp
264 support
265 .B \-keymap cua
266 to make ^Z, ^X, ^C and ^V do the same thing as in contemporary GUI editors.
267
268 .LP
269 These options can also be specified in the joerc file.  They can be set
270 depending on the file-name extension.  Programs (.c, .h or .p extension)
271 usually have autoindent enabled.  Wordwrap is enabled on other files, but rc
272 files have it disabled.
273
274 .SH Editing Tasks
275 .SS Basic Editing
276
277 When you type characters into the editor, they are normally inserted into
278 the file being edited (or appended to the file if the cursor is at the end
279 of the file).  This is the normal operating mode of the editor.  If you want
280 to replace some existing text, you have to delete the old text before or
281 after you type in the replacement text.  The \fBBackspace\fR key can be used
282 for deleting text: move the cursor to right after the text you want to
283 delete and hit \fBBackspace\fR a number of times.
284
285 Hit the \fBEnter\fR or \fBReturn\fR key to insert a line-break.  For
286 example, if the cursor was in the middle of a line and you hit \fBReturn\fR,
287 the line would be split into two lines with the cursor appearing at the
288 beginning of the second line.  Hit \fBBackspace\fR at the beginning of a
289 line to eliminate a line-break.
290
291 Use the arrow keys to move around the file.  If your keyboard doesn't have
292 arrow keys (or if they don't work for some reason), use \fB^F\fR to move
293 forwards (right), \fB^B\fR to move backwards (left), \fB^P\fR to move to the
294 previous line (up), and \fB^N\fR to move to the next line (down).  The right
295 and left arrow keys simply move forwards or backwards one character at a
296 time through the text: if you're at the beginning of a line and
297 you press left-arrow, you will end up at the end of the previous line.  The
298 up and down arrow keys move forwards and backwards by enough characters so
299 that the cursor appears in the same column that it was in on the original
300 line.
301
302 If you want to indent the text you enter, you can use the \fBTAB\fR key.
303 This inserts a special control character which makes the characters which
304 follow it begin at the next TAB STOP.  TAB STOPS normally occur every 8
305 columns, but this can be changed with the \fB^T D\fR command.  Python
306 programmers often set TAB STOPS on every 4 columns.
307
308 If for some reason your terminal screen gets messed up (for example, if
309 you receive a mail notice from biff), you can have the editor refresh the
310 screen by hitting \fB^R\fR.
311
312 There are many other keys for deleting text and moving around the file.  For
313 example, hit \fB^D\fR to delete the character the cursor is on instead of
314 deleting backwards like \fBBackspace\fR.  \fB^D\fR will also delete a
315 line-break if the cursor is at the end of a line.  Type \fB^Y\fR to delete
316 the entire line the cursor is on or \fB^J\fR to delete just from the cursor
317 to the end of the line.
318
319 Hit \fB^A\fR to move the cursor to the beginning of the line it's on.  Hit
320 \fB^E\fR to move the cursor to the end of the line.  Hit \fB^U\fR or
321 \fB^V\fR for scrolling the cursor up or down 1/2 a screen's worth.
322 "Scrolling" means that the text on the screen moves, but the cursor stays at
323 the same place relative to the screen.  Hit \fB^K U\fR or \fB^K V\fR to move
324 the cursor to the beginning or the end of the file.  Look at the help
325 screens in the editor to find even more delete and movement commands.
326
327 If you make a mistake, you can hit \fB^_\fR to "undo" it.  On most keyboards
328 you hit just \fB^-\fR to get \fB^_\fR, but on some you might have to hold
329 both the \fBShift\fR and \fBControl\fR keys down at the same time to get it.
330 If you "undo" too much, you can "redo" the changes back into existence by
331 hitting \fB^^\fR (type this with just \fB^6\fR on most keyboards).
332
333 If you were editing in one place within the file, and you then temporarily
334 had to look or edit some other place within the file, you can get back to
335 the original place by hitting \fB^K -\fR.  This command actually returns you
336 to the last place you made a change in the file.  You can step through a
337 history of places with \fB^K -\fR and \fB^K =\fR, in the same way you can
338 step through the history of changes with the "undo" and "redo" commands.
339
340 When you are done editing the file, hit \fB^K X\fR to exit the editor.  You
341 will be prompted for a file name if you hadn't already named the file you
342 were editing.
343
344 When you edit a file, you actually edit only a copy of the file.  So if you
345 decide that you don't want the changes you made to a file during a
346 particular edit session, you can hit \fB^C\fR to exit the editor without
347 saving them.
348
349 If you edit a file and save the changes, a "backup" copy of that file is
350 created in the current directory, with a ~ appended to the name, which
351 contains the original version of the file.
352
353 .SS Word wrap and formatting
354
355 If you type past the right edge of the screen in a C language or PASCAL
356 file, the screen will scroll to the right to follow the cursor.  If you type
357 past the right edge of the screen in a normal file (one whose name doesn't
358 end in .c, .h or .p), JOE will automatically wrap the last word onto the
359 next line so that you don't have to hit \fBReturn\fR.  This is called
360 word-wrap mode.  Word-wrap can be turned on or off with the \fB^T W\fR
361 command.  JOE's initialisation file is usually set up so that this mode is
362 automatically turned on for all non-program files.  See the section below on
363 the \fBjoerc\fR file to change this and other defaults.
364
365 Aside for Word-wrap mode, JOE does not automatically keep paragraphs
366 formatted like some word-processors.  Instead, if you need a paragraph to be
367 reformatted, hit \fB^K J\fR.  This command "fills in" the paragraph that the
368 cursor is in, fitting as many words in a line as is possible.  A paragraph,
369 in this case, is a block of text separated above and below by a blank line.
370
371 The margins which JOE uses for paragraph formatting and word-wrap can be set
372 with the \fB^T L\fR and \fB^T R\fR commands.  If the left margin is set to
373 a value other than 1, then when you start typing at the beginning of a line,
374 the cursor will immediately jump to the left margin.
375
376 If you want to center a line within the margins, use the \fB^K A\fR command.
377
378 .SS Over-type mode
379
380 Sometimes it's tiresome to have to delete old text before or after you
381 insert new text.  This happens, for example, when you are changing a table
382 and you want to maintain the column position of the right side of the table.
383 When this occurs, you can put the editor in over-type mode with \fB^T T\fR.
384 When the editor is in this mode, the characters you type in replace existing
385 characters, in the way an idealised typewriter would.  Also, \fBBackspace\fR
386 simply moves left instead of deleting the character to the left, when it's
387 not at the end or beginning of a line.  Over-type mode is not the natural
388 way of dealing with text electronically, so you should go back to
389 insert-mode as soon as possible by typing \fB^T T\fR again.
390
391 If you need to insert while you're in over-type mode, hit \fB^@\fR.  This
392 inserts a single SPACE into the text.
393
394 .SS Control and Meta characters
395
396 Each character is represented by a number.  For example, the number for 'A'
397 is 65 and the number for '1' is 49.  All of the characters which you
398 normally see have numbers in the range of 32 - 126 (this particular
399 arbitrary assignment between characters and numbers is called the ASCII
400 character set).  The numbers outside of this range, from 0 to 255, aren't
401 usually displayed, but sometimes have other special meanings.  The number
402 10, for example, is used for the line-breaks.  You can enter these special,
403 non-displayed \fBcontrol characters\fR by first hitting \fB`\fR and then
404 hitting a character in the range \fB@ A B C ... X Y Z [ ^ ] \e _\fR to get
405 the number 0 - 31, and ? to get 127.  For example, if you hit \fB` J\fR,
406 you'll insert a line-break character, or if you hit \fB` I\fR, you'll insert
407 a TAB character (which does the same thing the TAB key does).  A useful
408 control character to enter is 12 (\fB` L\fR), which causes most printers to
409 advance to the top of the page.  You'll notice that JOE displays this
410 character as an underlined L.  You can enter the characters above 127, the
411 \fBmeta characters\fR, by first hitting \fB^\e\fR.  This adds 128
412 to the next (possibly control) character entered.  JOE displays characters
413 above 128 in inverse-video.  Some foreign languages, which have more letters
414 than English, use the meta characters for the rest of their alphabet.  You
415 have to put the editor in \fBASIS\fR mode (described later) to have these
416 passed untranslated to the terminal.
417
418 .SS Prompts
419 If you hit \fBTAB\fR at any file name prompt, joe will attempt to complete
420 the name you entered as much as possible.  If it couldn't complete the
421 entire name, because there are more than one possible completions, joe
422 beeps.  If you hit \fBTAB\fR again, joe list the completions.  You can use
423 the arrow keys to move around this directory menu and press RETURN or SPACE
424 to select an item.  If you press the first letter of one of the directory
425 entries, it will be selected, or if more than one entry has the same first
426 letter, the cursor will jump between those entries.  If you select a
427 subdirectory or .., the directory name is appended to the prompt and the new
428 directory is loaded into the menu.  You can hit Backspace to go back to the
429 previous directory.
430
431 Most prompts record a history of the responses you give them.  You can hit
432 up and down arrow to step through these histories.
433
434 Prompts are actually single line windows with no status line, so you can use
435 any editing command that you normally use on text within the prompts.  The
436 prompt history is actually just other lines of the same "prompt file".  Thus
437 you can can search backwards though the prompt history with the normal \fB^K
438 F\fR command if you want.
439
440 Since prompts are windows, you can also switch out of them with \fB^K P\fR
441 and \fB^K N\fR.
442
443 .SS Where am I?
444
445 Hit \fB^K SPACE\fR to have JOE report the line number, column number, and
446 byte number on the last line of the screen.  The number associated with the
447 character the cursor is on (its ASCII code) is also shown.  You can have the
448 line number and/or column number always displayed on the status line by
449 setting placing the appropriate escape sequences in the status line setup
450 strings.  Edit the joerc file for details.
451
452 .SS File operations
453
454 You can hit \fB^K D\fR to save the current file (possibly under a different
455 name from what the file was called originally).  After the file is saved,
456 you can hit \fB^K E\fR to edit a different file.
457
458 If you want to save only a selected section of the file, see the section on
459 \fBBlocks\fR below.
460
461 If you want to include another file in the file you're editing, use \fB^K
462 R\fR to insert it.
463
464 .SS Temporarily suspending the editor
465
466 If you need to temporarily stop the editor and go back to the shell, hit
467 \fB^K Z\fR.  You might want to do this to stop whatever you're editing and
468 answer an e-mail message or read this man page, for example.  You have to
469 type \fBfg\fR or \fBexit\fR (you'll be told which when you hit \fB^K Z\fR)
470 to return to the editor.
471
472 .SS Searching for text
473
474 Hit \fB^K F\fR to have the editor search forwards or backwards for a text
475 fragment (\fBstring\fR) for you.  You will be prompted for the text to
476 search for.  After you hit \fBReturn\fR, you are prompted to enter options.
477 You can just hit \fBReturn\fR again to have the editor immediately search
478 forwards for the text, or you can enter one or more of these options:
479
480 .IP \fBb
481 Search backwards instead of forwards.
482
483 .IP \fBi
484 Treat uppercase and lower case letters as the same when searching.  Normally
485 uppercase and lowercase letters are considered to be different.
486
487 .IP \fBnnn
488 (where \fBnnn\fR is a number) If you enter a number, JOE searches for the
489 Nth occurrence of the text.  This is useful for going to specific places in
490 files structured in some regular manner.
491
492 .IP \fBr
493 Replace text.  If you enter the \fBr\fR option, then you will be further
494 prompted for replacement text.  Each time the editor finds the search text,
495 you will be prompted as to whether you want to replace the found search text
496 with the replacement text.  You hit: \fBy\fR to replace the text and then
497 find the next occurrence, \fBn\fR to not replace this text, but to then find
498 the next occurrence, \fBl\fR to replace the text and then stop searching,
499 \fBr\fR to replace all of the remaining occurrences of the search text in
500 the remainder of the file without asking for confirmation (subject to the
501 \fBnnn\fR option above), or \fB^C\fR to stop searching and replacing.
502
503 .PP
504 You can hit \fB^L\fR to repeat the previous search.
505
506 .SS Regular Expressions
507
508 A number of special character sequences may be entered as search text:
509
510 .IP \fB\e*
511 This finds zero or more characters.  For example, if you give \fBA\e*B\fR as
512 the search text, JOE will try to find an A followed by any number of characters
513 and then a B.
514
515 .IP \fB\e?
516 This finds exactly one character.  For example, if you give \fBA\e?B\fR as
517 the search text, JOE will find AXB, but not AB or AXXB.
518
519 .IP \fB\e^\ \e$
520 These match the beginning and end of a line.  For example, if you give
521 \fB\e^test\e$\fR, then JOE with find \fBtest\fR on a line by itself.
522
523 .IP \fB\e<\ \e>
524 These match the beginning and end of a word.  For example, if you give
525 \fB\e<\e*is\e*\e>\fR, then joe will find whole words which have the
526 sub-string \fBis\fR within them.
527
528 .IP \fB\e[...]
529 This matches any single character which appears within the brackets.  For
530 example, if \fB\e[Tt]his\fR is entered as the search string, then JOE finds
531 both \fBThis\fR and \fBthis\fR.  Ranges of characters can be entered within
532 the brackets.  For example, \fB\e[A-Z]\fR finds any uppercase letter.  If
533 the first character given in the brackets is \fB^\fR, then JOE tries to find
534 any character not given in the the brackets.
535
536 .IP \fB\ec
537 This works like \fB\e*\fR, but matches a balanced C-language expression.
538 For example, if you search for \fBmalloc(\ec)\fR, then JOE will find all
539 function calls to \fBmalloc\fR, even if there was a \fB)\fR within the
540 parenthesis.
541
542 .IP \fB\e+
543 This finds zero or more of the character which immediately follows the
544 \fB\e+\fR.  For example, if you give \fB\e[ ]\e+\e[ ]\fR, where the
545 characters within the brackets are both SPACE and TAB, then JOE will find
546 whitespace.
547
548 .IP \fB\e\e
549 Matches a single \e.
550
551 .IP \fB\en
552 This finds the special end-of-line or line-break character.
553
554 .PP
555 A number of special character sequences may also be given in the replacement
556 string:
557
558 .IP \fB\e&
559 This gets replaced by the text which matched the search string.  For
560 example, if the search string was \fB\e<\e*\e>\fR, which matches words, and
561 you give \fB"\e&"\fR, then joe will put quote marks around words.
562
563 .IP \fB\e0\ -\ \e9
564 These get replaced with the text which matched the Nth \fB\e*\fR, \fB\e?\fR,
565 \fB\e+\fR, \fB\ec\fR, \fB\e+\fR, or \fB\e[...]\fR in the search string.
566
567 .IP \fB\e\e
568 Use this if you need to put a \fB\e\fR in the replacement string.
569
570 .IP \fB\en
571 Use this if you need to put a line-break in the replacement string.
572 .PP
573 Some examples:
574
575 Suppose you have a list of addresses, each on a separate line, which starts
576 with "Address:" and has each element separated by commas.  Like so:
577
578 Address: S. Holmes, 221b Baker St., London, England
579
580 If you wanted to rearrange the list, to get the country first, then the
581 city, then the person's name, and then the address, you could do this:
582
583 Type \fB^K F\fR to start the search, and type:
584
585 \fBAddress:\e*,\e*,\e*,\e*\e$\fR
586
587 to match "Address:", the four comma-separated elements, and then the end of
588 the line.  When asked for options, you would type \fBr\fR to replace the
589 string, and then type:
590
591 \fBAddress:\e3,\e2,\e0,\e1\fR
592
593 To shuffle the information the way you want it. After hitting return, the
594 search would begin, and the sample line would be changed to:
595
596 Address: England, London, S. Holmes, 221b Baker St.
597
598
599 .SS Blocks
600
601 If you want to move, copy, save or delete a specific section of text, you
602 can do it with highlighted blocks.  First, move the cursor to the start of
603 the section of text you want to work on, and press \fB^K B\fR.  Then move
604 the cursor to the character just after the end of the text you want to
605 affect and press \fB^K K\fR.  The text between the \fB^K B\fR and \fB^K K\fR
606 should become highlighted.  Now you can move your cursor to someplace else
607 in your document and press \fB^K M\fR to move the highlighted text there.
608 You can press \fB^K C\fR to make a copy of the highlighted text and insert
609 it to where the cursor is positioned.  \fB^K Y\fR to deletes the highlighted
610 text.  \fB^K W\fR, writes the highlighted text to a file.
611
612 A very useful command is \fB^K /\fR, which filters a block of text through a
613 unix command.  For example, if you select a list of words with \fB^K B\fR
614 and \fB^K K\fR, and then type \fB^K / sort\fR, the list of words will be
615 sorted.  Another useful unix command for \fB^K /\fR, is \fBtr\fR.  If you
616 type \fB^K / tr a-z A-Z\fR, then all of the letters in the highlighted block
617 will be converted to uppercase.
618
619 After you are finished with some block operations, you can just leave the
620 highlighting on if you don't mind it (of course, if you accidentally hit
621 \fB^K Y\fR without noticing...).  If it really bothers you, however, just
622 hit \fB^K B ^K K\fR, to turn the highlighting off.
623
624 .SS Indenting program blocks
625 Auto-indent mode toggled with the \fB^T I\fR command.  The
626 \fBjoerc\fR is normally set up so that files with names ending with .p, .c
627 or .h have auto-indent mode enabled.  When auto-indent mode is enabled and
628 you hit \fBReturn\fR, the cursor will be placed in the same column that the
629 first non-SPACE/TAB character was in on the original line.
630
631 You can use the \fB^K ,\fR and \fB^K .\fR commands to shift a block of text
632 to the left or right.  If no highlighting is set when you give these
633 commands, the program block the cursor is located in will be selected, and
634 will be moved by subsequent \fB^K ,\fR and \fB^K .\fR commands.  The number
635 of columns these commands shift by can be set through a \fB^T\fR option.
636
637 .SS Windows
638 You can edit more than one file at the same time or edit two or more
639 different places of the same file.  To do this, hit \fB^K O\fR, to split the
640 screen into two windows.  Use \fB^K P\fR or \fB^K N\fR to move the cursor
641 into the top window or the lower window.  Use \fB^K E\fR to edit a new
642 file in one of the windows.  A window will go away when you save the file
643 with \fB^K X\fR or abort the file with \fB^C\fR.  If you abort a file which
644 exists in two windows, one of the window goes away, not the file.
645
646 You can hit \fB^K O\fR within a window to create even more windows.  If you
647 have too many windows on the screen, but you don't want to eliminate them,
648 you can hit \fB^K I\fR.  This will show only the window the cursor is in, or
649 if there was only one window on the screen to begin with, try to fit all
650 hidden windows on the screen.  If there are more windows than can fit on
651 the screen, you can hit \fB^K N\fR on the bottom-most window or \fB^K P\fR
652 on the top-most window to get to them.
653
654 If you gave more than one file name to JOE on the command line, each file
655 will be placed in a different window.
656
657 You can change the height of the windows with the \fB^K G\fR and \fB^K T\fR
658 commands.
659
660 .SS Keyboard macros
661
662 Macros allow you to record a series of keystrokes and replay them with the
663 press of two keys.  This is useful to automate repetitive tasks.  To start a
664 macro recording, hit \fB^K [\fR followed by a number from 0 to 9.  The
665 status line will display (Macro n recording...).  Now, type in the series of
666 keystrokes that you want to be able to repeat.  The commands you type will
667 have their usual effect. Hit \fB^K ]\fR to stop recording the macro.  Hit
668 \fB^K\fR followed by the number you recorded the macro in to execute one
669 iteration of the key-strokes.
670
671 For example, if you want to put "**" in front of a number of lines, you can
672 type:
673
674 \fB^K [ ^A ** \fR<down arrow> \fB^K ]\fR
675
676 Which starts the macro recording, moves the cursor to the beginning of the
677 line, inserts "**", moves the cursor down one line, and then ends the
678 recording. Since we included the key-strokes needed to position the cursor
679 on the next line, we can repeatedly use this macro without having to move
680 the cursor ourselves, something you should always keep in mind when
681 recording a macro.
682
683 If you find that the macro you are recording itself has a repeated set of
684 key-strokes in it, you can record a macro within the macro, as long as you
685 use a different macro number.  Also you can execute previously recorded
686 macros from within new macros.
687
688
689 .SS Repeat
690 You can use the repeat command, \fB^K \e\fR, to repeat a macro, or any other
691 edit command or even a normal character, a specified number of times.  Hit
692 \fB^K \e\fR, type in the number of times you want the command repeated and
693 press \fBReturn\fR.  The next edit command you now give will be repeated
694 that many times.
695
696 For example, to delete the next 20 lines of text, type:
697
698 \fB^K \ 20\fR<return>\fB^Y\fR
699
700 .SS Rectangle mode
701 Type \fB^T X\fR to have \fB^K B\fR and \fB^K K\fR select rectangular blocks
702 instead of stream-of-text blocks.  This mode is useful for moving, copying,
703 deleting or saving columns of text.  You can also filter columns of text
704 with the \fB^K /\fR command- if you want to sort a column, for example.  The
705 insert file command, \fB^K R\fR is also effected.
706
707 When rectangle mode is selected, over-type mode is also useful
708 (\fB^T T\fR).  When over-type mode is selected, rectangles will replace
709 existing text instead of getting inserted before it.  Also the delete block
710 command (\fB^K Y\fR) will clear the selected rectangle with SPACEs and TABs
711 instead of deleting it.  Over-type mode is especially useful for the filter
712 block command (\fB^K /\fR), since it will maintain the original width of the
713 selected column.
714
715 .SS Tag search
716 If you are editing a large C program with many source files, you can use the
717 \fBctags\fR program to generate a \fBtags\fR file.  This file contains a
718 list of program symbols and the files and positions where the symbols are
719 defined.  The \fB^K ;\fR command can be used to lookup a symbol (functions,
720 defined constants, etc.), load the file where the symbol is defined into the
721 current window and position the cursor to where the symbol is defined.
722 \fB^K ;\fR prompts you for the symbol you want, but uses the symbol the
723 cursor was on as a default.  Since \fB^K ;\fR loads
724 the definition file into the current window, you probably want to split the
725 window first with \fB^K O\fR, to have both the original file and the
726 definition file loaded.
727
728 .SS Shell windows
729 Hit \fB^K '\fR to run a command shell in one of JOE's windows.  When the
730 cursor is at the end of a shell window (use \fB^K V\fR if it's not),
731 whatever you type is passed to the shell instead of the window.  Any output
732 from the shell or from commands executed in the shell is appended to the
733 shell window (the cursor will follow this output if it's at the end of the
734 shell window).  This command is useful for recording the results of shell
735 commands- for example the output of \fBmake\fR, the result of \fBgrep\fRping
736 a set of files for a string, or directory listings from \fBFTP\fR sessions.
737 Besides typeable characters, the keys ^C, Backspace, DEL, Return and ^D are
738 passed to the shell.  Type the shell \fBexit\fR command to stop recording
739 shell output.  If you press \fB^C\fR in a shell window, when the cursor is
740 not at the end of the window, the shell is \fBkill\fRed.
741
742 .SH \fBEnvironment\ variables
743
744 For JOE to operate correctly, a number of other environment settings must be
745 correct.  The throughput (baud rate) of the connection between the computer
746 and your terminal must be set correctly for JOE to update the screen
747 smoothly and allow typeahead to defer the screen update.  Use the \fBstty
748 nnn\fR command to set this.  You want to set it as close as possible to
749 actual throughput of the connection.  For example, if you are connected via
750 a 1200 baud modem, you want to use this value for \fBstty\fR.  If you are
751 connected via 14.4k modem, but the terminal server you are connected to
752 connects to the computer a 9600 baud, you want to set your speed as 9600
753 baud.  The special baud rate of 38400 or \fBextb\fR is used to indicate that
754 you have a very-high speed connection, such as a memory mapped console or an
755 X-window terminal emulator.  If you can't use \fBstty\fR to set the actual
756 throughput (perhaps because of a modem communicating with the computer at a
757 different rate than it's communicating over the phone line), you can put a
758 numeric value in the \fBBAUD\fR environment variable instead (use \fBsetenv
759 BAUD 9600\fR for csh or \fBBAUD=9600; export BAUD\fR for sh).
760
761 The \fBSHELL\fR or \fBEXECSHELL\fR environment variable must be set to the
762 full pathname of a shell executable that accepts the \-i (interactive) and
763 \-c (run a command) arguments of the Korn Shell; otherwise, \fB/bin/sh\fR
764 is used.
765
766 The \fBTERM\fR environment variable must be set to the type of terminal
767 you're using.  If the size (number of lines/columns) of your terminal is
768 different from what is reported in the TERMCAP or TERMINFO entry, you can
769 set this with the \fBstty rows nn cols nn\fR command, or by setting the
770 \fBLINES\fR and \fBCOLUMNS\fR environment variables.
771
772 The \fBxterm\-xfree86\fR terminal allows automatic entering and leaving
773 of the bracketed paste mode.
774
775 The \fBJOETERM\fR environment variable may be set to override the regular
776 \fBTERM\fR environment variable for specifying your terminal type.
777
778 JOE uses two character maps for its operation: the terminal I/O character
779 map, which determines how characters are sent to the terminal and whether
780 the %a/%A message specifiers use Unicode, and the file encoding, which can
781 be specified per file using the \fB\-encoding\fR option and changed with
782 the \fB^T E\fR command, and which defaults to the terminal I/O character
783 map, which, in turn, is determined from the current locale, if the system
784 supports such, otherwise the \fBLC_ALL\fR, \fBLC_CTYPE\fR and \fBLANG\fR
785 environment variables (if they contain a period, only the part after it
786 and before an optional "at sign" is used); on cygwin32 before 1.7.2, the
787 codepage is used instead if the POSIX locale environment variables are
788 empty; the environment variable \fBJOECHARMAP\fR can be used to manually
789 force one overriding all methods described above, and can be used together
790 with \fB\-encoding\fR to specify a different default file character map.
791
792 JOE normally expects that flow control between the computer and your
793 terminal to use ^S/^Q handshaking (I.E., if the computer is sending
794 characters too fast for your terminal, your terminal sends ^S to stop the
795 output and ^Q to restart it).  If the flow control uses out-of-band or
796 hardware handshaking or if your terminal is fast enough to always keep up
797 with the computer output and you wish to map ^S/^Q to edit commands, you can
798 set the environment variable \fBNOXON\fR to have JOE attempt to turn off
799 ^S/^Q handshaking.  If the connection between the computer and your terminal
800 uses no handshaking and your terminal is not fast enough to keep up with the
801 output of the computer, you can set the environment variable \fBDOPADDING\fR
802 to have \fBJOE\fR slow down the output by interspersing PAD characters
803 between the terminal screen update sequences.
804
805 .SH Filenames
806 Wherever JOE expects you to enter a file name, whether on the command line
807 or in prompts within the editor, you may also type:
808
809 .IP \fB!command
810 Read or write data to or from a shell command.  For example,
811 use \fBjoe '!ls'\fR to get a copy of your directory listing to edit or from
812 within the editor use \fB^K D !mail jhallen@world.std.com\fR to send the
813 file being edited to me.
814
815 .IP \fB>>filename
816 Use this to have JOE append the edited text to the end of the file
817 "filename."
818
819 .IP \fBfilename,START,SIZE
820 Use this to access a fixed section of a file or device.  \fBSTART\fR and
821 \fBSIZE\fR may be entered in decimal (ex.: 123) octal (ex.: 0777) or
822 hexadecimal (ex.: 0xFF).  For example, use \fBjoe /dev/fd0,508,2\fR to edit
823 bytes 508 and 509 of the first floppy drive in Linux.
824
825 .IP \fB\-
826 Use this to get input from the standard input or to write output to the
827 standard output.  For example, you can put joe in a pipe of commands:
828 \fBquota \-v | joe \- | mail root\fR, if you want to complain about your low
829 quota.
830
831
832 .SH The\ joerc file
833 \fB^T\fR options, the help screens and the key-sequence to editor command
834 bindings are all defined in JOE's initialisation file.
835 If you make a copy of this file (@joeinitcopy@) to \fB$HOME/.joerc\fR,
836 you can customise these settings to your liking.
837 The syntax of the initialisation file should be fairly obvious,
838 and there are further instruction in it.
839
840 .SH Acknowledgments
841 JOE was written by Joseph H. Allen.
842 If you have bug reports or questions, e-mail them to jhallen@world.std.com.
843 Larry Foard (entropy@world.std.com) and Gary Gray (ggray@world.std.com)
844 also helped with the creation of JOE.
845 Thorsten "mirabilos" Glaser (tg@mirbsd.org) created JUPP, and the 16-bit MS-DOS
846 version of JUPP 2.8 was compiled by Andreas Totlis (atotlis@t-online.de).
847
848 .SH Bugs
849 This manual page describes only the JOE flavour; documentation for JUPP is
850 especially missing.