# preconv

## Name



           preconv - prepare files for typesetting with _groff_
    


## Synopsis



           **preconv**[**-dr**] [**-D** _fallback-encoding_] [**-e** _encoding_] [_file_ ...]
    
           **preconv -h**
    
           **preconv --help**
    
           **preconv -v**
    
           **preconv --version**
    


## Description



           _preconv_ reads each _file_ , converts its encoded characters to a form
           _troff_(1) can interpret, and sends the result to the standard
           output stream.  Currently, this means that code points in the
           range 0–127 in ISO 646:1991 IRV (US-ASCII), ISO 8859, or Unicode
           remain as-is and the remainder are converted to the _groff_ special
           character form “**\[u** _XXXX_**]** ”, where _XXXX_ is a hexadecimal number of
           four to six digits corresponding to a Unicode code point.  By
           default, _preconv_ also inserts a _roff_ **.lf** request at the beginning
           of each _file_ , identifying it for the benefit of later processing
           (including diagnostic messages); the **-r** option suppresses this
           behavior.
    
           In typical usage scenarios, _preconv_ need not be run directly;
           instead it should be invoked with the **-k** or **-K** options of _groff_.
           If no _file_ operands are present, or if _file_ is “**-** ”, _preconv_ reads
           the standard input stream.
    
           _preconv_ selects an input encoding with the following algorithm,
           stopping at the first success.
    
           1.  If the input encoding has been explicitly specified with
               option **-e** , use it.
    
           2.  If the input starts with a Unicode Byte Order Mark, select
               UTF-8, UTF-16, or UTF-32 accordingly.
    
           3.  If the input stream is seekable, check the first two input
               lines for a GNU Emacs file-local variable identifying the
               character encoding, here referred to as the “coding tag”.  If
               found, use it.
    
           4.  If the input stream is seekable, and if the _uchardet_ library
               is available on the system, use it to try to infer the
               encoding of the file.
    
           5.  If the **-D** option specifies an encoding, use it.
    
           6.  Use the encoding specified by the current locale (_LC_CTYPE_),
               unless the locale is “C”, “POSIX”, or empty, in which case
               assume ISO Latin-1 (8859-1).
    
           The coding tag and _uchardet_ methods in the above procedure rely
           upon a seekable input stream; when _preconv_ reads from a pipe, the
           stream is not seekable, and these detection methods are skipped.
           If character encoding detection of your input is unreliable,
           arrange for one of the other methods to succeed by using _preconv_ 's
           **-D** or **-e** options, or by configuring your locale appropriately.
           _groff_ also supports a _GROFF_ENCODING_ environment variable, which
           can be overridden by its **-K** option.  Valid values for (or
           parameters to) all of these are enumerated in the lists of
           recognized coding tags in the next subsection, and are further
           influenced by _iconv_ library support.
    
       **Coding tags**
           Text editors that support more than a single character encoding
           need tags within the input files to mark the file's encoding.
           While it is possible to guess the right input encoding with the
           help of heuristics that produce good results for a preponderance
           of natural language texts, they are not absolutely reliable.
           Heuristics can fail on inputs that are too short or don't
           represent a natural language.
    
           Consequently, _preconv_ supports the coding tag convention used by
           GNU Emacs (with some restrictions).  This notation appears in
           specially marked regions of an input file designated for “file-
           local variables”.
    
           _preconv_ interprets the following syntax if it occurs in a _roff_
           comment in the first or second line of the input.  Both “\"” and
           “\#” comment forms are recognized, but the control (or no-break
           control) character must be the default and must begin the line.
           Similarly, the escape character must be the default.
                  **-*-**[...**;**] **coding:**_encoding_[**;**...] **-*-**
    
           The only variable _preconv_ interprets is “coding”, which can take
           the values listed below.
    
           The following list comprises all MIME “charset” parameter values
           recognized, case-insensitively, by _preconv_.
                  big5, cp1047, euc-jp, euc-kr, gb2312, iso-8859-1,
                  iso-8859-2, iso-8859-5, iso-8859-7, iso-8859-9,
                  iso-8859-13, iso-8859-15, koi8-r, us-ascii, utf-8, utf-16,
                  utf-16be, utf-16le
    
           In addition, the following list of other coding tags is
           recognized, each of which is mapped to an appropriate value from
           the list above.
                  ascii, chinese-big5, chinese-euc, chinese-iso-8bit,
                  cn-big5, cn-gb, cn-gb-2312, cp878, csascii, csisolatin1,
                  cyrillic-iso-8bit, cyrillic-koi8, euc-china, euc-cn,
                  euc-japan, euc-japan-1990, euc-korea, greek-iso-8bit,
                  iso-10646/utf8, iso-10646/utf-8, iso-latin-1, iso-latin-2,
                  iso-latin-5, iso-latin-7, iso-latin-9, japanese-euc,
                  japanese-iso-8bit, jis8, koi8, korean-euc, korean-iso-8bit,
                  latin-0, latin1, latin-1, latin-2, latin-5, latin-7,
                  latin-9, mule-utf-8, mule-utf-16, mule-utf-16be,
                  mule-utf-16-be, mule-utf-16be-with-signature,
                  mule-utf-16le, mule-utf-16-le,
                  mule-utf-16le-with-signature, utf8, utf-16-be,
                  utf-16-be-with-signature, utf-16be-with-signature,
                  utf-16-le, utf-16-le-with-signature,
                  utf-16le-with-signature
    
           Any “-dos”, “-unix”, or “-mac” suffix on a coding tag (which
           indicates the end-of-line convention used in the file) is ignored
           during comparison with the above tags.
    
       [1miconv[24m support
           While _preconv_ recognizes all of the coding tags listed above, it
           is capable on its own of interpreting only two encodings:
           ISO Latin-1 and and UTF-8.  ISO 646:1991 IRV (US-ASCII) is a
           proper subset of both these encodings.  If _iconv_(3) support is
           configured at compile time and available at run time, all others
           are passed to _iconv_ library functions, which may recognize many
           additional encoding strings.  The command “**preconv -v** ” discloses
           whether _iconv_ support is configured.
    
           The use of _iconv_ means that characters in the input that encode
           invalid code points for that encoding may be dropped from the
           output stream or mapped to the Unicode replacement character
           (U+FFFD).  Compare the following examples using the input “café”
           (note the “e” with an acute accent), which due to its short length
           challenges inference of the encoding used.
                  printf 'caf\351\n' | LC_ALL=en_US.UTF-8 preconv
                  printf 'caf\351\n' | preconv -e us-ascii
                  printf 'caf\351\n' | preconv -e latin-1
           The fate of the accented “e” differs in each case.  In the first,
           _uchardet_ fails to detect an encoding (though the library on your
           system may behave differently) and _preconv_ falls back to the
           locale settings, where octal 351 starts an incomplete UTF-8
           sequence and results in the Unicode replacement character.  In the
           second, it is not a representable character in the declared input
           encoding of US-ASCII and is discarded by _iconv_.  In the last, it
           is correctly detected and mapped.
    
       **Limitations**
           _preconv_ cannot perform any transformation on input that it cannot
           see.  Examples include files that are interpolated by
           preprocessors that run subsequently, including _soelim_(1); files
           included by _troff_ itself through “**so** ” and similar requests; and
           string definitions passed to _troff_ through its **-d** command-line
           option.
    
           _preconv_ assumes that its input uses the default escape character,
           a backslash **\** , and writes special character escape sequences
           accordingly.
    


## Options



           **-h** and **--help** display a usage message, while **-v** and **--version** show
           version and configuration information; all exit afterward.
    
           **-d** Emit debugging messages to the standard error stream.
    
           **-D** _fbenc_
                  Select the fallback encoding _fbenc_ if all detection methods
                  fail.
    
           **-e** _enc_ Skip detection and select encoding _enc_ ; see _groff_ 's **-K**
                  option.
    
           **-r** Write files “raw”; do not add **.lf** requests.
    


## Exit status



           _preconv_ exits with status **0** on successful operation, status **2** if
           the program cannot interpret its command-line arguments, and
           status **1** if it encounters an error during operation.
    


## See also



           _groff_(1), _iconv_(3), _locale_(7)
    


* * *