multilingual patch for Keith Bostic's nvi
Jun-ichiro itojun Hagino <itojun@itojun.org>
$Id: README.english,v 1.2 2002/05/22 11:03:21 itojun Exp $


			vi users of the world, unite!


OVERVIEW

	This patchkit contains multilingual patch for nvi 1.79.
	We call it "nvi-m17n" for short.  "m17n" stands for
	multilingualization, since "multilingualization" is made up by
	m, 17 letters, and n.

	You can obtain the latest release of nvi from the following place:
		ftp://ftp.cs.berkeley.edu/ucb/4bsd/
	This package and more up-to-date versions can be found from the
	following place:
		ftp://ftp.foretune.co.jp/pub/tools/nvi-m17n/

	Historical note:
	We once called it "jnvi" since it started as Japanization of nvi.
	You may see the name "jnvi" left somewhere.  That means "nvi-m17n".

REDISTRIBUTION

	Freely redistributable, under condition written in LICENSE file.

WARRANITY AND COPYRIGHT

	Absolutely no warranty.  Pray and backup before try.

	The patch is based on the Japanization work on nvi 1.03 by:
		Yoshitaka Tokugawa <toku@wide.ad.jp>
	and Japanization patch to elvis(vi clone by Steve Kirkendall) by:
		Jun-ichiro itojun Itoh <itojun@itojun.org>
	
	Some part of multibyte support has been derived from other people's
	work.  See comment in multibyte.c.

	Multilingual portion copyright(c) 1996, 1997 by Jun-ichiro Itoh.
	All rights reserved.

DOCUMENTATION NOTE

	We denote "multilingualized nvi" as "nvi" where it is obvious.
	If it is not obvious, we denote that as "nvi-m17n".

QUICK START GUIDE (for impatients)

	First of all, please note that the patch DOES NOT multilingual-ize
	all the functionality of original nvi.
	Therefore, there are some functionalities that shall NOT be invoked.
	The list of functionalities that are multilingualized, and that are
	not multilingualized, will be provided later in the document.
	For details refer to "IT ENABLES..." and "IT DOES NOT ENABLE..."
	sections.

	0. patch the original nvi package.
		% cd nvi-1.79
		% patch -p1 < nvi-m17n.diff
	1. configure nvi with multilingual patch enabled.
		% cd build
		% ./configure --enable-multibyte
	   If you need canna support (Japanese keyboard input engine),
	   configure as following.
	   /usr/local/canna should be the path to canna library/header.
		% ./configure --enable-multibyte --enable-canna=/usr/local/canna

	2. build and install it.
		% make
		% su
		password: xxxx
		# make install

	3. If you're using X, I recommend you to install kterm 6.2.0 for
	   multilingual display.  kterm 6.2.0 can be found at X11R6 contrib
	   mirror site near you.  Also you might need to install some
	   additional fonts.

	4. edit the configuration file. (~/.exrc)
	4-a. iso-2022-* display capability
	     If you have fully iso-2022-* capable terminal software, add the
	     following line:
		set noskipdisplay
	     If you don't have one, add the following line:
		set skipdisplay
	4-b. display encoding
	     Choose encoding scheme of your terminal output from the list
	     below.  Add a line like this:
		set displayencoding=iso-2022-jp
		set displayencoding=sjis
		set displayencoding=euc-jp
		set displayencoding=big5
	     Please note that, the display encoding support has very big twist.
	     See "IT ENABLES..." section for details.
	4-c. keyboard encoding
	     Choose encoding scheme of your keyboard input from the list below.
	     Add a line like this:
		set inputencoding=euc-jp
	     Note that not all the encodings are available as keyboard input
	     encoding.
	4-d. file encoding
	     Choose encoding scheme of your file i/o from the list below.
	     Add a line like this:
		set fileencoding=iso-2022-jp
	     Also, if you would like an automatic encoding scheme selection
	     on file read operation, add the following line:
		set autodetect=jp (for detecting euc-jp/sjis/iso-2022-jp)
		set autodetect=cn (for detecting euc-cn/big5/hz/iso-2022-cn)
		set autodetect=tw (for detecting euc-tw/big5/hz/iso-2022-cn)
		set autodetect=kr (for detecting euc-kr/iso-2022-kr)
	     You can also set autodetection procedure to overwrite
	     fileencoding option, on file open time. (:e/:n)
	     In this case, you should append "+" to autodetect option.
	     In this case, you can preserve encoding method of the file
	     you are editing:
		set autodetect=jp+
		set autodetect=cn+

	     It should be noted that, if you are using chinese encodings
	     (:set autodetect=cn), it is adviced that you have "euc-cn" or
	     "big5" set to fileencoding.  Making a correct guess between
	     euc-cn and big5 is almost impossible, so the autodetection
	     usually fails.  If autodetection fails, the value set to
	     fileencoding will be used.
	     Therefore, if you prefer big5, use the following setting:
		set autodetect=cn fileencoding=big5
	     If you prefer euc-cn, use the following setting:
		set autodetect=cn fileencoding=euc-cn
	     No other settings are recommended for chinese code detection.

	     If you use autodetection of tiwanese encodings
	     (:set autodetect=tw) the above description will apply.
	     Please set fileencoding option to "euc-tw" or "big5".
	
	4-e. canna support
	     If you are willing to use canna support, add the following line:
		set canna
	     If you would like to have automatic canna fence control, add the
	     following too. (also, set fepkey as you like):
		set cannactrl
	     If you need to specify canna server, do it as following:
		set cannaserver=somehost.your.domain
	     If you would like to change canna starter key, specify that as
	     following.  This will set the canna starter key to control-O.
	     be VERY careful making choice!:
		set cannakey=^O

	5. Please note that, after applying this patch, some part of nvi's
	   original document are no longer valid.
	   For example, locale-related items (as found as the first question
	   in nvi-1.79/FAQ) are not applicable to nvi-m17n.

	6. You're all set.  Enjoy!

	Here are some exaples for .exrc file:

	Example 1: using iso-2022-* capable terminal, uses euc-jp terminal
	and filesystem, autodetection enabled for Japanese encodings
		set noskipdisplay
		set displayencoding=euc-jp
		set inputencoding=euc-jp
		set fileencoding=euc-jp
		set autodetect=jp

	Example 2: using iso-2022-* capable terminal, uses iso-2022-jp terminal
	and filesystem, autodetection enabled for Japanese encodings,
	need canna support, and automatic fence control.
		set noskipdisplay
		set displayencoding=iso-2022-jp
		set inputencoding=iso-2022-jp
		set fileencoding=iso-2022-jp
		set autodetect=jp
		set canna cannactrl

	Example 3: using iso-2022-* capable terminal, uses big5 terminal
	and filesystem, autodetection enabled for Chinese encodings
		set noskipdisplay
		set displayencoding=big5
		set inputencoding=big5
		set fileencoding=big5
		set autodetect=cn

