PRECONV

Section: User Commands (1)
Index Return to Main Contents

BSD mandoc

NAME

preconv - recode multibyte UNIX manuals

SYNOPSIS

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

DESCRIPTION

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

By default, it parses from standard output, determining encoding as described in Sx 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_char7.

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 preconv to stop processing and exit.

Algorithm

An encoding is chosen according to the following steps:

From the argument passed to -e enc
If a BOM exists, UTF-8 encoding is selected.
From the coding tags parsed from Qq 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 Qq coding and val is the name of the encoding. A typical file variable with a coding tag is

.\" -*- mode: troff; coding: utf-8 -*-
From the argument passed to -D enc
If all else fails, Latin-1 is used.

The 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

Ex -std

EXAMPLES

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

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

STANDARDS

The 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 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 preconv utility was written by An Kristaps Dzonsons , Mt kristaps@bsd.lv .

Index

NAME

SYNOPSIS

DESCRIPTION

Algorithm