--- a
+++ b/docs/HINTS
@@ -0,0 +1,210 @@
+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.