ENCODING SCHEMES

	"*" sign at the leftmost column of the line indicates that the
	encoding is available as keyboard input encoding too.
	(:set inputencoding=xxx)

	"!" sign at the leftmost column indicates that the encoding scheme
	does not conform to the specification.  Please look into the note for
	detail.

	Note that multilingual encoding uses iso-2022-* designations for
	character sets that are not specified in the encoding specification.
	(For example, latin-1 character set in iso-2022-kr, cyrillic in
	iso-2022-cn, and so forth)
	Monolingual encoding skips characters of unsupported character set.

	For details of encoding scheme treatment, refer to the "IT ENABLES..."
	section.

    fully multilingual encodings:
	   name		note			initially designated charsets
	   ---		---			---
	*! euc-jp-1978				G0=ascii, G1=JIS X0208.1978,
						G2=JIS X0201 kana,
						G3=JIS X0212-1990.
						SS1 and SS2 used
	*! euc-jp				G0=ascii, G1=JIS X0208.1983,
						G2=JIS X0201 kana,
						G3=JIS X0212-1990.
						SS1 and SS2 used
	*! euc-jp-1983	same as euc-jp
	*! euc-jp-1990				G0=ascii, G1=JIS X0208.1990,
						G2=JIS X0201 kana,
						G3=JIS X0212-1990.
						SS1 and SS2 used
	*! euc-jp-0213				G0=ascii, G1=JIS X0213-1,
						G2=JIS X0201 kana,
						G3=JIS X0213-2.
						SS1 and SS2 used
	*! euc-cn				G0=ascii/G1=GB2312
	*  euc-kr				G0=ascii/G1=KSC5601

	*  iso-8859-1	8bit			G0=ascii/G1=latin1
	*  iso-8859-2	8bit			G0=ascii/G1=latin2
	*  iso-8859-3	8bit			G0=ascii/G1=latin3
	*  iso-8859-4	8bit			G0=ascii/G1=latin4
	*  iso-8859-7	8bit			G0=ascii/G1=greek
	*  iso-8859-8	8bit			G0=ascii/G1=hebrew
	*  iso-8859-9	8bit			G0=ascii/G1=latin5
	*  iso-8859-15	8bit			G0=ascii/G1=latin9
	*  latin1	8bit			alias of iso-8859-1
	*  latin2	8bit			alias of iso-8859-2
	*  iso-2022-cn-ext			G0=ascii
			rfc1922			SI, SO, SS2 and SS3 used
	*  iso-2022-cn	rfc1922			alias of iso-2022-cn-ext
						(they are compatible)
	*  iso-2022-jp-2 rfc1554		G0=ascii
						SS2 used
	*  iso-2022-jp	rfc1468			alias of iso-2022-jp-2
						(they are compatible)
	*! iso-2022-jp-3 JIS X0213 document	G0=ascii
						SS2 used
	*! iso-2022-kr	rfc1557			G0=ascii
						SI and SO used
	*  ctext	X11 compound text	G0=ascii/G1=iso-8859-1
			8bit			no locking shift used
	   
	*  iso-2022-7-1	generic 7bit for test, use G0 only
	*  iso-2022-7-2	generic 7bit for test, use G0/1
	*  iso-2022-8-2	generic 8bit for test, use G0/1

    monolingual encodings:
	   name		note			character sets(fixed)
	   ---		---			---
	*  none		imitates original nvi	G0=ascii, G1=ascii(binary)	
	*! sjis		MS-Kanji/Shift JIS	ascii/JIS X0208.1983
	*  big5
	*  euc-tw				G0=ascii, G1=CNS11643-1,
						G2=CNS11643-[2-7]
	   hz		rfc1842			


	euc-jp series feature:
	  nvi uses ASCII for G0 character set.  This conforms to AT&T document
	  where EUC is defined.
	  You may notice that JIS X0201-left is specified for G0 character
	  set in JIS X0208.1997, and some of old IANA document, however,
	  they are incorrect.  IANA charset registry document was corrected
	  in early 1998 to conform to AT&T document.
	euc-cn feature:
	  We do not support G2 character set (row 8 of GB2312-80, with
	  thin glyphs) in euc-cn.
	iso-2022-jp-3 feature:
	  Specification says that if there is JIS X0208.1983 designation,
	  that should be treated as JIS X0213-1 character iff the codepoint
	  is compatible across two character sets.
	  The implementation treats all JIS X0208.1983 designation as JIS
	  X0213-1 designation, without checking codepoint compatibility.
	iso-2022-kr feature:
	  Though not documented in rfc1557, actual practice shows that it is
	  necessery to remove EOL of the line with KSC5601 designation only.
	  nvi-m17n implements this behavior.
	sjis feature:
	  JIS X0208.1997 specifies Shift JIS encoding a bit.  The
	  specification says that JIS X0201-left should be used instead
	  of ASCII.  It is not a happy choice for most of users, so we'll
	  use ASCII instead.
	  Also, JIS X0208.1983 is chosen for kanji character set.  JIS
	  X0208.1997 uses JIS X0208.1990 instead.  We may eventually change
	  this.
	  (But anyway, no sjis user is aware of JIS X0208 variants!)


