$Id: README,v 1.11 2007/11/13 16:38:15 yuk Exp $
(Translated from Russian and edited by David S. Lawyer)

1. What is mapchan?

mapchan - A program which allows you to transform the input and output
of a terminal (including a serial port terminal).  It is useful when:

  * You need to work with various encodings on various virtual
    terminals
  * You have an assortment of terminals, not one of which supports 
    your favorite encoding.

This software is an incomplete implementation of the functionality of
the utility "mapchan" of SCO Unix (man-page see in `doc/mapchan.F.Z').  
This is not a crude hack, requiring modification of the kernel.  
It's a conventional program using the mechanism of pseudo-terminals.  
As a result, it's not Linux-only and should work on any unix-like system.

Started from version 3.0 is supported standard transforming of any
known codeset with mechanizm 'iconv', if source system has base
codeset UTF-8.

2. Installation

The installation process uses the traditional files:

  make
  make install

It suggested that map_files go into /etc/mapchan

3. Launching

Command line format:

  mapchan [-q] [-s shell] [-f map_file] [-p /dev/ttyXX | auto] [-h]

  options:

    -q - Quiet start (without any messages).
    -s - Permits specifying the launching shell.
         Default - /bin/sh
    -p - Old-style naming of pseudo-tty, for example: "/dev/ttyc1" 
         for exactly name, or "/dev/ttyc1-df" for name range,
	 or "auto" - if you want select the first unused.
	 NOTE: If this key is not used - terminal device created
	 dynamically in Unix'98 standard as "/dev/pts/N"
    -f - map_file-name
         Default: read from the file: /etc/mapchan/default
    -u - codeset in target system if in source system is used UTF-8
         You can see codeset name list by command 'iconv --list'
    -P - Pause (2 sec) when terminal is opening.
    -h - Output short help

ATTENTION! Starting "mapchan" without parameters will not display
---------  usage info and then quit the program.  In this case
	  "mapchan" tries to start in conformance with 
	  /etc/mapchan/default.

Starting mapchan is best done from the user ".profile" file
by one of two methods:

1) Having created in /etc/mapchan the file "default" (a sample may be
found in "examples") indicate for each terminal line which map_file is
to be used.  The format of the "default" file:

   <name_of_terminal> <name_of_map_file>
   <name_of_terminal> <name_of_map_file>
   ....

   Then place at the end of the user file ".profile" a line like:

   mapchan -q -s mc

2) One may put all the selecting of the map_file in ".profile",
placing at the end of it something like:

   if [ "$TERM" == "sm7238"]; then
      mapchan -f /etc/mapchan/sm7238.map -s user_prog
   else
      user_prog
   fi


4. Format of the map_file

   There are the following differences from the SCO implementation:

   - as yet the tag "beep" is unsupported
   - there is no tag "compose" (it's hardly need in real life)
   - only one "dead" tag may be put in a map-file

   map_file may include:
   
   - comments, beginning with #
   - empty lines
   - a section for output transformations starting with the label
     "output" (maps the terminal screen)
   - a section for input transformations starting with the label
     "input"  (maps the terminal keyboard)
   - an optional section for input transformations, starting with the
     label "dead" 

Each section contains an arbitrary number of lines, each of which
determines the transformation of input or output symbols.  While a
symbol is usually simply transformed into another symbol it may be
transformed into a sequence of symbols.  The format of a line:

<symbol> <what it's transformed into>

Sequences of symbols may be separated by white-space for readability.

Symbols may be represented as:

   0777 - number, starting with "0" - octal code
   0xAA - number, starting with "0x" - hexadecimal code
   99   - number, starting with a decimal digit - decimal code
   'A'  - symbol in single quotes - that symbol
   A    - alphabet letter - that letter

4.1. Section "control"

Format of this section is different from SCO mapchan.
In my version it used for description of controls (while single-char)
for mapping disabling ad enabling.

It's usefull when you need to send data not for displaying over the
terminal line (for example, on local printer).

String format:

'-' <mapping off char>
'+' <mapping on char>

4.2. Section "esc("

This section is present only in this version of mapchan. It's work as
"output", but made transforming only for sequences 

ESC ( char

what are used for codeset switching. For example, if section 

esc(
'B' 0x1B '(' 'K'

present in some map-file - then esc-sequence ESC(B will be transformed 
into ESC(K during output.


5. Examples

The directory examples/ contains some example files:

	default 	- file showing the map_file to use for each tty

Map-files:

	altkoi.map	- the program is in alternative DOS encoding,
			  the terminal - koi8-r
	koiualt.map	- program is koi8-u, terminal - alternative
	koiumain.map	- program is koi8-u, terminal - basic GOST
	k180.map	- same as previous + mapping disabling/enabling
                          (section "control")
	sm7238.map	- program is koi8-u, terminal - SM7238 in mode
			  "UP.RUS" (symbols in basic GOST with vt100
			  pseudo-graphics)
	dos2koi.map	- program is CP-866, terminal - koi8-r
	win2koi.map	- program is CP-1251, terminal - koi8-r

The above example files are best viewed using a koi8 font (Russian).
"Alternative" is a special encoding derived from MS DOS and used
primarily in Russia.
