preconv

preconv [-r] [-L encoding] [-I encoding] [file...]

-r
    Perform reverse conversion. This is used when converting groff's internal character representation back to an external encoding for output.

-L encoding
    Specify the output encoding for the conversion. This determines the character set to which the input will be converted.

-I encoding
    Specify the input encoding. This informs preconv about the character set of the source file(s) or standard input.

file...
    One or more input files to be processed. If no files are specified, preconv reads from standard input (stdin).

preconv is an internal utility of the groff typesetting system, primarily used to convert character encodings of input files. It processes input to a common internal representation that groff's troff formatter and its preprocessors (like eqn for equations or tbl for tables) can understand.

It acts as a crucial pre-processor, typically invoked automatically by groff when needed, rather than being run directly by users from the command line. preconv handles various input encodings (e.g., UTF-8, Latin-1) and ensures that special characters, non-ASCII characters, and multi-byte characters are correctly interpreted. This guarantees consistent and accurate rendering of documents, especially those containing diverse character sets or international text.

preconv is primarily an internal component of the groff typesetting pipeline and is not typically intended for direct user invocation. Its behavior is largely orchestrated and controlled by the main groff command's options and environment settings. For general character encoding conversion, the iconv(1) utility is usually more appropriate.

preconv reads input from the files specified on the command line, or from standard input (stdin) if no files are provided. The converted output is then written to standard output (stdout).

While preconv can be run manually, its primary function is within the automated groff pipeline. groff automatically detects the need for character conversion based on input characteristics and system locale, and then intelligently inserts preconv into the processing chain before the main troff formatter or other preprocessors. This makes its operation largely transparent to the end user.

preconv has been an integral part of the groff (GNU roff) typesetting system almost since its inception. groff was developed as a free replacement for the AT&T roff and troff text formatters. As groff evolved to support internationalization and diverse character sets, preconv became crucial for ensuring that documents written in various encodings (like UTF-8) could be correctly processed and formatted. Its role is fundamental in groff's robust handling of diverse text inputs, making it a critical, albeit often hidden, component of the typesetting pipeline.

groff(1), troff(1), eqn(1), tbl(1), groff_char(7), iconv(1)