Initial revision
[alioth/jupp.git] / README
1 This is Joe's Own Editor.  See the INFO file if you don't know what this is.
2
3 =-=-=-=-=-=-=-=-=-=-=-=
4 Installation procedure
5 =-=-=-=-=-=-=-=-=-=-=-=
6
7   Joe uses automake and autoconf suites to build itself. Type:
8
9         ./configure
10         make
11
12 At this point you can try JOE without fully installing it by typing "./joe".
13 However, you need to copy a few files into your home directory first:
14
15         # This is required for JOE to start:
16         cp joerc ~/.joerc
17
18         # The following are needed if you want syntax highlighting to work:
19         mkdir ~/.joe
20         mkdir ~/.joe/syntax
21         cp syntax/*.jsf ~/.joe/syntax
22
23 Otherwise you need to do a real install, which generally requires root
24 privileges:
25
26         su root
27         make install
28
29 This will copy the executables to /usr/local/bin and runtime files to
30 /usr/local/etc.  After installation, you can then try it by typing "joe".
31
32 =-=-=-=-=-=-=-=-=-=-=-=
33 Verify the installation
34 =-=-=-=-=-=-=-=-=-=-=-=
35
36 A number of features should be tested:
37
38 Shell windows:
39 --------------
40
41 Please test the installation by trying the shell command: ^K '  A shell
42 prompt should appear in the window and you should be able to type "ls".  If
43 not, two things could be broken:
44
45    JOE could not open a pseudo terminal (pty), which is unfortunately one of
46 the two most incompatible parts of the UNIX API.  Take a look at tty.c-
47 there are several methods for opening the pty: mess with the "#ifdefs" until
48 you find a method which works (and send a bug report for your operating
49 system).
50
51    The SHELL environment variable is not set or exported (Cygwin has this
52 problem).  Put:
53
54         export SHELL=/bin/bash
55     or  setenv SHELL /bin/bash
56
57    In you .profile or .cshrc file and send mail to the Cygwin mailing list
58 so that they fix this problem.
59
60 Process groups:
61 ---------------
62
63 Once you have a shell window open, try to suspend JOE: ^K Z.  Then resume
64 it: "fg".  The shell window should still be active.  If not, your operating
65 system is not handling process groups properly.  Look for the setsid() or
66 setprgp() system calls in tty.c (this is the other most incompatible part of
67 the UNIX API).  Currently process groups appear to be broken in Cygwin (so
68 if you suspend JOE, any shells get killed).
69
70 Resize windows:
71 ---------------
72
73 Try resizing the terminal emulator window: JOE should resize itself to
74 properly fit.  If this doesn't work, either ttgtsz() (in tty.c) is not
75 reading the size properly, or the SIGWINCH signal is not being received
76 by JOE (the handler is winchd() in tty.c).
77
78 Baud rate:
79 ----------
80
81 JOE cares about the baud rate as reported by "stty":
82
83         38400 or above:         Joe does not issue scrolling commands
84
85         9600 - 19200:           Joe issues scrolling commands, but does
86                                 not delay.
87
88         0 - 4800:               Joe defeats output buffering by sleeping
89                                 after every chunk of data is sent to the
90                                 screen, by the amount of time that the data
91                                 should take to get there as determined by
92                                 the baud rate.  This allows typeahead to
93                                 interrupt the screen update process: If you
94                                 hit Page Down 100 times, only the final
95                                 contents of the screen get sent to the
96                                 terminal, otherwise you have to wait for all
97                                 100 pages to get to the screen before you
98                                 can do anything.
99
100 Sleeping should really be used at 9600 baud, but too many systems use 9600
101 as the default speed for terminal emulators.  If you are using a real serial
102 link to a real terminal, you may want to adjust these thresholds: search for
103 "9600" in tty.c.
104
105 Padding:
106 --------
107
108 Ideally either terminals can keep up with the baud rate or they backpressure
109 the computer using hardware flow control (RTS and CTS pins on RS-232
110 connector).
111
112 If not, there are two options, both bad:
113
114 Use XON/XOFF (^S/^Q) flow control: this works, but ^S causes the screen to
115 freeze, which freaks out new users, plus ^S is the search key in "jmacs".
116
117 Use padding: the termcap database indicates how long each command should
118 take.  If padding is enabled, JOE will send enough NUL characters after each
119 command to account for this time.  You need set the DOPADDING environment
120 variable or use the -dopadding option.
121
122 You should just buy a modern terminal :-)
123
124 =-=-=-=-=-=-=-=-=-=-=-=-=-
125 Common ./configure options
126 =-=-=-=-=-=-=-=-=-=-=-=-=-
127
128 Here are some common ./configure options:
129
130   To have "make intall" install JOE into your home directory:
131
132         ./configure --prefix=$HOME
133
134         The executables will end up in $HOME/bin and the runtime
135         files will end up in $HOME/etc.  You need to have $HOME/bin in
136         your path for this to work.
137
138
139   For other install options:
140
141         ./configure --help
142
143
144   To force JOE to use /etc/termcap file using its built-in termcap file parser
145   (which is useful if you want to compile JOE so that it doesn't depend on any
146   libraries other than libc):
147
148         ./configure --disable-curses --disable-termcap
149
150   (--disable-termcap prevents JOE from using the termcap emulation functions
151    in the -ltermcap library.  --disable-curses prevents JOE from using the
152    termcap emulation functions in the -lcurses library).
153
154   Otherwise, JOE tries to use the terminfo database via termcap
155   emulation routines: see man tgetent, tgetstr, tgoto, etc.  (JOE has its
156   own implementation of "curses", so curses is not required except to get
157   access to the terminfo database).
158
159   Note that even if you don't have an /etc/termcap file, JOE will run: it
160   will assume that the terminal is "ANSI" (but you need to compile it this
161   way for it to be able to use the builtin ANSI termcap entry).
162
163
164 =-=-=
165 Usage
166 =-=-=
167
168 USAGE:  joe filename [filename ...]
169
170   Optionally precede each filename with +nnn to start at specified line number.
171
172   Options:
173
174  -mid           Cursor is recentered when scrolling is necessary
175  -marking       Text between ^KB and cursor is highlighted (use with -lightoff)
176  -asis          Characters 128 - 255 shown as-is
177  -force         Force final newline when files are saved
178  -nobackups     If you don't want backup files to be created
179  -lightoff      Turn off highlighting after block copy or move
180  -exask         ^KX always confirms file name
181  -beep          Beep on errors and when cursor goes past extremes
182  -nosta         Disable top-most status line
183  -keepup        %k and %c status line escape sequences updated frequently
184  -pg nnn        No. lines to keep for PgUp/PgDn
185  -csmode        ^KF after a previous search does a ^L instead
186  -backpath path Directory to store backup files
187  -nonotice      Disable copyright notice
188  -noxon         Attempt to turn off ^S/^Q processing
189  -orphan        Put extra files given on command line in orphaned buffers
190                 instead of in windows
191  -dopadding     Output pad characters (for when there is no tty handshaking)
192  -lines nnn     Set no. screen lines
193  -baud nnn      Set baud rate for terminal optimizations
194  -columns nnn   Set no. screen columns
195  -help          Start with help on
196  -skiptop nnn   Don't use top nnn lines of the screen
197
198   Options before each file name:
199
200  -wordwrap              Wordwrap
201  -autoindent            Auto indent
202  -overwrite             Overtype mode
203  -lmargin nnn           Left margin
204  -rmargin nnn           Right margin
205  -tab nnn               Tab width
206  -indentc nnn           Indentation character (32 for space, 9 for tab)
207  -istep nnn             Number of indentation columns
208  -french                One space after '.', '?' and '!' for wordwrap
209                         and paragraph reformat instead of two.  Joe
210                         does not change the spacing you give, but
211                         sometimes it must put spacing in itself.  This
212                         selects how much is inserted.
213  -spaces                TAB inserts spaces instead of tabs.
214  -linums                Enable line numbers on each line
215  -rdonly                File is read-only
216  -crlf                  File is uses CR-LF at ends of lines (MS-DOS files)
217
218         These options can also be set in the joerc file.  The NOXON, LINES,
219 COLUMNS, DOPADDING and BAUD options can also be set with environment
220 variables.
221
222         The JOETERM environment variable can be set to override the TERM
223 environment variable.
224
225 ** IMPORTANT **
226
227 The baud rate must be correctly set or either typeahead will not interrupt
228 the screen update and scrolling wont be used or there will be annoying
229 delays in the screen update.  If you can't set the baud rate correctly with
230 'stty', give a numeric value in the environment variable 'BAUD' or to the
231 command line options '-baud'.
232
233 The baud rate '38400' or 'extb' means infinite to joe.  Use it for X windows
234 and hardware console ttys.  No delays will be generated and scrolling will
235 not be used.
236
237 The baud rate '19200' or 'exta' means that joe will use scrolling, but will
238 not delay.
239
240 Use the LINES and COLUMNS environment variables or the -lines and -columns
241 command line options if you need the terminal size to be different than
242 whatever the termcap entry or stty reports.
243
244 Since most people use terminal emulators, JOE does not send out pad
245 characters.  If you're using a real terminal and the padding matters, set
246 the environment variable DOPADDING or give the command line option
247 -dopadding.
248
249 If you want joe to try to disable ^S/^Q processing, set the environment
250 variable NOXON or command line option -noxon.
251
252 A termcap file is included with JOE.  You might consider updating your own
253 termcap file with the entries in it, particularly if you use ANSI/VT100ish
254 terminals.  JOE understands some capabilities which are not usually supplied
255 in normal termcap (see below).
256
257                                  VARIATIONS
258                                  =-=-=-=-=-
259
260 Termcap/Terminfo
261 =-=-=-=-=-=-=-=-
262
263         JOE prefers to use the termcap terminal capability database.  It
264 attempts to find this file in:
265
266         $HOME/.termcap          Personal .termcap in your home directory
267         /usr/local/lib/termcap  Joe's termcap file
268         /etc/termcap            Normal system termcap file
269
270         Joe copies its own termcap file to /usr/local/lib/termcap (or
271 wherever the system-wide joerc file is going to go) when 'make install' is
272 run.
273
274         Termcap is better than terminfo because it is a more open standard.
275 Programs can directly access the termcap database and future versions of
276 terminfo may require programs to use curses.  The only argument in
277 terminfo's favor is that it is faster than termcap.  To fix this problem,
278 JOE will use a termcap index file if it exists and if it is up to date.
279
280         This is the procedure to make the termcap index file:
281
282                 make termidx
283                 ./termidx </etc/termcap >/etc/termcap.idx
284
285         The /etc/termcap.idx is a text file which you can look at if you're
286 curious.
287
288         JOE supports the GNU extensions to the termcap language and also
289 understands several new capabilities:
290
291                 AL DL IC DC RI LE UP DO SF SR
292
293                         Versions of the standard capabilities which accept
294                         an argument.  For example, RI with and argument of
295                         7 should move the cursor 7 positions to the right.
296
297                 rr
298
299                         Set this flag if the cursor is restricted to move
300                         only within the scrolling regions.  This is an optional
301                         mode on vt220s and several clones assume that this
302                         mode is always on.
303
304                 cV
305
306                         Like the 'cv' capability, but the cursor goes to the
307                         beginning of the specified line.  Like 'ESC [ n H' in
308                         ansi/vt100.
309
310 JPICO
311 =-=-=
312
313 If you want JPICO to act more like real pico when you hit ^X (I.E., to have
314 it ask before saving), change the line:
315
316 exsave          ^X              Exit
317
318 to:
319
320 ask,query,lose,query,abortbuf   ^X      Exit
321
322 BROKEN TERMINALS
323 =-=-=-=-=-=-=-=-
324 "Joe does not update the screen correctly in Procomm"
325 "My Xenix console does not scroll correctly"
326
327 Old versions of Procomm, many other DOS comm programs and nearly every
328 PC-UNIX console (with the exception of Linux) does not emulate VT100s
329 properly.  There are usually one or more problems:
330
331         1) Tabs are destructive
332
333         2) Tabs are destructive when inverse mode is set
334
335         3) Scrolling regions are not supported
336
337         4) Cursor positioning is scrolling region relative instead of
338            screen relative.
339
340         5) Some other program set the tab-stops to something other than
341            one tab stop every 8 columns.
342
343         6) The erase commands (ESC [ J and ESC [ K) fill with inverse
344            video blanks instead of plain blanks when inverse mode is set.
345
346         7) Backspace is destructive
347
348 Procomm 2.3 works fine- but make sure you have DEC VT100 selected, not 'ANSI
349 BBS' and also that backspace (BS) is set to 'non-destructive'.  If you must
350 use an old version of Procomm, try using the 'ansisys' or 'nansisys' termcap
351 entry.  Unix consoles usually do not have scrolling regions, but instead
352 have insert and delete line commands.  The 'fansi' entry and ones derived
353 from it will work correctly.  These termcap entries are provided in the
354 termcap file which came with joe.  If at all possible have your sysadmin
355 install these entries in '/etc/termcap'.  Even if your system normally uses
356 the terminfo database, you can copy Joe's termcap file into
357 /etc/termcap.
358
359 "I don't have root access and can't update the system's termcap file.  How
360  do I get only Joe to use a different termcap entry?"
361
362 "My system uses terminfo.  How do I get only Joe to use a different termcap
363  entry?"
364
365 What you should do is copy the termcap file which is provided with joe into
366 '.termcap' of your home directory.  Now suppose you want Joe to use the
367 'fansi' termcap entry:
368
369 If you use csh or tcsh, place this in your .cshrc file:
370
371         setenv JOETERM fansi
372
373 If you use sh, ksh or bash, place this in your .profile file:
374
375         JOETERM=fansi; export JOETERM
376
377 "I don't have root access and can't update the system's termcap file.  How
378  do I get all of my programs to use one of Joe's termcap entries?"
379
380 Again, copy termcap into '.termcap' in your home directory, but set the
381 environment variables like this:
382
383         setenv TERMCAP $HOME/.termcap
384         setenv TERM fansi
385
386 "My system uses terminfo... how do I get all of my programs to use one of
387  Joe's termcap entries?"
388
389 First, compile joe for terminfo.  You then have to 'tic' the terminfo
390 version of joe's termcap file into your account.  These are the commands for
391 doing this:
392
393         1)      cd
394         2)      mkdir .info
395         3)      setenv TERMINFO $HOME/.info
396
397                 (or
398
399                 TERMINFO=$HOME/.info; export TERMINFO
400
401                 if you use bash, sh or ksh)
402
403         4)      tic joe/terminfo
404
405 Then put the 'setenv TERMINFO $HOME/.info' line into your .login file or
406 'TERMINFO=$HOME/.info; export TERMINFO' in your .profile.  Now all of your
407 programs should look up the 'TERM' in your own personal terminfo database.
408
409 USING JOE IN A SHELL SCRIPT
410 =-=-=-=-=-=-=-=-=-=-=-=-=-=
411
412 Joe used to use /dev/tty to access the terminal.  This caused a problem with
413 idle-session killers (they would kill joe because the real tty device was
414 not being accessed for a long time), so now joe only uses /dev/tty if you
415 need to pipe a file into joe, as in:  echo "hi" | joe -
416
417 If you want to use joe in a shell script which has its stdin/stdout
418 redirected, but you don't need to do 'joe -', you should simply redirect
419 joe's stdin/stdout to /dev/tty:
420
421         joe filename  </dev/tty >/dev/tty
422
423 ___________________________________________________________________
424 $MirOS: contrib/code/jupp/README,v 1.3 2008/05/13 16:17:42 tg Exp $