CHARACTER SETS

	nvi will not recognize the designation sequence for the character
	sets that are not listed here.  If you need some character sets
	to be recognized, please drop the author a note.

    94 character sets:
	name			designation to G0	note
	---			---			---
	IRV 1983 		ESC ( @
	UK			ESC ( A
	ASCII (IRV 1991)	ESC ( B			hardcoded as default
	Swedish			ESC ( C
	Norwegian		ESC ( E
	JIS X0201 right		ESC ( I			katakana
	JIS X0201 left		ESC ( J
	German			ESC ( K
	French			ESC ( R
	Italian			ESC ( Y
	Spanish			ESC ( Z
	Private 94-0		ESC ( 0			no specific spec
	Private 94-1		ESC ( 1			no specific spec

    96 character sets:
	name			designation to G0	note
	---			---			---
	Latin1			ESC , A			iso-8859-1
	Latin2			ESC , B			iso-8859-2
	Latin3			ESC , C			iso-8859-3
	Latin4			ESC , D			iso-8859-4
	Greek			ESC , F			iso-8859-7
	Arabic			ESC , G			iso-8859-6
	Hebrew			ESC , H			iso-8859-8
	Cyrillic		ESC , L			iso-8859-5
	Latin5			ESC , M			iso-8859-9
	Thai			ESC , T			TIS620.2529
	Latin6			ESC , V			iso-8859-10
	Latin6 additions	ESC , X			iso-8859-10 additions
	Private 96-0		ESC , 0			no specific spec
	Private 96-1		ESC , 1			no specific spec

    94x94 character sets:
	name			designation to G0	note
	---			---			---
	JIS X0208.1978		ESC $ ( @ or ESC $ @
	GB2312-80		ESC $ ( A or ESC $ A
	JIS X0208.1983		ESC $ ( B or ESC $ B
	JIS X0208.1990		ESC & @ ESC $ ( B or ESC & @ ESC $ B
	KSC5601.1987		ESC $ ( C
	JIS X0212.1990		ESC $ ( D
	ISO IR-165		ESC $ ( E
	CNS11643-1992-1		ESC $ ( G
	CNS11643-1992-2		ESC $ ( H
	CNS11643-1992-3		ESC $ ( I
	CNS11643-1992-4		ESC $ ( J
	CNS11643-1992-5		ESC $ ( K
	CNS11643-1992-6		ESC $ ( L
	CNS11643-1992-7		ESC $ ( M
	JIS X0213-1		ESC $ ( O
	JIS X0213-2		ESC $ ( P
	Big5-1			ESC $ ( 0		unofficial, Mule-like
	Big5-2			ESC $ ( 1		unofficial, Mule-like

OPTIONS ADDED

	name			type	range	description
	---			---	---	---
	autodetect(ad)		str	-	detect encoding at file input
	displayencoding(de)	str	global	display encoding
	fepkey			str	-	lists cmds with auto fence ctrl
	fileencoding(fe)	str	-	file input/output encoding
	inputencoding(ie)	str	-	keyboard input encoding
	skipdisplay(sd)		bool	-	skip unsupported chars on disp

OPTIONS ADDED FOR CANNA SUPPORT

	name			type	range	description
	---			---	---	---
	canna			bool	global	use canna or not
	cannactrl		bool	-	controls fence automatically
	cannakey		str	-	canna starter key
	cannaserver		str	global	hostname of canna server

CONFIGURATION

    MULTIBYTE

	On configuration time, you need to add "--enable-multibyte" to enable
	multibyte support.  Typical installation procedure might be as follows:
		% cd build
		% ./configure --enable-multibyte
		% make
	You might want to give a default parameter for multibyte encoding,
	such as:
		% ./configure --enable-multibyte=euc-kr
		% ./configure --enable-multibyte=iso-2022-jp
		% ./configure --enable-multibyte=euc-cn
	If you didn't specify encoding method, it will become "none".

    CANNA

	If you would like to use canna support, you should add "--enable-canna"
	to the argument to configure.  It must come with --enable-multibyte.
		% cd build
		% ./configure --enable-multibyte --enable-canna

	You may need to specify directory where the compiler can find
	canna headers and libraries.
	If you specify directory SOMEWHERE as argument to --enable-canna,
	like:
		% ./configure --enable-multibyte --enable-canna=SOMEWHERE
	it means that you have the following headers and libraries:
		SOMEWHERE/include/canna/jrkanji.h
		SOMEWHERE/lib/libcanna.a

	If you have non-standard installation, and the directory prefix
	is not the same for headers/libraries, you should specify those
	directories manually.  If you have headers/libraries in the following
	location:
		SOMEWHERE/canna/jrkanji.h
		ELSEWHERE/libcanna.a
	you should do the following:
		% env CFLAGS=-ISOMEWHERE LDFLAGS=-LELSEWHERE \
			./configure --enable-multibyte --enable-canna

	In most cases, you will need to use the following setting:
		% ./configure --enable-multibyte --enable-canna=/usr/local/canna

IT ENABLES...

    Multibyte-safe movement/input.

    Multibyte word movement. (currently japanese/korean only, sorry)

    Console output for iso-2022-* capable terminal, and primitive
    euc-jp/euc-cn/euc-kr/euc-tw/sjis/big5 support.
	Encoding must be set by
		:set displayencoding=foobaa

	The available encodings are listed in "ENCODING SCHEMES" section.
	However, it is not very straightforward; read the following
	description with care.

	Multibyte chars will be displayed in the following manner:

	1. If special function was defined for the encoding, use that.
	   special function is defined for each some 8bit encodings.
		name	note
		---	---
		euc-jp	ASCII will be displayed as G0(GL) chars (0x21-0x7e).
			JIS X0208.1990/1983/1978 chars will be displayed
			as G1(GR) chars (0x8181-0xfefe).
			There's no way to distinguish between JIS X0208
			variants.  It depends on your terminal how they
			will be rendered.
			NOTE: JIS X0201-left won't be treated in a special
			manner.
		euc-cn
		euc-kr
		euc-tw	G0/G1 only (G0=ASCII, G1=CNS11643-1)
		sjis	ASCII will be displayed as G0(GL) chars (0x21-0x7e).
			JIS X0208.1990/1983/1978 chars and JIS X0201 kana chars
			are encoded by sjis convention, and displayed properly.
			There's no way to distinguish between JIS X0208
			variants.  It depends on your terminal how they
			will be rendered.
			NOTE: JIS X0201-left won't be treated in a special
			manner.
		big5

	2. if ":set skipdisplay" was done, skip it by displaying "?" or "??".

	3. Otherwise, try displaying it with G0 designation of iso-2022-*
	   escape sequence, such as "ESC $ B" for JIS X0208.1983,
	   "ESC , A" for latin-1.  We use G0 designation only for simplicity.
	   It is same as "iso-2022-7-1" encoding, which uses G0 designations
	   only.

	For multilingual use, (case 3 in the above steps) best suited for
	use with fully iso-2022-* capable terminals.  For example, you may
	want to try kterm-6.2.0, which can be found on ftp servers that has
	X11R6 contrib.

	If you would like to know about detail of the patch to curses,
	see curses/README.m17n.

	:set displayencoding=xxx is global option, so it will affect
	all the sub-screens.  On the other hand, :set skipdisplay is
	not an global option, so that a user can have a control over it
	per sub-screen manner.

    File i/o encoding is switchable.
	The available encodings are listed in "ENCODING SCHEMES" section.

	Most of multilingual encodings are made possible by using generic
	iso-2022-* parser/generator.
	Please note that, some multilingual encoding specification does not
	specify some of the character set.  For example, iso-2022-jp2
	(RFC1554) specifies how to designate arbitrary character set,
	but iso-2022-kr(RFC1557) does not.
	If the encoding scheme you are using does not specify how to encode
	some character set, nvi will recognize/generate iso-2022-*
	escape sequences.
	Example:
	  If you use JIS X0208.1983 while you are using
	  ":set fileencoding=latin1" setting, nvi will emit
	  "ESC $ B whatever ESC ( B", which is valid iso-2022-* sequence
	  for JIS X0208.1983.

	Monolingual encodings (namely sjis and hz) are hardcoded, and
	they will just skip any charsets that are not supported.

	:set fileencoding=xxx affects the filter command (! in vi),
	file open/read/write (:r, :w, :e and :n), and scripting input/output
	to shell (:script).

    Automatic encoding detection at file open/read time.
	Capable of autodetecting several encoding schemes on the fly.
		:set autodetect=jp (for detecting euc-jp/sjis/iso-2022-jp)
		:set autodetect=cn (for detecting euc-cn/big5/hz/iso-2022-cn)
		:set autodetect=tw (for detecting euc-tw/big5/hz/iso-2022-cn)
		:set autodetect=kr (for detecting euc-kr/iso-2022-kr)
	If other value is set to autodetect option, autodetect will not
	be performed.

	On file edit-start time (such as :n or :e) or file read time (:r)
	the content of the file will be read into the backing database, 
	then the autodetection procedure starts.  Autodetection procedure
	tries to figure out the encoding, and converts the backing database
	into proper internal expression based on the result.
	If the autodetection was unsuccessful, the value set to fileencoding
	option (:set fileencoding) will be used as default value.

	You can also set autodetection procedure to overwrite fileencoding
	option, at edit-start time. (:e/:n)  By doing so, you can preserve
	encoding method of an file across edit sessions.
	In this case, you should append "+" to autodetect option, like:
		set autodetect=jp+
		set autodetect=cn+
	If you use this option, control-G vi command will display the encoding
	method you're using.

	Please note that autodetection may take some time over a huge file,
	since autodetection procedure may scan whole lines which are
	just read into the backing database.
	(Maximum lines to be scanned can be changed by changing
	PREDICT_MAXLINES in common/multibyte.c.)
	Also, autodetection is not always possible; especially for short
	files.
	I don't think the autodetection procedure will be happy with binary
	files, so please be warned.

	:set autodetect=xxx only affects file open/read operations.
	(:r, :e and :n)

	It should be noted that, if you are using chinese encodings
	(:set autodetect=cn), it is adviced that you have "euc-cn" or
	"big5" set to fileencoding.  Making a correct guess between
	euc-cn and big5 is almost impossible, so the autodetection
	usually fails.  If autodetection fails, the value set to
	fileencoding will be used.
	Therefore, if you prefer big5, use the following setting:
		:set autodetect=cn fileencoding=big5
	If you prefer euc-cn, use the following setting:
		:set autodetect=cn fileencoding=euc-cn
	No other settings are recommended for chinese code detection.

	If you use autodetection of tiwanese encodings (:set autodetect=tw)
	the above description will apply.  Please set fileencoding option
	to "euc-tw" or "big5".

    - Multibyte keyboard input.
	selection of keyboard input code should be done like:
		:set inputencoding=euc-jp
		:set inputencoding=iso-2022-jp
	euc-jp/kr/cn and iso-2022-* encodings use generic iso-2022-*
	parser.  Therefore, their input stream handling is truely
	multilingual.

	Single and locking shift sequences will be accepted if it is
	allowed in the encoding type.  For example, euc-* encoding
	accepts SS2R and SS3R (0x8e and 0x8f) only.
	Note that if you are going to use iso-2022-* encodings for keyboard
	input, there'll be problem with ESC.  ESC denotes the start of
	character set designation, as well as finish of vi entry mode...
	We currently identify them by timeout mechanism.  There may some
	trouble arise when you are using nvi over very slow serial line.

    - Regular expression search over multibyte chars.
	For list of restrictions/notes, refer to regex/README.m17n.

    - Direct canna support for Japanese text entry.
	"canna" is an client-server protocol for Japanese text conversion.
	added options are listed in separate section.
	Canna support is for vi mode only; in ex mode execution, canna
	support is not available.

	If you would like to use canna, do the following:
		:set canna
	It will connect nvi to canna server.  You can disconnect from
	canna server by doing:
		:set nocanna

	To switch to canna mode (activate fence), tap control-O.
	The keystroke is determined by cannakey option.  You can change
	it by setting cannakey option, as follows.  This example sets
	canna starter key to control-X:
		:set cannakey=^X	(to enter it on colon mode, use ^V^X)
	Please be VERY careful about your choice.  The selected keystroke
	will overrider everything, and that keystroke will NEVER be passed
	to nvi itself, while canna option is set.

	Sometimes it might be annoying to see canna fence activated while
	you're in the vi command mode.  nvi can automatically control
	deactivation of canna.  You can enable this feature by setting
	the following option:
		:set cannactrl
	If you set this option, the following events will happen:
	- on leaving from text entry (for selected commands),
	  canna fence will be deactivated automatically.
	- on entering to text entry (for selected commands),
	  canna fence will be activated automatically,
	  if was recently automatically deactivated.
	- on entering to vi command mode (for all commands),
	  canna fence will be automatically turned off.
	You can select commands to be controlled as above, by setting
	fepkey option.  By default, it is set to "/?aioAIO".
	You may want to add "ftFT", for example.
	Full-featured example would be as follows:
		:set fepkey=?/aioAIOcCrRtfTF
	Believe me, it works.

	To change canna server, do the following
		:set cannaserver=hostname.your.domain

	There are several twists to canna support.  See "KNOWN TWISTS"
	secton.

SETTING UP OPTIONS SPECIFIC TO NVI

	As you see, There are several options added to original nvi.
	However, under some circumstances, option settings written in .exrc
	may trouble you:
	1. If you use both nvi-m17n and original nvi/other vi clone, other
	   implementations may not understand extended options of nvi-m17n.
	   In that case, they will bark on startup, or they do not start up.
	2. If you are willing to use multiple settings, it would be nice if
	   you can switch one setting to another.

	In case of 1., there are three sideways:
	- You can use .nexrc rather than .exrc to resolve conflict between
	  nvi and other vi clones.
	  Since .nexrc is introduced in original nvi, it is unable to pass
	  different options to nvi-m17n and original nvi, by using .nexrc.
	- You can use environment variable NEXINIT too.
	  It works just like EXINIT, but it is for nvi/nvi-m17n only.
	- You can use wrapper script (described below)
	In case of 2., you can use wrapper script.

    Wrapper script
	You can use wrapper script to pass some options specific to nvi-m17n.
	For example, see below:

--->8 example for japanese editing (save as, say "jnvi")
#! /bin/sh

EXINIT0="set canna cannactrl autodetect=jp fileencoding=iso-2022-jp displayencoding=iso-2022-jp inputencoding=iso-2022-jp noskipdisplay"
if [ -f ~/.exrc ]; then
	EXINIT="$EXINIT0 `sed -e '/^set /!d' -e 's/^set //' < ~/.exrc | tr '\012' ' '`"
else
	EXINIT=$EXINIT0
fi
export EXINIT
exec /usr/local/bin/nvi $*
--->8

ADDITIONAL TOOL

	The package adds a perl script called "regular" to original nvi package.

    regular [-options]

	Some text files contain ASCII text with unnecessery designations.
	For example, "a" in UK charset, "a" in JIS X0201 roman charset,
	and so forth.  They are correct use, however, they sometimes
	annoy the users of nvi-m17n since it is not always easy to input those
	chars in those charset, not ASCII "a".
	Regular converts these chars into ASCII "a".

	Regular has several options.
		-7
			Output encoding will be iso-2022-7-1.
			All charset will be designated to G0.
			No locking shift/single shift will be used.
			Regular acts like this by default.
		-8
			Output encoding will be iso-2022-8-2.
			All 94/94x94 charset will be designated to G0,
			and all 96/96x96 charset will be designated to G1.
			No locking shift/single shift will be used.
		-kr
			Assume that input is iso-2022-kr.
			It means that, charsets designated to G0/G1/whatever
			will be valid across the line-break.  In other
			cases, designation will be reset to
				G0=ASCII, G1=G2=G3=nothing
			at every line break.
	It eats text from standard input, and generate output to standard
	output.  Use like
		% regular < source.txt > dst.txt
	or, from nvi-m17n, use filter (! in vi mode) command.

	Known twists:
	- Though nvi-m17n can handle it, output encoding is very uncommon.
	  It must not be regarded as generic tool.  It is just for supporting
	  nvi-m17n.
	- It is not possible to handle euc-*/sjis/big5/whatever document.
	  If you use vi filter command, fileencoding options in nvi-m17n must
	  be set to iso-2022-* kind of encoding.
	- Regular is DEADLY slow.  Be warned.
	  If you feel it unusable, please use "qregular" instead.
	  It recognize direct G0/G1 designation only.

IT DOES NOT ENABLE...

	The patch DOES NOT multilingual-ize all the functionality of nvi.
	Therefore, there are some functionalities that shall NOT be invoked.
	I list SOME of them here.  Check source code for unsupported features:
	- sideway scrolling screen mode (:set leftright) sometimes generate
	  core-dump, or infinite loop.
	- display interfaces other than curses will not work.
	- can be compiled with embedded perl interpreter.  however, it is
	  almost unusable since perl script will need to handle nvi's
	  internal code.
	- not confirmed with tcl linked.  I think it won't work.
	- in ex mode, the echoback of the keystroke you typed will be
	  performed by the terminal software you're using, not by nvi itself.
	  (this is the behavior of original nvi)
	  therefore, there might be garbled echoback if your terminal software
	  does not properly handle it.
	- there is no canna support in ex mode, due to screen control
	  method used by origial nvi.  (colon mode in vi has canna support)

KNOWN TWISTS(of original nvi 1.79)

	There's a problem with tcsh 6.05.00.
	In tcsh 6.05.00,
		% echo -n 'hoge' | tcsh -c cat
	will hang.  Also,
		% ( echo 'hoge'; echo -n 'hoge') | tcsh -c cat
	will produce only the first line, which is a different result from
	that of csh.
	Because of this, if your login shell is tcsh 6.05.00, and you invoke
	"filter 1 line" command (say, "!!cat" or "!!fmt") in nvi, nvi hangs
	with tcsh.
	The easiest way around it is not to use tcsh from nvi.  For that,
	you may want to add a line in your .exrc:
		set shell=/bin/csh

	If you do
		:set
	then
		:set all
	the screen will scroll too much (1 lines more than expected).
	You will not be able to read the first line generated by :set all.

	The original nvi assumes that macros defined in ctype.h (isprint(),
	isblank() and alike) will properly handle minus values.
	(NOTE: this is NOT in the ANSI C specification!)
	If it is not satisfied, nvi will hang if chars that are 8th bit set
	(0x80-0xff) appears.  It is very critical situation to
	multilingualization, since it uses values that are 8th bit set heavily.
	I've fixed most of the occurences, however, I might missed somewhere.
	If nvi hangs in your configuration, please tell me how can you
	repeat that.

KNOWN TWISTS(of nvi-m17n)

	If you use iso-2022-* encoding as keyboard input,
	(:set inputencoding=xxx) control-O and control-N will always
	be treated as SI/SO which switches character set.  Therefore, you
	can't use control-N as "next line" vi command.
	(If you use canna support, the behavior might be overriden by
	canna starter key.  See below)
	To type in those kind of control key strokes, you should temporarily
	change the keyboard encoding, like:
		:set inputencoding=none

	Multilingual parser/generator for keyboard, terminal output, file i/o
	are implemented separately.  They have slightly different
	characteristics.  This is because:
	- Keyboard parser must understand halfway-entered text stream
	- Terminal output generator must designate everything into G0
	  (although monolingual encoding such as sjis can use 8bit)
	- File i/o is the easiest one of the three guys

	Autodetection of chinese encoding method is almost impossible.

	Canna starter key (as defined by :set cannakey) overrides everything.
	Therefore, for example, if you set canna starter key to control-O,
	you will not be able to use control-O as SI.  If you set canna starter
	key to control-M, you will not be able to enter CR!
	Be very careful choosing starter key.

	Some vi commands are implemented by using other vi commands.
	For example, S command is implemented as c_ command.
	C, D, S, and Y commands are implemented in this way.
	fepkey option looks into translated version of the command.
	Therefore, if you enable automatic canna control for c command,
	automatic control for S command will be automatically enabled.
	see v_alias() in vi/vi.c for details.

	When you set wrapmargin/wraplen option, it will wrap lines at
	word boundary which is recognized by W/B vi command.  Sometimes
	it may look annoying when you do it over multibyte lines.
	Now I'm trying to find a good way to wrap multibyte lines.
	If you have some comments, please let me know.

	I haven't checked autodetection of korean/chinese encoding very much.
	If you have any suggestions, please let me know.

	If you are using iso-2022-* variants to keyboard encoding,
	keyboard timeout is too long (twice as long as non-multibyte
	implementation).

	Please note that, after applying this patch, some part of nvi's
	original document are no longer valid.
	For example, locale-related items (as found as the first question
	in nvi-1.79/FAQ) are not applicable to nvi-m17n.

	If you use nvi-m17n on some of the non iso-2022 capable terminals,
	you'll see strange "B" character at the top-left of the screen on
	startup.  The character is the remains of "ESC ( B", which was not
	properly handled by your terminal.  nvi-m17n will generate the
	sequence initializing G0(=GL) character set to ASCII.
	If you are annoyed by the character, modify the following line
	in curses/refresh.c (in function putdesig()).
default:	static enum { NO, ASCII, CACHED } prevstate = NO;
modified:	static enum { NO, ASCII, CACHED } prevstate = ASCII;
	In this case, nvi-m17n will assume that the terminal has ASCII
	character set as G0(=GL) character set on startup.  (and this
	assumption is incorrect in many cases)

	Cursor keys (i.e. escape sequence defined in termcap :ku: or :kd:
	capability) may not be recognized correctly.  The situation has
	multiple reasons, it seems.  The author rarely uses cursor keys.
	so please fill him in with the steps needed to repeat the problem.

	When using Canna with nvi, Canna library API gives nvi an euc-jp
	encoded stream when Japanese text is entered.  Japanese letters in
	the stream will be recognized as chars in JIS X0208.1983 character set.
	Sometimes this may not be the natural behavior, for example when
	you are manipulating iso-2022-jp-3 text (where JIS X0213-1 should
	be used where JIS X0208 designation appears).

COMMENTS AND SUGGESTIONS

	Bugs and comments should be sent by the following methods:
		via http://www.itojun.org/cgi-bin/gnats-send-pr
		e-mailed to nvi-m17n@foretune.co.jp
	Please specify the version number of the patch you've tried.

CONTACTING THE AUTHOR

	Jun-ichiro itojun Hagino (Jun-ichiro Itoh)
	itojun@itojun.org
	Contribution to the author, in any form (example: just say "thanks"),
	is always appreciated.
