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