~mirabilos/jupp/trunk

This documentation should go elsewhere, but I haven't gotten around to it
yet.

GCC
---

Disable the following warnings; the code doesn't cope with it:
-Wno-pointer-sign
-Wno-unused-parameter
-Wno-strict-prototypes

UTF-8
-----

Do note that the joerc files must be written using the 8-bit encoding,
not in UTF-8. Syntax files, on the other hand, absolutely must be
written in UTF-8 since jupp29.

JOE now handles two classes of character sets: UTF-8 and byte coded (like
ISO-8859-1).  It can not yet handle other major classes such as UTF-16 or
GB2312. There are other restrictions: character sets must use LF (0x0A) or
CR-LF (0x0D - 0x0A) as line terminators, space must be 0x20 and tab must be
0x09. Basically, the files must be UNIX or MS-DOS compatible text files.

This means EBCDIC will not work properly (but you would need to handle fixed
record length lines anyway) and character sets which use CR terminated lines
(MACs) will not yet work.

The terminal and the file can have different encodings.  JOE will translate
between the two.  Currently, one of the two must be UTF-8 for translation to
work.

The character set for the terminal and the default character set assumed for
files is determined by the 'LC_ALL' environment variable (and if that's not
set, LC_CTYPE and LANG are also checked). 'JOECHARMAP' overrides this value.

For example, if LC_ALL is set to:

	de_DE

Then the character set will be ISO-8859-1.

If LC_ALL is set to:

	de_DE.UTF-8

The character set will UTF-8.

Hit ^T E to change the coding for the file.  Hit <tab> <tab> at this prompt
to get a list of available codings.  There are a number of built-in
character sets, plus you can install character sets in the ~/.jupp/charmaps
and /usr/local/etc/joe/charmaps directories.

Check: /usr/share/i18n/charmaps for example character set files.  Only
byte oriented character sets will work.  Also, the file should not be
gzipped (all of the charmap file in /usr/share/i18n/charmaps on my computer
were compressed).  The parser is very bad, so basically the file has to look
exactly like the example one in /usr/local/etc/joe/charmaps.

You can hit ^K <space> to see the current character set.

