joe-3.1jupp31.tgz (die zweite Klappe…)

[alioth/jupp.git] / README

This is Joe's Own Editor.  See the INFO file if you don't know what this is.

Well actually, this is jupp, Programmers' Editor, the Editor which sucks less.
It's got a Launchpad page, too: https://launchpad.net/jupp
Although, you’re encouraged to ask stuff on IRC in #MirBSD on irc.freenode.net
(Port 6697 SSL, 6667 insecure) or on miros-discuss@mirbsd.org (public mailing
list, but do not send mail to junk@mirbsd.org, that's a spamtrap).

=-=-=-=-=-=-=-=-=-=-=-=
Installation procedure
=-=-=-=-=-=-=-=-=-=-=-=

  Joe uses automake and autoconf suites to build itself. Type:

        ./configure
        make

At this point you can try JOE without fully installing it by typing "./joe".
However, you need to copy a few files into your home directory first:

        # This is required for JOE to start:
        cp joerc ~/.joerc

        # The following are needed if you want syntax highlighting to work:
        mkdir ~/.jupp
        mkdir ~/.jupp/syntax
        cp syntax/*.jsf ~/.jupp/syntax/

Otherwise you need to do a real install, which generally requires root
privileges:

        su root
        make install

This will copy the executables to /usr/local/bin and runtime files to
/usr/local/etc.  After installation, you can then try it by typing "joe".

=-=-=-=-=-=-=-=-=-=-=-=
Verify the installation
=-=-=-=-=-=-=-=-=-=-=-=

A number of features should be tested:

Shell windows:
--------------

Please test the installation by trying the shell command: ^K '  A shell
prompt should appear in the window and you should be able to type "ls".  If
not, two things could be broken:

   JOE could not open a pseudo terminal (pty), which is unfortunately one of
the two most incompatible parts of the UNIX API.  Take a look at tty.c-
there are several methods for opening the pty: mess with the "#ifdefs" until
you find a method which works (and send a bug report for your operating
system).

   The SHELL environment variable is not set or exported (Cygwin has this
problem).  Put:

        export SHELL=/bin/bash
    or  setenv SHELL /bin/bash

   In you .profile or .cshrc file and send mail to the Cygwin mailing list
so that they fix this problem.

Process groups:
---------------

Once you have a shell window open, try to suspend JOE: ^K Z.  Then resume
it: "fg".  The shell window should still be active.  If not, your operating
system is not handling process groups properly.  Look for the setsid() or
setprgp() system calls in tty.c (this is the other most incompatible part of
the UNIX API).  Currently process groups appear to be broken in Cygwin (so
if you suspend JOE, any shells get killed).

Resize windows:
---------------

Try resizing the terminal emulator window: JOE should resize itself to
properly fit.  If this doesn't work, either ttgtsz() (in tty.c) is not
reading the size properly, or the SIGWINCH signal is not being received
by JOE (the handler is winchd() in tty.c).

JOE requires a certain minimum window size, which differs between the
functions needing it. Do not complain if your window is *much* too small.

Baud rate:
----------

JOE cares about the baud rate as reported by "stty":

        38400 or above:         Joe does not issue scrolling commands

        9600 - 19200:           Joe issues scrolling commands, but does
                                not delay.

        0 - 4800:               Joe defeats output buffering by sleeping
                                after every chunk of data is sent to the
                                screen, by the amount of time that the data
                                should take to get there as determined by
                                the baud rate.  This allows typeahead to
                                interrupt the screen update process: If you
                                hit Page Down 100 times, only the final
                                contents of the screen get sent to the
                                terminal, otherwise you have to wait for all
                                100 pages to get to the screen before you
                                can do anything.

Sleeping should really be used at 9600 baud, but too many systems use 9600
as the default speed for terminal emulators.  If you are using a real serial
link to a real terminal, you may want to adjust these thresholds: search for
"9600" in tty.c.

Padding:
--------

Ideally either terminals can keep up with the baud rate or they backpressure
the computer using hardware flow control (RTS and CTS pins on RS-232
connector).

If not, there are two options, both bad:

Use XON/XOFF (^S/^Q) flow control: this works, but ^S causes the screen to
freeze, which freaks out new users, plus ^S is the search key in "jmacs".

Use padding: the termcap database indicates how long each command should
take.  If padding is enabled, JOE will send enough NUL characters after each
command to account for this time.  You need set the DOPADDING environment
variable or use the -dopadding option.

You should just buy a modern terminal :-)

=-=-=-=-=-=-=-=-=-=-=-=-=-
Common ./configure options
=-=-=-=-=-=-=-=-=-=-=-=-=-

Here are some common ./configure options:

  To have "make intall" install JOE into your home directory:

        ./configure --prefix=$HOME

        The executables will end up in $HOME/bin and the runtime
        files will end up in $HOME/etc.  You need to have $HOME/bin in
        your path for this to work.


  For other install options:

        ./configure --help


  To force JOE to use /etc/termcap file using its built-in termcap file parser
  (which is useful if you want to compile JOE so that it doesn't depend on any
  libraries other than libc):

        ./configure --disable-curses --disable-termcap

  (--disable-termcap prevents JOE from using the termcap emulation functions
   in the -ltermcap library.  --disable-curses prevents JOE from using the
   termcap emulation functions in the -lcurses library).

  Otherwise, JOE tries to use the terminfo database via termcap
  emulation routines: see man tgetent, tgetstr, tgoto, etc.  (JOE has its
  own implementation of "curses", so curses is not required except to get
  access to the terminfo database).

  Note that even if you don't have an /etc/termcap file, JOE will run: it
  will assume that the terminal is "ANSI" (but you need to compile it this
  way for it to be able to use the builtin ANSI termcap entry).


=-=-=
Usage
=-=-=

USAGE:  joe filename [filename ...]

  Optionally precede each filename with +nnn to start at specified line number.

  Options:

 -mid           Cursor is recentered when scrolling is necessary
 -marking       Text between ^KB and cursor is highlighted (use with -lightoff)
 -asis          Characters 128 - 255 shown as-is
 -force         Force final newline when files are saved
 -nobackups     If you don't want backup files to be created
 -lightoff      Turn off highlighting after block copy or move
 -exask         ^KX always confirms file name
 -beep          Beep on errors and when cursor goes past extremes
 -nosta         Disable top-most status line
 -keepup        %k and %c status line escape sequences updated frequently
 -pg nnn        No. lines to keep for PgUp/PgDn
 -csmode        ^KF after a previous search does a ^L instead
 -backpath path Directory to store backup files
 -nonotice      Disable copyright notice
 -noxon         Attempt to turn off ^S/^Q processing
 -orphan        Put extra files given on command line in orphaned buffers
                instead of in windows
 -dopadding     Output pad characters (for when there is no tty handshaking)
 -lines nnn     Set no. screen lines
 -baud nnn      Set baud rate for terminal optimizations
 -columns nnn   Set no. screen columns
 -help          Start with help on
 -skiptop nnn   Don't use top nnn lines of the screen

  Options before each file name:

 -wordwrap              Wordwrap
 -autoindent            Auto indent
 -overwrite             Overtype mode
 -lmargin nnn           Left margin
 -rmargin nnn           Right margin
 -tab nnn               Tab width
 -indentc nnn           Indentation character (32 for space, 9 for tab)
 -istep nnn             Number of indentation columns
 -french                One space after '.', '?' and '!' for wordwrap
                        and paragraph reformat instead of two.  Joe
                        does not change the spacing you give, but
                        sometimes it must put spacing in itself.  This
                        selects how much is inserted.
 -spaces                TAB inserts spaces instead of tabs.
 -linums                Enable line numbers on each line
 -rdonly                File is read-only
 -crlf                  File is uses CR-LF at ends of lines (MS-DOS files)

        These options can also be set in the joerc file.  The NOXON, LINES,
COLUMNS, DOPADDING and BAUD options can also be set with environment
variables.

        The JOETERM environment variable can be set to override the TERM
environment variable.

** IMPORTANT **

The baud rate must be correctly set or either typeahead will not interrupt
the screen update and scrolling wont be used or there will be annoying
delays in the screen update.  If you can't set the baud rate correctly with
'stty', give a numeric value in the environment variable 'BAUD' or to the
command line options '-baud'.

The baud rate '38400' or 'extb' means infinite to joe.  Use it for X windows
and hardware console ttys.  No delays will be generated and scrolling will
not be used.

The baud rate '19200' or 'exta' means that joe will use scrolling, but will
not delay.

Use the LINES and COLUMNS environment variables or the -lines and -columns
command line options if you need the terminal size to be different than
whatever the termcap entry or stty reports.

Since most people use terminal emulators, JOE does not send out pad
characters.  If you're using a real terminal and the padding matters, set
the environment variable DOPADDING or give the command line option
-dopadding.

If you want joe to try to disable ^S/^Q processing, set the environment
variable NOXON or command line option -noxon.

A termcap file is included with JOE.  You might consider updating your own
termcap file with the entries in it, particularly if you use ANSI/VT100ish
terminals.  JOE understands some capabilities which are not usually supplied
in normal termcap (see below).

                                 VARIATIONS
                                 =-=-=-=-=-

Termcap/Terminfo
=-=-=-=-=-=-=-=-

        JOE prefers to use the termcap terminal capability database.  It
attempts to find this file in:

        $HOME/.termcap          Personal .termcap in your home directory
        /usr/local/lib/termcap  Joe's termcap file
        /etc/termcap            Normal system termcap file

        Joe copies its own termcap file to /usr/local/lib/termcap (or
wherever the system-wide joerc file is going to go) when 'make install' is
run.

        Termcap is better than terminfo because it is a more open standard.
Programs can directly access the termcap database and future versions of
terminfo may require programs to use curses.  The only argument in
terminfo's favor is that it is faster than termcap.  To fix this problem,
JOE will use a termcap index file if it exists and if it is up to date.

        This is the procedure to make the termcap index file:

                make termidx
                ./termidx </etc/termcap >/etc/termcap.idx

        The /etc/termcap.idx is a text file which you can look at if you're
curious.

        JOE supports the GNU extensions to the termcap language and also
understands several new capabilities:

                AL DL IC DC RI LE UP DO SF SR

                        Versions of the standard capabilities which accept
                        an argument.  For example, RI with and argument of
                        7 should move the cursor 7 positions to the right.

                rr

                        Set this flag if the cursor is restricted to move
                        only within the scrolling regions.  This is an optional
                        mode on vt220s and several clones assume that this
                        mode is always on.

                cV

                        Like the 'cv' capability, but the cursor goes to the
                        beginning of the specified line.  Like 'ESC [ n H' in
                        ansi/vt100.

JPICO
=-=-=

If you want JPICO to act more like real pico when you hit ^X (I.E., to have
it ask before saving), change the line:

exsave          ^X              Exit

to:

ask,query,lose,query,abortbuf   ^X      Exit

BROKEN TERMINALS
=-=-=-=-=-=-=-=-
"Joe does not update the screen correctly in Procomm"
"My Xenix console does not scroll correctly"

Old versions of Procomm, many other DOS comm programs and nearly every
PC-UNIX console (with the exception of Linux) does not emulate VT100s
properly.  There are usually one or more problems:

        1) Tabs are destructive

        2) Tabs are destructive when inverse mode is set

        3) Scrolling regions are not supported

        4) Cursor positioning is scrolling region relative instead of
           screen relative.

        5) Some other program set the tab-stops to something other than
           one tab stop every 8 columns.

        6) The erase commands (ESC [ J and ESC [ K) fill with inverse
           video blanks instead of plain blanks when inverse mode is set.

        7) Backspace is destructive

Procomm 2.3 works fine- but make sure you have DEC VT100 selected, not 'ANSI
BBS' and also that backspace (BS) is set to 'non-destructive'.  If you must
use an old version of Procomm, try using the 'ansisys' or 'nansisys' termcap
entry.  Unix consoles usually do not have scrolling regions, but instead
have insert and delete line commands.  The 'fansi' entry and ones derived
from it will work correctly.  These termcap entries are provided in the
termcap file which came with joe.  If at all possible have your sysadmin
install these entries in '/etc/termcap'.  Even if your system normally uses
the terminfo database, you can copy Joe's termcap file into
/etc/termcap.

"I don't have root access and can't update the system's termcap file.  How
 do I get only Joe to use a different termcap entry?"

"My system uses terminfo.  How do I get only Joe to use a different termcap
 entry?"

What you should do is copy the termcap file which is provided with joe into
'.termcap' of your home directory.  Now suppose you want Joe to use the
'fansi' termcap entry:

If you use csh or tcsh, place this in your .cshrc file:

        setenv JOETERM fansi

If you use sh, ksh or bash, place this in your .profile file:

        JOETERM=fansi; export JOETERM

"I don't have root access and can't update the system's termcap file.  How
 do I get all of my programs to use one of Joe's termcap entries?"

Again, copy termcap into '.termcap' in your home directory, but set the
environment variables like this:

        setenv TERMCAP $HOME/.termcap
        setenv TERM fansi

"My system uses terminfo... how do I get all of my programs to use one of
 Joe's termcap entries?"

First, compile joe for terminfo.  You then have to 'tic' the terminfo
version of joe's termcap file into your account.  These are the commands for
doing this:

        1)      cd
        2)      mkdir .info
        3)      setenv TERMINFO $HOME/.info

                (or

                TERMINFO=$HOME/.info; export TERMINFO

                if you use bash, sh or ksh)

        4)      tic joe/terminfo

Then put the 'setenv TERMINFO $HOME/.info' line into your .login file or
'TERMINFO=$HOME/.info; export TERMINFO' in your .profile.  Now all of your
programs should look up the 'TERM' in your own personal terminfo database.

USING JOE IN A SHELL SCRIPT
=-=-=-=-=-=-=-=-=-=-=-=-=-=

Joe used to use /dev/tty to access the terminal.  This caused a problem with
idle-session killers (they would kill joe because the real tty device was
not being accessed for a long time), so now joe only uses /dev/tty if you
need to pipe a file into joe, as in:  echo "hi" | joe -

If you want to use joe in a shell script which has its stdin/stdout
redirected, but you don't need to do 'joe -', you should simply redirect
joe's stdin/stdout to /dev/tty:

        joe filename  </dev/tty >/dev/tty

___________________________________________________________________
$MirOS: contrib/code/jupp/README,v 1.6 2017/01/11 22:04:31 tg Exp $