man/pre-preconv.1.in

   1 .ig
   2 @ @L_P_PRECONV@.1
   3
   4 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
   5
   6 Copyright (C) 2006 - 2008 Free Software Foundation, Inc.
   7
   8 Permission is granted to make and distribute verbatim copies of
   9 this manual provided the copyright notice and this permission notice
  10 are preserved on all copies.
  11
  12 Permission is granted to copy and distribute modified versions of this
  13 manual under the conditions for verbatim copying, provided that the
  14 entire resulting derived work is distributed under the terms of a
  15 permission notice identical to this one.
  16
  17 Permission is granted to copy and distribute translations of this
  18 manual into another language, under the above conditions for modified
  19 versions, except that this permission notice may be included in
  20 translations approved by the Free Software Foundation instead of in
  21 the original English.
  22 ..
  23 .
  24 .do nr __compat \n[.C]
  25 .cp 0
  26 .
  27 .
  28 .TH @U_P_PRECONV@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
  29 .
  30 .
  31 .SH NAME
  32 @L_P_PRECONV@ \- convert encoding of input files
  33 .
  34 .
  35 .SH SYNOPSIS
  36 .SY @L_P_PRECONV@
  37 .OP \-dr
  38 .OP \-e encoding
  39 .RI [ files
  40 .IR .\|.\|. ]
  41 .
  42 .SY @
  43 .B \-h
  44 |
  45 .B \-\-help
  46 .
  47 .SY @L_P_PRECONV@
  48 .B \-v
  49 |
  50 .B \-\-version
  51 .YS
  52 .
  53 .PP
  54 It is possible to have whitespace between the
  55 .B \-e
  56 command line option and its parameter.
  57 .
  58 .
  59 .SH DESCRIPTION
  60 .B @L_P_PRECONV@
  61 reads
  62 .I files
  63 and converts its encoding(s) to a form
  64 .BR @L_TROFF@ (@MAN1EXT@)
  65 can process, sending the data to standard output.
  66 Currently, this means ASCII characters and `\e[uXXXX]' entities, where
  67 `XXXX' is a hexadecimal number with four to six digits, representing a
  68 Unicode input code.
  69 Normally,
  70 .B @L_P_PRECONV@
  71 should be invoked with the
  72 .B \-k
  73 and
  74 .B \-K
  75 options of
  76 .BR @L_ROFF@ .
  77 .
  78 .
  79 .SH OPTIONS
  80 .TP
  81 .B \-d
  82 Emit debugging messages to standard error (mainly the used encoding).
  83 .
  84 .TP
  85 .BI \-D encoding
  86 Specify default encoding if everything fails (see below).
  87 .
  88 .TP
  89 .BI \-e encoding
  90 Specify input encoding explicitly, overriding all other methods.
  91 This corresponds to
  92 .BR @L_ROFF@ 's
  93 .BI \-K encoding
  94 option.
  95 Without this switch,
  96 .B @L_P_PRECONV@
  97 uses the algorithm described below to select the input encoding.
  98 .
  99 .TP
 100 .B \-\-help
 101 .TQ
 102 .B \-h
 103 Print help message.
 104 .
 105 .TP
 106 .B \-r
 107 Do not add .lf requests.
 108 .
 109 .TP
 110 .B \-\-version
 111 .TQ
 112 .B \-v
 113 Print version number.
 114 .
 115 .
 116 .SH USAGE
 117 .B @L_P_PRECONV@
 118 tries to find the input encoding with the following algorithm.
 119 .
 120 .IP 1.
 121 If the input encoding has been explicitly specified with option
 122 .BR \-e ,
 123 use it.
 124 .
 125 .IP 2.
 126 Otherwise, check whether the input starts with a
 127 .I Byte Order Mark
 128 (BOM, see below).
 129 If found, use it.
 130 .
 131 .IP 3.
 132 Finally, check whether there is a known
 133 .I coding tag
 134 (see below) in either the first or second input line.
 135 If found, use it.
 136 .
 137 .IP 4.
 138 If everything fails, use a default encoding as given with option
 139 .BR \-D ,
 140 by the current locale, or `latin1' if the locale is set to `C',
 141 `POSIX', or empty (in that order).
 142 .
 143 .PP
 144 Note that the
 145 .B @L_ROFF@
 146 program supports a
 147 .B @U_ROFF@_ENCODING
 148 environment variable which is eventually expanded to option
 149 .BR \-k .
 150 .
 151 .SS "Byte Order Mark"
 152 The Unicode Standard defines character U+FEFF as the Byte Order Mark
 153 (BOM).
 154 On the other hand, value U+FFFE is guaranteed not be a Unicode character at
 155 all.
 156 This allows to detect the byte order within the data stream (either
 157 big-endian or lower-endian), and the MIME encodings \%`UTF-16' and
 158 \%`UTF-32' mandate that the data stream starts with U+FEFF.
 159 Similarly, the data stream encoded as \%`UTF-8' might start with a BOM (to
 160 ease the conversion from and to \%UTF-16 and \%UTF-32).
 161 In all cases, the byte order mark is
 162 .I not
 163 part of the data but part of the encoding protocol; in other words,
 164 .BR @L_P_PRECONV@ 's
 165 output doesn't contain it.
 166 .
 167 .PP
 168 Note that U+FEFF not at the start of the input data actually is emitted;
 169 it has then the meaning of a `zero width no-break space' character \[en]
 170 something not needed normally in
 171 .BR @L_ROFF@ .
 172 .
 173 .SS "Coding Tags"
 174 Editors which support more than a single character encoding need tags
 175 within the input files to mark the file's encoding.
 176 While it is possible to guess the right input encoding with the help of
 177 heuristic algorithms for data which represents a greater amount of a natural
 178 language, it is still just a guess.
 179 Additionally, all algorithms fail easily for input which is either too short
 180 or doesn't represent a natural language.
 181 .
 182 .PP
 183 For these reasons,
 184 .B @L_P_PRECONV@
 185 supports the coding tag convention (with some restrictions) as used by
 186 .B "GNU Emacs"
 187 and
 188 .B XEmacs
 189 (and probably other programs too).
 190 .
 191 .PP
 192 Coding tags in
 193 .B "GNU Emacs"
 194 and
 195 .B XEmacs
 196 are stored in so-called
 197 .IR "File Variables" .
 198 .B @L_P_PRECONV@
 199 recognizes the following syntax form which must be put into a troff comment
 200 in the first or second line.
 201 .
 202 .RS
 203 .PP
 204 \-*\-
 205 .IR tag1 :
 206 .IR value1 ;
 207 .IR tag2 :
 208 .IR value2 ;
 209 \&.\|.\|.\& \-*\-
 210 .RE
 211 .
 212 .PP
 213 The only relevant tag for
 214 .B @L_P_PRECONV@
 215 is `coding' which can take the values listed below.
 216 Here an example line which tells
 217 .B Emacs
 218 to edit a file in troff mode, and to use \%latin2 as its encoding.
 219 .
 220 .RS
 221 .PP
 222 .EX
 223 \&.\[rs]" \-*\- mode: troff; coding: latin-2 \-*\-
 224 .EE
 225 .RE
 226 .
 227 .PP
 228 The following list gives all MIME coding tags (either lowercase or
 229 uppercase) supported by
 230 .BR @L_P_PRECONV@ ;
 231 this list is hard-coded in the source.
 232 .
 233 .RS
 234 .PP
 235 .ad l
 236 \%big5, \%cp1047, \%euc-jp, \%euc-kr, \%gb2312, \%iso-8859-1, \%iso-8859-2,
 237 \%iso-8859-5, \%iso-8859-7, \%iso-8859-9, \%iso-8859-13, \%iso-8859-15,
 238 \%koi8-r, \%us-ascii, \%utf-8, \%utf-16, \%utf-16be, \%utf-16le
 239 .ad
 240 .RE
 241 .
 242 .PP
 243 In addition, the following hard-coded list of other tags is recognized which
 244 eventually map to values from the list above.
 245 .
 246 .RS
 247 .PP
 248 .ad l
 249 \%ascii, \%chinese-big5, \%chinese-euc, \%chinese-iso-8bit, \%cn-big5,
 250 \%\%cn-gb, \%cn-gb-2312, \%cp878, \%csascii, \%csisolatin1,
 251 \%cyrillic-iso-8bit, \%cyrillic-koi8, \%euc-china, \%euc-cn, \%euc-japan,
 252 \%euc-japan-1990, \%euc-korea, \%greek-iso-8bit, \%iso-10646/utf8,
 253 \%iso-10646/utf-8, \%iso-latin-1, \%iso-latin-2, \%iso-latin-5,
 254 \%iso-latin-7, \%iso-latin-9, \%japanese-euc, \%japanese-iso-8bit, \%jis8,
 255 \%koi8, \%korean-euc, \%korean-iso-8bit, \%latin-0, \%latin1, \%latin-1,
 256 \%latin-2, \%latin-5, \%latin-7, \%latin-9, \%mule-utf-8, \%mule-utf-16,
 257 \%mule-utf-16be, \%mule-utf-16-be, \%mule-utf-16be-with-signature,
 258 \%mule-utf-16le, \%mule-utf-16-le, \%mule-utf-16le-with-signature, \%utf8,
 259 \%utf-16-be, \%utf-16-be-with-signature, \%utf-16be-with-signature,
 260 \%utf-16-le, \%utf-16-le-with-signature, \%utf-16le-with-signature
 261 .ad
 262 .RE
 263 .
 264 .PP
 265 Those tags are taken from
 266 .B "GNU Emacs"
 267 and
 268 .BR XEmacs ,
 269 together with some aliases.
 270 Trailing \%`-dos', \%`-unix', and \%`-mac' suffixes of coding tags (which
 271 give the end-of-line convention used in the file) are stripped off before
 272 the comparison with the above tags happens.
 273 .
 274 .SS "Iconv Issues"
 275 .B @L_P_PRECONV@
 276 by itself only supports three encodings: \%latin-1, cp1047, and \%UTF-8;
 277 all other encodings are passed to the
 278 .B iconv
 279 library functions.
 280 At compile time it is searched and checked for a valid
 281 .B iconv
 282 implementation; a call to `@L_P_PRECONV@ \-\-version' shows whether
 283 .B iconv
 284 is used.
 285 .
 286 .
 287 .SH BUGS
 288 .B @L_P_PRECONV@
 289 doesn't support
 290 .I "local variable lists"
 291 yet.
 292 This is a different syntax form to specify local variables at the end of a
 293 file.
 294 .
 295 .
 296 .SH "SEE ALSO"
 297 .BR @L_ROFF@ (@MAN1EXT@)
 298 .
 299 .cp \n[__compat]
 300 .rr __compat
 301 .
 302 .\" s-ts-mode