contrib/groff/src/preproc/preconv/preconv.man

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