This documentation should go elsewhere, but I haven't gotten around to it yet. UTF-8 ----- JOE now handles two classes of character sets: UTF-8 and byte coded (like ISO-8859-1). It can not yet handle other major classes such as UTF-16 or GB2312. There are other restrictions: character sets must use LF (0x0A) or CR-LF (0x0D - 0x0A) as line terminators, space must be 0x20 and tab must be 0x09. Basically, the files must be UNIX or MS-DOS compatible text files. This means EBCDIC will not work properly (but you would need to handle fixed record length lines anyway) and character sets which use CR terminated lines (MACs) will not yet work. The terminal and the file can have different encodings. JOE will translate between the two. Currently, one of the two must be UTF-8 for translation to work. The character set for the terminal and the default character set assumed for files is determined by the 'LC_ALL' environment variable (and if that's not set, LC_CTYPE and LANG are also checked). For example, if LC_ALL is set to: de_DE Then the character set will be ISO-8859-1. If LC_ALL is set to: de_DE.UTF-8 The character set will UTF-8. Hit ^T E to change the coding for the file. Hit at this prompt to get a list of available codings. There are a number of built-in character sets, plus you can install character sets in the ~/.joe/charmaps and /usr/local/etc/joe/charmaps directories. Check: /usr/share/i18n/charmaps for example character set files. Only byte oriented character sets will work. Also, the file should not be gzipped (all of the charmap file in /usr/share/i18n/charmaps on my computer were compressed). The parser is very bad, so basically the file has to look exactly like the example one in /usr/local/etc/joe/charmaps. You can hit ^K to see the current character set. You can hit ` x to enter a Unicode character if the file coding is UTF-8. Programming ----------- Try ^K , and ^K . These keys select the current block (based on indentation) and shift it left or right by the -istep and -indentc. Hit Ctrl-G to jump between matching delimiters. This works on word delimiters for languages like Pascal and Verilog which use begin...end to delimit blocks. If a word is not known, Ctrl-G starts a search with the word moved into the search prompt. Selecting blocks ---------------- The "classic" way is to hit ^K B at the beginning and ^K K at the end. These set pointers called markb and markk. Once these are set you can jump to markb with ^[ b and jump to markk with ^[ k. New way: hit Ctrl-rtarw (right arrow) to start selecting rightward. Each time you hit Ctrl-rtarw, the block is extended one more to the right. This uses a simple macro: "begin_marking,rtarw,toggle_marking". Unfortunately, there is no standard way to get the keysequence given by the terminal emulator when you hit Ctrl-rtarw. Instead you have to determine this sequence yourself and enter it directly in the joerc file. Some examples are given for xterm and gnome-terminal. Hit ` rtarw within JOE to have the sequence shown on your screen. Note that Putty uses ^[ ^[ [ C which will not appear with ` rtarw (also ^[ ^[ is set book mark, so you need to unbind it to do this in Putty). Also you can hit Ctrl-delete to cut and Ctrl-insert to paste if the sequence for these keys are known. Xterm Mouse support ------------------- Use the -mouse option to enable xterm mouse support. When enabled, you can position the cursor or select text with the mouse. Unfortunately, text selected this way is not paste-able to other X windows. However, when xterm mouse support is enable you can use Shift-left-click and Shift-middle-click for normal Xterm select and paste. Shell Windows ------------- If you use Bash, you can hit: ` UP-ARROW and ` DOWN-ARROW to scroll through Bash's history buffer. Other keys work as well: try ` A to go to beginning of line or ` E to go to end of line. Unfortunately JOE only emulates a dumb terminal, so you have to use a lot of imagination to do any editing beyond hitting backspace. In general, any character quoted with ` is sent to the shell. Also sent to the shell: TAB, Backspace, Enter, ^C and ^D. Macros ------ A macro is a comma separated list of commands or named macros. When the macro is executed, each command is executed until either the end of the list is reached, or one of the commands fails (non-zero return value from the command). Failed commands beep if you have beeps enabled (^T B). Macro don't stop modifier ------------------------- Sometimes, you expect commands to sometimes fail, but want the rest of the commands in the list to be executed anyway. To mark a command which is allowed to fail, postfix it with '!'. For example, here a macro which hits down page in the window above: prevw,pgdn!,nextw If prevw fails, the macro is aborted as usual. Even if pgdn fails (already at end of buffer), nextw will be executed so that the cursor is returned to the original window. Macro repeat argument modifiers ------------------------------- Repeat arguments can be specified with ^K \. When a command is executed with a repeat argument, it is repeatedly executed the specified number of times. If the repeat argument is negative, an opposite command (if one exists) is executed instead. For example, if you repeat "rtarw" -3 times, "ltarw" will be repeated 3 times. If a negative argument is given for a command which does not have an opposite, the repeat argument is ignored. Normally, if a repeat argument is specified for a macro, the macro is simply repeated the given number of times. If a negative argument is given, the argument is ignored. Sometimes you want to allow negative arguments for macros and have their behavior modified. To do this, postfix each command within the macro which should be switched to its opposite for negative arguments with '-'. For example, here is the page down other window macro: prevw,pgdn-!,nextw Now if you execute this with an argument of -2, it will be repeated twice, but pgup will be executed instead of pgdn. (not that several postfix modifiers can be placed after each command). Sometimes when a repeat argument is given to macro, you want only one of the commands in the list to be repeated, not the entire macro. This can be indicated as follows: prevw,pgdn#!,nextw If this is executed with an argument of 2, prevw is executed once, pgdn is executed twice, and nextw is executed once. Finally, even more complex semantics can be expressed with the "if" command: if~,"arg<0",then, ltarw, else, rtarw, endif When the macro is executed, the "arg" math variable is set to the given repeat argument. The "argset" variable is set to true if the user set an argument, even if it's 1. If no argument was given, argset is false. If any command in the list is postfixed with ~ (if above), the macro is not repeated, even if there is an argument. 'arg' is still set to the given repeat count, however. 'psh'/'query' interaction ------------------------- The 'psh' command saves the ^KB and ^KK positions on a stack. When the macro completes, (or when the 'pop' command is called) the positions are restored. The 'query' command suspends macro execution until the current dialog is complete. It also suspends the automatic 'pop' which happens at the end of a macro- so if the macro ends in a dialog you often want to call 'query' to prevent the ^KB ^KK positions from being restored too early. Hex edit mode ------------- When this mode is selected (either put -hex on the command line, or look for "Hex edit mode" after hitting ^T), the buffer is displayed as a hex dump, but all of the editing commands operate the same way. It is most useful to select overtype mode in conjunction with hex dump (hit ^T T). Then typing will not insert. - To enter the hex byte 0xF8 type ` x F 8 - You can use ^KC to copy a block as usual. If overtype mode is selected, the block will overwrite the destination data without changing the size of the file. Otherwise it inserts. - Hit ESC x byte , to jump to a particular byte offset. Hex values can be entered into this prompt like this: 0x2000. - Search, incremental search, and search & replace all operate as usual.