You can hit ` x to enter a UCS character if the file coding is UTF-8.

Programming
-----------

	Try ^K , and ^K .  These keys select the current block (based on
indentation) and shift it left or right by the -istep and -indentc.

Selecting blocks
----------------

	The "classic" way is to hit ^K B at the beginning and ^K K at the
end.  These set pointers called markb and markk.  Once these are set you
can jump to markb with ^[ b and jump to markk with ^[ k.

	New way no.1: hit Ctrl-space to start selecting, move the cursor,
then hit Ctrl-space to complete the block.  Hit Ctrl-space in the block to
cancel it.  Hit Ctrl-space outside of the block to start selecting a new
one.  This uses the "toggle_marking" function.  Also any block command will
complete the block. (joe flavour only)

	New way no.2: hit Ctrl-rtarw to start selecting rightward.  Each
time you hit Ctrl-rtarw, the block is extended one more to the right.  This
uses a simple macro: "begin_marking,rtarw,toggle_marking".  Unfortunately,
there is no standard way to get the keysequence given by the terminal
emulator when you hit Ctrl-rtarw.  Instead you have to determine this
sequence yourself and enter it directly in the joerc file.  Some examples
are given for xterm and gnome-terminal.  Hit ` rtarw to have the sequence
shown on your screen.  Note that Putty uses ^[ ^[ [ C which will not appear
with ` rtarw (also ^[ ^[ is set book mark, so you need to unbind it to do
this in Putty). (joe flavour only)

	Also you can hit Ctrl-delete to cut and Ctrl-insert to paste if the
sequence for these keys are known. (joe flavour only)

	New way No.3: press down shift, then move the cursor with the
arrow keys or, optionally with ctrl, the Home and End keys; release the
shift key when done and remember that the cursor indicator on screen is
not part of the selection. (all flavours)

	Also, you can pass "-keymap cua" on the command line to change
the key bindings for ^Z (Undo), ^X (Cut), ^C (Copy), ^V (Paste) as in
contemporary GUI editors. (joe, rjoe, jstar, jupp flavours only)

	Using Picture mode and Rectangle mode may help with that.

Hex edit mode
-------------

When this mode is selected (either put -hex on the command line, or look for
"Hex edit mode" after hitting ^T), the buffer is displayed as a hex dump,
but all of the editing commands operate the same way.  It is most useful to
select overtype mode in conjunction with hex dump (hit ^T T).  Then typing
will not insert.

- To enter the hex byte 0xF8 type ` x F 8

- You can use ^KC to copy a block as usual.  If overtype mode is selected,
  the block will overwrite the destination data without changing the size of
  the file.  Otherwise it inserts.

- Hit ESC x byte <Enter>, to jump to a particular byte offset.  Hex values
  can be entered into this prompt like this: 0x2000.

- Search, incremental search, and search & replace all operate as usual.

Licences (binary package summary)
---------------------------------

joe is Copyright
 © 1992, 2004 Joseph H. Allen
 © 2001 Marek 'Marx' Grac
 © 2004, 2006, 2011, 2013, 2014, 2017, 2018, 2020 mirabilos
jupp is Copyright
 © 1997–2020 Thorsten Glaser

 * jupp is free software; you can redistribute and/or modify it, deal
 * in the work, etc. under the terms of the GNU General Public Licen-
 * se, version 1 (of February 1989) as published by the Free Software
 * Foundation, reproduced in the file COPYING in the jupp source code
 * distribution. If jupp is combined with other independent work, for
 * example libraries or when using crunchgen, into a combined binary,
 * that may be conveyed under any version of the GPL, as published by
 * the Free Software Foundation, and any compatible licence permitted
 * by any version of the GPL, as above.

jupp is also:
 * Copyright © 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012,
 *	       2013, 2014, 2016, 2017, 2018, 2020
 *	mirabilos <m@mirbsd.org>
 *
 * Provided that these terms and disclaimer and all copyright notices
 * are retained or reproduced in an accompanying document, permission
 * is granted to deal in this work without restriction, including un‐
 * limited rights to use, publicly perform, distribute, sell, modify,
 * merge, give away, or sublicence.
 *
 * This work is provided “AS IS” and WITHOUT WARRANTY of any kind, to
 * the utmost extent permitted by applicable law, neither express nor
 * implied; without malicious intent or gross negligence. In no event
 * may a licensor, author or contributor be held liable for indirect,
 * direct, other damage, loss, or other issues arising in any way out
 * of dealing in the work, even if advised of the possibility of such
 * damage or existence of a defect, except proven that it results out
 * of said person’s immediate fault when using the work as intended.

strlfun.inc (optional) additionally is:
 * Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

I18N data is:
 * Parts Copyright © 1991–2020 Unicode, Inc. All rights reserved.
 * Distributed under the Terms of Use in
 *     https://www.unicode.org/copyright.html.
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of the Unicode data files and any associated documentation
 * (the "Data Files") or Unicode software and any associated documentation
 * (the "Software") to deal in the Data Files or Software
 * without restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, and/or sell copies of
 * the Data Files or Software, and to permit persons to whom the Data Files
 * or Software are furnished to do so, provided that either
 * (a) this copyright and permission notice appear with all copies
 * of the Data Files or Software, or
 * (b) this copyright and permission notice appear in associated
 * Documentation.
 *
 * THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF
 * ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT OF THIRD PARTY RIGHTS.
 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS
 * NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL
 * DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THE DATA FILES OR SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale,
 * use or other dealings in these Data Files or Software without prior
 * written authorization of the copyright holder.

popen.inc (optional) is:
 * Copyright (c) 1988, 1993
 *	The Regents of the University of California.  All rights reserved.
 *
 * This code is derived from software written by Ken Arnold and
 * published in UNIX Review, Vol. 6, No. 8.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the University nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.

___________________________________________________________________
$MirOS: contrib/code/jupp/HINTS,v 1.19 2020/03/27 08:28:53 tg Exp $