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