1$Id: README,v 1.11 2007/11/13 16:38:15 yuk Exp $ 2(Translated from Russian and edited by David S. Lawyer) 3 41. What is mapchan? 5 6mapchan - A program which allows you to transform the input and output 7of a terminal (including a serial port terminal). It is useful when: 8 9 * You need to work with various encodings on various virtual 10 terminals 11 * You have an assortment of terminals, not one of which supports 12 your favorite encoding. 13 14This software is an incomplete implementation of the functionality of 15the utility "mapchan" of SCO Unix (man-page see in `doc/mapchan.F.Z'). 16This is not a crude hack, requiring modification of the kernel. 17It's a conventional program using the mechanism of pseudo-terminals. 18As a result, it's not Linux-only and should work on any unix-like system. 19 20Started from version 3.0 is supported standard transforming of any 21known codeset with mechanizm 'iconv', if source system has base 22codeset UTF-8. 23 242. Installation 25 26The installation process uses the traditional files: 27 28 make 29 make install 30 31It suggested that map_files go into /etc/mapchan 32 333. Launching 34 35Command line format: 36 37 mapchan [-q] [-s shell] [-f map_file] [-p /dev/ttyXX | auto] [-h] 38 39 options: 40 41 -q - Quiet start (without any messages). 42 -s - Permits specifying the launching shell. 43 Default - /bin/sh 44 -p - Old-style naming of pseudo-tty, for example: "/dev/ttyc1" 45 for exactly name, or "/dev/ttyc1-df" for name range, 46 or "auto" - if you want select the first unused. 47 NOTE: If this key is not used - terminal device created 48 dynamically in Unix'98 standard as "/dev/pts/N" 49 -f - map_file-name 50 Default: read from the file: /etc/mapchan/default 51 -u - codeset in target system if in source system is used UTF-8 52 You can see codeset name list by command 'iconv --list' 53 -P - Pause (2 sec) when terminal is opening. 54 -h - Output short help 55 56ATTENTION! Starting "mapchan" without parameters will not display 57--------- usage info and then quit the program. In this case 58 "mapchan" tries to start in conformance with 59 /etc/mapchan/default. 60 61Starting mapchan is best done from the user ".profile" file 62by one of two methods: 63 641) Having created in /etc/mapchan the file "default" (a sample may be 65found in "examples") indicate for each terminal line which map_file is 66to be used. The format of the "default" file: 67 68 <name_of_terminal> <name_of_map_file> 69 <name_of_terminal> <name_of_map_file> 70 .... 71 72 Then place at the end of the user file ".profile" a line like: 73 74 mapchan -q -s mc 75 762) One may put all the selecting of the map_file in ".profile", 77placing at the end of it something like: 78 79 if [ "$TERM" == "sm7238"]; then 80 mapchan -f /etc/mapchan/sm7238.map -s user_prog 81 else 82 user_prog 83 fi 84 85 864. Format of the map_file 87 88 There are the following differences from the SCO implementation: 89 90 - as yet the tag "beep" is unsupported 91 - there is no tag "compose" (it's hardly need in real life) 92 - only one "dead" tag may be put in a map-file 93 94 map_file may include: 95 96 - comments, beginning with # 97 - empty lines 98 - a section for output transformations starting with the label 99 "output" (maps the terminal screen) 100 - a section for input transformations starting with the label 101 "input" (maps the terminal keyboard) 102 - an optional section for input transformations, starting with the 103 label "dead" 104 105Each section contains an arbitrary number of lines, each of which 106determines the transformation of input or output symbols. While a 107symbol is usually simply transformed into another symbol it may be 108transformed into a sequence of symbols. The format of a line: 109 110<symbol> <what it's transformed into> 111 112Sequences of symbols may be separated by white-space for readability. 113 114Symbols may be represented as: 115 116 0777 - number, starting with "0" - octal code 117 0xAA - number, starting with "0x" - hexadecimal code 118 99 - number, starting with a decimal digit - decimal code 119 'A' - symbol in single quotes - that symbol 120 A - alphabet letter - that letter 121 1224.1. Section "control" 123 124Format of this section is different from SCO mapchan. 125In my version it used for description of controls (while single-char) 126for mapping disabling ad enabling. 127 128It's usefull when you need to send data not for displaying over the 129terminal line (for example, on local printer). 130 131String format: 132 133'-' <mapping off char> 134'+' <mapping on char> 135 1364.2. Section "esc(" 137 138This section is present only in this version of mapchan. It's work as 139"output", but made transforming only for sequences 140 141ESC ( char 142 143what are used for codeset switching. For example, if section 144 145esc( 146'B' 0x1B '(' 'K' 147 148present in some map-file - then esc-sequence ESC(B will be transformed 149into ESC(K during output. 150 151 1525. Examples 153 154The directory examples/ contains some example files: 155 156 default - file showing the map_file to use for each tty 157 158Map-files: 159 160 altkoi.map - the program is in alternative DOS encoding, 161 the terminal - koi8-r 162 koiualt.map - program is koi8-u, terminal - alternative 163 koiumain.map - program is koi8-u, terminal - basic GOST 164 k180.map - same as previous + mapping disabling/enabling 165 (section "control") 166 sm7238.map - program is koi8-u, terminal - SM7238 in mode 167 "UP.RUS" (symbols in basic GOST with vt100 168 pseudo-graphics) 169 dos2koi.map - program is CP-866, terminal - koi8-r 170 win2koi.map - program is CP-1251, terminal - koi8-r 171 172The above example files are best viewed using a koi8 font (Russian). 173"Alternative" is a special encoding derived from MS DOS and used 174primarily in Russia. 175