[CS-FSLUG] HOWTO: Configuring Joe (long)

[Ed Hurst]

Written for usual semi-clueless audience....



                         How to Customize Joe
                      Adding Win-esque Keystrokes
                               Ed Hurst
                             21 June 2004

=======================================================================

Sometimes the best applications are found on the Unix/Linux console. If
one were to assume the standards I've already published for plain text
files <http://ed.asisaid.com/newestyle.txt> then one of the best
applications for adhering to that standard is Joe (Joe's Own Editor).
This tutorial was written in Joe, of course. Pleae note that I follow
the convention here of setting examples off from the left margin.

Many long-time computer users love Joe because they can resurrect their
old WordStar keystrokes and get a lot of work done quickly. I never
used WordStar; I love Joe because it permits all the formatting and
editing features I desire. Better yet, it can be customized to allow
each user to include their own keystrokes. Yes, I admit I've been
deeply tainted by the DOS/Win pattern of keystrokes. Most of the
computer users in the world are in the same boat, so I'm hardly alone.
I find it annoying that each text editor I've tried in Unix/Linux has
its own unique keystrokes. Rather than learn a whole raft of different
and confusing command sequences for each one, I've settled on a few,
and Joe is my favorite, primarily because I can teach Joe how to behave
to suit me.

Much of what follows is based on the work of Anne Baretta:

   http://www.ibb.net/~anne/keyboard.html

and the good folks on the Joe mailing list.

Basic Theory: You probably know that there is nothing inherent in the
signals produced by your keyboard that puts out this or that character
or code from the same key on every keyboard throughout the world.
Otherwise, folks with non-English alphabets couldn't use computers in
their own lanaguage. In Unix/Linux we run the keyboard output through
an interpreter before it hits the application or the X server.
Normally, we establish that interpreter during the installation of our
OSs when we select our langaguage and keyboard layout. For some
applications, we have to make special adjustments in various config
files to change their default behavior. Joe is one of the few that
knows how to read those codes directly, and you can tell Joe what they
should mean.

For example, the F-keys. By default, none of them mean anything in
Joe. If you are working in a console (no GUI) or in a terminal emulator
(Konsole, XTerm, RxVT, Gnome-Terminal, etc.) there is a distinct code
being transmitted, and we can capture that code with characters on
screen. Simply type CTRL+V (for the clueless, that means hold down the
CTRL key and then hit V). The next keystroke or combination you type
will display a code that Joe can read. It will not work for a sequence,
but only for a single. Let's try the F1 key:

   ^[OP

is what you will see in most cases. Here's what that means:

   ^[ = "escape" ("Hey, we're changing modes here!")

   O P = the specific code Joe can read

Okay, so what do we do with this? You will need to get a copy of the
Joe config file for your own home directory. It will be named "joerc"
on every system I know about, and you can usually find it with the
'locate' command. When you find it, copy it to your home directory:

   cp /path/to/system/config/joerc ~/

Open your new 'joerc' in any text editor. For now, ignore all the stuff
at the top, and slide on down a ways until you start seeing the names
of some odd commands set against the left margin, with another column
that shows keystrokes in codes similar to what we saw above:

   pgdn            .kN             Screen down
   pgdn            ^V
   pgdn            ^[ [ 6 ~
   pgup            .kP             Screen up
   pgup            ^U
   pgup            ^[ [ 5 ~

Notice what comes by default in the config file -- both the 'pgup' and
'pgdn' commands are listed several times, and one entry for each
includes one of those odd sequences that start with "^[" (escape
sequence) and end with a couple of other codes. The third column, if
there's anything there, explains in plain English what the command
does. By the way, if you read above in the 'joerc' file you'll find
that the ".kx" business represents the "grey keys" or numeric keypad on
older keyboards. You'll also learn that Joe understands some of the
F-keys already, but none are used. Note that the caret "^" usually
means the CTRL key. Hitting CTRL+[ or ^[ is the same as hitting the ESC
key.


                    Now, for the rest of the story

What follows are the keystrokes I have added, so that Joe is
comfortable for me. Explainations are under each example. You are
advised to check each keystroke combination in the terminal or terminal
emulator you will be using. RxVT is different from XTerm, for example.
Konsole will ignore some combinations, like CTRL+HOME. Notice that the
codes that appear on your console output must be spaced out after the
initial escape sequence "^[". Just follow the examples below. Insert
your custom commands close to where you find similar commands. Keep
this in mind: Joe tries to parse everything that is set against the
left column. If Joe is confused by it, you'll have an error when you
try to start it. Simply move the offending line one space right, and
Joe will ignore it.

   :def capit filt,"tr a-z A-Z"
   :def uncapit filt,"tr A-Z a-z"

These define two macros so that I can easily capitalize anything
highlighted, or uncapitalize as well. They appear as the commands
"capit" and "uncapit" later.

   spellfile   .k7

I use F7 to start the spell checker (entire file; different command for
just one word).

   dnslide     ^[ [ 1 ; 2 B

   upslide     ^[ [ 1 ; 2 A

SHIFT+DOWN will scroll the screen downward, leaving the cursor where it
is. Similar command for scrolling upward: SHIFT+UP

   blkcpy          .k8

   blkmove         .k9

F8 will copy a highlighted block to where the cursor sits. F9 will move
the block.

   bof      ^[ [ 1 ; 5 H

   eof      ^[ [ 1 ; 5 F

CTRL+HOME takes you to the beginning of file and CTRL+END takes you to
the end.

   capit           .k1
   capit           ^K 1
   uncapit         .k2
   uncapit         ^K 2

My predefined marcros for capitalization and uncapitalization are now
linked to F1 and the sequence CTRL+K, 1 for capit; lower case changes
are linked to F2 and CTRL+K, 2.

   center          .k4

Center a line of text with the single keystroke F4.

   delch           ^[ [ 3 ~

Some Unix/Linux systems cling tenaciously to the ancient meaning of the
DEL key, which is not what most of us expect. This will insure we
delete the character under the cursor, and pull the remaining text
left. The cursor does not move; it devours in place, pulling everything
on its right and below.

   deleol          ^J

becomes

   deleol          ^Q ^J

because I use CTRL+J for something else. I never use this command in
Joe, anyway.

   fmtblk          ^J

CTRL+J will now reformat the current paragraph, so that the right end
of each line falls within my specified range (72 characters), tries to
remove double spaces between words and sentences (read the top of the
joerc file), and performs all sorts of other complex changes.
Experiment and you will see.

   bol     ^[ [ H

   eol     ^[ [ F

This insures that the HOME and END keys take you to the beginning and
end of the current line, respectively.

   exsave          .k;

   save            .F1

F10 will save the file and close it. F11 will save but continue
editing, or give you the option of saving to a new filename.


   markb           .k5

   markk           .k6

F5 will begin the highlighting, and F6 will close it. You must start at
the upper left of your block, or Joe will get confused.

   mode,"T"        .kI

Hitting the INSERT key will toggle between 'insert mode' and 'overtype
mode'.

   nextword        ^[ [ 1 ; 5 C

   prevword        ^[ [ 1 ; 5 D

CTRL+RIGHT takes you to the next word, CTRL+LEFT the previous word.


At the top of the file are two sections on setting general options.
Read them and experiment for yourself. Here are the options I set for
files ending in ".txt" --

   *.txt
   -wordwrap
   -rmargin 72
   -tab 3
   -french
   -spaces

This tells Joe (in sequence) to automatically line-wrap any thing
extending beyond the right margin, which margin is 72, that tabs are 3
characters wide, that I don't want double spaces between sentences, and
that I want tabs to be spaces, not real tabs.

When you are finished, be sure to save your 'joerc' as '.joerc'. Adding
a period to front of the file adds it to the collection of "dot-files"
in your home directory that are designed for configuration files, and
are normally not visible.

-- 
Ed Hurst
-----------
Software Freedom Day, 28 August 2004
Got Freedom?
http://www.softwarefreedomday.org/
---
[This E-mail scanned for viruses by Declude Virus]