MANDOC-PRECONV(1)

NAME
mandoc-preconv - recode multibyte UNIX manuals

SYNOPSIS
mandoc-preconv [-D enc] [-e enc] [file]

DESCRIPTION
The mandoc-preconv utility recodes multibyte UNIX manual files into mandoc(1) ( or other troff system supporting the ‘\[uNNNN]’ escape sequence) input.

By default, it parses from standard output, determining encoding as described in Algorithm.

Its arguments are as follows:

-D enc
    The default encoding.

-e enc
    The document's encoding.

file
    The input file.

The recoded input is written to standard output: Unicode characters in the ASCII range are printed as regular ASCII characters, while those above this range are printed using the ‘\[uNNNN]’ format documented in mandoc_char(7).

If input bytes are improperly formed in the current encoding, they're passed unmodified to standard output. For some encodings, such as UTF-8, unrecoverable input sequences will cause mandoc-preconv to stop processing and exit.

  Algorithm
An encoding is chosen according to the following steps:

1.  From the argument passed to -e enc.

2.  If a BOM exists, UTF-8 encoding is selected.

3.  From the coding tags parsed from "File Variables" on the first two lines of input. A file variable is an input line of the form

        .\" -*- key: val [; key: val ]* -*-

    A coding tag variable is where key is "coding" and val is the name of the encoding. A typical file variable with a coding tag is

        .\" -*- mode: troff; coding: utf-8 -*-

4.  From the argument passed to -D enc.

5.  If all else fails, Latin-1 is used.

The mandoc-preconv utility recognises the UTF-8, us-ascii, and latin-1 encodings as passed to the -e and -D arguments, or as coding tags. Encodings are matched case-insensitively.

EXIT STATUS

EXAMPLES
Explicitly page a UTF-8 manual foo.1 in the current locale:

    $ mandoc-preconv -e utf-8 foo.1 | mandoc -Tlocale | less

SEE ALSO
mandoc(1), mandoc_char(7)

STANDARDS
The mandoc-preconv utility references the US-ASCII character set standard, ANSI_X3.4-1968; the Latin-1 character set standard, ISO/IEC 8859-1:1998; the UTF-8 character set standard; and UCS (Unicode), ISO/IEC 10646.

HISTORY
The mandoc-preconv utility first appeared in the GNU troff (“groff”) system in December 2005, authored by Tomohiro Kubota and Werner Lemberg. The implementation that is part of the mandoc(1) utility appeared in May 2011.

AUTHORS
The mandoc-preconv utility was written by Kristaps Dzonsons <kristaps@bsd.lv>.