jstar [global-options] [ [local-options] filename ]...
jmacs [global-options] [ [local-options] filename ]...
rjoe [global-options] [ [local-options] filename ]...
JOE also emulates several other editors. JSTAR is a close immitation of WordStar with many "JOE" extensions. JPICO is a close immitation of the Pine mailing system's PICO editor, but with many extensions and improvements. JMACS is a GNU-EMACS immitation. RJOE is a restricted version of JOE, which allowes you to edit only the files specified on the command line.
Although JOE is actually five different editors, it still requires only one executable, but one with five different names. The name of the editor with an "rc" appended gives the name of JOE's initialization file, which determines the personality of the editor.
JOE is free software; you can distribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. I have no plans for turning JOE into a commercial or share-ware product. JOE is available over the Internet from www.sourceforge.net/projects/joe-editor.
To start the editor, type joe followed by zero or more names of files you want to edit. Each file name may be preceeded by a local option setting (see the local options table which follows). Other global options, which apply to the editor as a whole, may also be placed on the command line (see the global options table which follows). If you are editing a new file, you can either give the name of the new file when you invoke the editor, or in the editor when you save the new file. A modified syntax for file names is provided to allow you to edit program output, standard input/output, or sections of files or devices. See the section Filenames below for details.
Once you are in the editor, you can type in text and use special control-character sequences to perform other editing tasks. To find out what the control-character sequences are, read the rest of this man page or type ^K H for help in the editor.
Now for some obscure computer-lore:
The ^ means that you hold down the Control key while pressing the following key (the same way the Shift key works for uppercase letters). A number of control-key sequences are duplicated on other keys, so that you don't need to press the control key: ESC will work in place of ^[, Del will work in place of ^?, Backspace will work in place of ^H, Tab will work in place of ^I, Return or Enter will work in place of ^M and Linefeed will work in place of ^J. Some keyboards may give you trouble with some control keys. ^_, ^^ and ^@ can usually be entered without pressing shift (I.E., try ^-, ^6 and ^2). Other keyboards may reassign these to other keys. Try: ^., ^, and ^/. ^SPACE can usually be used in place of ^@. ^\ and ^] are interpreted by many communication programs, including telnet and kermit. Usually you just hit the key twice to get it to pass through the communication program.
Once you have typed ^K H, the first help window appears at the top of the screen. You can continue to enter and edit text while the help window is on. To page through other topics, hit ^[, and ^[. (that is, ESC , and ESC .). Use ^K H to dismiss the help window.
You can customize the keyboard layout, the help screens and a number of behavior defaults by copying JOE's initialization file (usually /etc/joe/joerc) to .joerc in your home directory and then by modifying it. See the section joerc below.
To have JOE used as your default editor for e-mail and News, you need to set the EDITOR and VISUAL environment variables in your shell initialization file (.cshrc or .profile) to refer to JOE (joe usually resides as /usr/bin/joe).
There are a number of other obscure invocation parameters which may have to be set, particularly if your terminal screen is not updating as you think it should. See the section Environment variables below.
The following global options may be specified on the command line:
Each of these options may be specified in the joerc file as well. In addition, the NOXON, BAUD, LINES, COLUMNS and DOPADDING options may be specified with environment variables.
The JOETERM environment variable may be set to override the regular TERM environment variable for specifying your terminal type.
The following options may be specified before each filename on the command line:
These options can also be specified in the joerc file. They can be set depending on the file-name extension. Programs (.c, .h or .p extension) usually have autoindent enabled. Wordwrap is enabled on other files, but rc files have it disabled.
When you type characters into the editor, they are normally inserted into the file being edited (or appended to the file if the cursor is at the end of the file). This is the normal operating mode of the editor. If you want to replace some existing text, you have to delete the old text before or after you type in the replacement text. The Backspace key can be used for deleting text: move the cursor to right after the text you want to delete and hit Backspace a number of times.
Hit the Enter or Return key to insert a line-break. For example, if the cursor was in the middle of a line and you hit Return, the line would be split into two lines with the cursor appearing at the beginning of the second line. Hit Backspace at the beginning of a line to eliminate a line-break.
Use the arrow keys to move around the file. If your keyboard doesn't have arrow keys (or if they don't work for some reason), use ^F to move forwards (right), ^B to move backwards (left), ^P to move to the previous line (up), and ^N to move to the next line (down). The right and left arrow keys simply move forwards or backwards one character at a time through the text: if you're at the beginning of a line and you press left-arrow, you will end up at the end of the previous line. The up and down arrow keys move forwards and backwards by enough characters so that the cursor appears in the same column that it was in on the original line.
If you want to indent the text you enter, you can use the TAB key. This inserts a special control character which makes the characters which follow it begin at the next TAB STOP. TAB STOPS normally occur every 8 columns, but this can be changed with the ^T D command. PASCAL and C programmers often set TAB STOPS on every 4 columns.
If for some reason your terminal screen gets messed up (for example, if you receive a mail notice from biff), you can have the editor refresh the screen by hitting ^R.
There are many other keys for deleting text and moving around the file. For example, hit ^D to delete the character the cursor is on instead of deleting backwards like Backspace. ^D will also delete a line-break if the cursor is at the end of a line. Type ^Y to delete the entire line the cursor is on or ^J to delete just from the cursor to the end of the line.
Hit ^A to move the cursor to the beginning of the line it's on. Hit ^E to move the cursor to the end of the line. Hit ^U or ^V for scrolling the cursor up or down 1/2 a screen's worth. "Scrolling" means that the text on the screen moves, but the cursor stays at the same place relative to the screen. Hit ^K U or ^K V to move the cursor to the beginning or the end of the file. Look at the help screens in the editor to find even more delete and movement commands.
If you make a mistake, you can hit ^_ to "undo" it. On most keyboards you hit just ^- to get ^_, but on some you might have to hold both the Shift and Control keys down at the same time to get it. If you "undo" too much, you can "redo" the changes back into existence by hitting ^^ (type this with just ^6 on most keyboards).
If you were editing in one place within the file, and you then temporarily had to look or edit some other place within the file, you can get back to the original place by hitting ^K -. This command actually returns you to the last place you made a change in the file. You can step through a history of places with ^K - and ^K =, in the same way you can step through the history of changes with the "undo" and "redo" commands.
When you are done editing the file, hit ^K X to exit the editor. You will be prompted for a file name if you hadn't already named the file you were editing.
When you edit a file, you actually edit only a copy of the file. So if you decide that you don't want the changes you made to a file during a particular edit session, you can hit ^C to exit the editor without saving them.
If you edit a file and save the changes, a "backup" copy of that file is created in the current directory, with a ~ appended to the name, which contains the original version of the file.
If you type past the right edge of the screen in a C language or PASCAL file, the screen will scroll to the right to follow the cursor. If you type past the right edge of the screen in a normal file (one whose name doesn't end in .c, .h or .p), JOE will automatically wrap the last word onto the next line so that you don't have to hit Return. This is called word-wrap mode. Word-wrap can be turned on or off with the ^T W command. JOE's initialization file is usually set up so that this mode is automatically turned on for all non-program files. See the section below on the joerc file to change this and other defaults.
Aside for Word-wrap mode, JOE does not automatically keep paragraphs formatted like some word-processors. Instead, if you need a paragraph to be reformatted, hit ^K J. This command "fills in" the paragraph that the cursor is in, fitting as many words in a line as is possible. A paragraph, in this case, is a block of text separated above and below by a blank line.
The margins which JOE uses for paragraph formatting and word-wrap can be set with the ^T L and ^T R commands. If the left margin is set to a value other than 1, then when you start typing at the beginning of a line, the cursor will immediately jump to the left margin.
If you want to center a line within the margins, use the ^K A command.
Sometimes it's tiresome to have to delete old text before or after you insert new text. This happens, for example, when you are changing a table and you want to maintain the column position of the right side of the table. When this occurs, you can put the editor in over-type mode with ^T T. When the editor is in this mode, the characters you type in replace existing characters, in the way an idealized typewriter would. Also, Backspace simply moves left instead of deleting the character to the left, when it's not at the end or beginning of a line. Over-type mode is not the natural way of dealing with text electronically, so you should go back to insert-mode as soon as possible by typing ^T T again.
If you need to insert while you're in over-type mode, hit ^@. This inserts a single SPACE into the text.
Each character is represented by a number. For example, the number for 'A' is 65 and the number for '1' is 49. All of the characters which you normally see have numbers in the range of 32 - 126 (this particular arbitrary assignment between characters and numbers is called the ASCII character set). The numbers outside of this range, from 0 to 255, aren't usually displayed, but sometimes have other special meanings. The number 10, for example, is used for the line-breaks. You can enter these special, non-displayed control characters by first hitting ` and then hitting a character in the range @ A B C ... X Y Z [ ^ ] \ _ to get the number 0 - 31, and ? to get 127. For example, if you hit ` J, you'll insert a line-break character, or if you hit ` I, you'll insert a TAB character (which does the same thing the TAB key does). A useful control character to enter is 12 (` L), which causes most printers to advance to the top of the page. You'll notice that JOE displays this character as an underlined L. You can enter the characters above 127, the meta characters, by first hitting ^\. This adds 128 to the next (possibly control) character entered. JOE displays characters above 128 in inverse-video. Some foreign languages, which have more letters than English, use the meta characters for the rest of their alphabet. You have to put the editor in ASIS mode (described later) to have these passed untranslated to the terminal.
Most prompts record a history of the responses you give them. You can hit up and down arrow to step through these histories.
Prompts are actually single line windows with no status line, so you can use any editing command that you normally use on text within the prompts. The prompt history is actually just other lines of the same "prompt file". Thus you can can search backwards though the prompt history with the normal ^K F command if you want.
Since prompts are windows, you can also switch out of them with ^K P and ^K N.
Hit ^K SPACE to have JOE report the line number, column number, and byte number on the last line of the screen. The number associated with the character the cursor is on (its ASCII code) is also shown. You can have the line number and/or column number always displayed on the status line by setting placing the appropriate escape sequences in the status line setup strings. Edit the joerc file for details.
You can hit ^K D to save the current file (possibly under a different name from what the file was called originally). After the file is saved, you can hit ^K E to edit a different file.
If you want to save only a selected section of the file, see the section on Blocks below.
If you want to include another file in the file you're editing, use ^K R to insert it.
If you need to temporarily stop the editor and go back to the shell, hit ^K Z. You might want to do this to stop whatever you're editing and answer an e-mail message or read this man page, for example. You have to type fg or exit (you'll be told which when you hit ^K Z) to return to the editor.
Hit ^K F to have the editor search forwards or backwards for a text fragment (string) for you. You will be prompted for the text to search for. After you hit Return, you are prompted to enter options. You can just hit Return again to have the editor immediately search forwards for the text, or you can enter one or more of these options:
You can hit ^L to repeat the previous search.
A number of special character sequences may be entered as search text:
A number of special character sequences may also be given in the replacement string:
Suppose you have a list of addresses, each on a separate line, which starts with "Address:" and has each element separated by commas. Like so:
Address: S. Holmes, 221b Baker St., London, England
If you wanted to rearrange the list, to get the country first, then the city, then the person's name, and then the address, you could do this:
Type ^K F to start the search, and type:
to match "Address:", the four comma-separated elements, and then the end of the line. When asked for options, you would type r to replace the string, and then type:
To shuffle the information the way you want it. After hitting return, the search would begin, and the sample line would be changed to:
Address: England, London, S. Holmes, 221b Baker St.
If you want to move, copy, save or delete a specific section of text, you can do it with highlighted blocks. First, move the cursor to the start of the section of text you want to work on, and press ^K B. Then move the cursor to the character just after the end of the text you want to affect and press ^K K. The text between the ^K B and ^K K should become highlighted. Now you can move your cursor to someplace else in your document and press ^K M to move the highlighted text there. You can press ^K C to make a copy of the highlighted text and insert it to where the cursor is positioned. ^K Y to deletes the highlighted text. ^K W, writes the highlighted text to a file.
A very useful command is ^K /, which filters a block of text through a unix command. For example, if you select a list of words with ^K B and ^K K, and then type ^K / sort, the list of words will be sorted. Another useful unix command for ^K /, is tr. If you type ^K / tr a-z A-Z, then all of the letters in the highlighted block will be converted to uppercase.
After you are finished with some block operations, you can just leave the highlighting on if you don't mind it (of course, if you accidently hit ^K Y without noticing...). If it really bothers you, however, just hit ^K B ^K K, to turn the highlighting off.
You can use the ^K , and ^K . commands to shift a block of text to the left or right. If no highlighting is set when you give these commands, the program block the cursor is located in will be selected, and will be moved by subsequent ^K , and ^K . commands. The number of columns these commands shift by can be set through a ^T option.
You can hit ^K O within a window to create even more windows. If you have too many windows on the screen, but you don't want to eliminate them, you can hit ^K I. This will show only the window the cursor is in, or if there was only one window on the screen to begin with, try to fit all hidden windows on the screen. If there are more windows than can fit on the screen, you can hit ^K N on the bottom-most window or ^K P on the top-most window to get to them.
If you gave more than one file name to JOE on the command line, each file will be placed in a different window.
You can change the height of the windows with the ^K G and ^K T commands.
Macros allow you to record a series of keystrokes and replay them with the press of two keys. This is useful to automate repetitive tasks. To start a macro recording, hit ^K [ followed by a number from 0 to 9. The status line will display (Macro n recording...). Now, type in the series of keystrokes that you want to be able to repeat. The commands you type will have their usual effect. Hit ^K ] to stop recording the macro. Hit ^K followed by the number you recorded the macro in to execute one iteration of the key-strokes.
For example, if you want to put "**" in front of a number of lines, you can type:
^K [ ^A ** <down arrow> ^K ]
Which starts the macro recording, moves the cursor to the beginning of the line, inserts "**", moves the cursor down one line, and then ends the recording. Since we included the key-strokes needed to position the cursor on the next line, we can repeatedly use this macro without having to move the cursor ourselves, something you should always keep in mind when recording a macro.
If you find that the macro you are recording itself has a repeated set of key-strokes in it, you can record a macro within the macro, as long as you use a different macro number. Also you can execute previously recorded macros from within new macros.
For example, to delete the next 20 lines of text, type:
When rectangle mode is selected, over-type mode is also useful (^T T). When over-type mode is selected, rectangles will replace existing text instead of getting inserted before it. Also the delete block command (^K Y) will clear the selected rectangle with SPACEs and TABs instead of deleting it. Over-type mode is especially useful for the filter block command (^K /), since it will maintain the original width of the selected column.
For JOE to operate correctly, a number of other environment settings must be correct. The throughput (baud rate) of the connection between the computer and your terminal must be set correctly for JOE to update the screen smoothly and allow typeahead to defer the screen update. Use the stty nnn command to set this. You want to set it as close as possible to actual throughput of the connection. For example, if you are connected via a 1200 baud modem, you want to use this value for stty. If you are connected via 14.4k modem, but the terminal server you are connected to connects to the computer a 9600 baud, you want to set your speed as 9600 baud. The special baud rate of 38400 or extb is used to indicate that you have a very-high speed connection, such as a memory mapped console or an X-window terminal emulator. If you can't use stty to set the actual throughput (perhaps because of a modem communicating with the computer at a different rate than it's communicating over the phone line), you can put a numeric value in the BAUD environment variable instead (use setenv BAUD 9600 for csh or BAUD=9600; export BAUD for sh).
The TERM environment variable must be set to the type of terminal you're using. If the size (number of lines/columns) of your terminal is different from what is reported in the TERMCAP or TERMINFO entry, you can set this with the stty rows nn cols nn command, or by setting the LINES and COLUMNS environment variables.
JOE normally expects that flow control between the computer and your terminal to use ^S/^Q handshaking (I.E., if the computer is sending characters too fast for your terminal, your terminal sends ^S to stop the output and ^Q to restart it). If the flow control uses out-of-band or hardware handshaking or if your terminal is fast enough to always keep up with the computer output and you wish to map ^S/^Q to edit commands, you can set the environment variable NOXON to have JOE attempt to turn off ^S/^Q handshaking. If the connection between the computer and your terminal uses no handshaking and your terminal is not fast enough to keep up with the output of the computer, you can set the environment variable DOPADDING to have JOE slow down the output by interspersing PAD characters between the terminal screen update sequences.