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