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 <tab> <tab> 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 <space> 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 <Enter>, 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.