Convert a Manual Page Between Encodings with manconv

You will finish with a repeatable way to convert a manual page to a chosen character encoding while leaving the source file untouched. The examples use manconv from man-db 2.12.0, installed here as package version 2.12.0-4build2.

Allow about ten minutes. You need a shell, a readable manual-page file, and permission to write the output directory. This guide uses an ordinary user account. It does not edit files under /usr/share/man, so sudo is not normally needed.

1. Check the installed command

On this installation the executable is in man-db's private directory, so it is safest to ask the package where it put the file and invoke that path explicitly:

$ dpkg-query -W -f='${Package} ${Version}\n' man-db
man-db 2.12.0-4build2
$ command -v manconv || true
$ /usr/libexec/man-db/manconv --version
manconv 2.12.0

Your distribution may put manconv on PATH. Use command -v manconv if it returns a path, or substitute the installed path shown by your package manager. The command takes a source encoding with -f, a destination encoding with -t, and an optional file name. Its output goes to standard output.

Checkpoint: confirm the executable and version before putting it in a script. If the version is not 2.12.0, read that machine's manual with man manconv before relying on output details.

2. Convert a known UTF-8 page

First make a working copy. This avoids writing into a package-managed directory and gives you a file that can be compared with the source:

$ cp --preserve=all /path/to/page.1 /tmp/page.1
$ /usr/libexec/man-db/manconv -f UTF-8 -t ISO-8859-1 /tmp/page.1 > /tmp/page-latin1.1
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file /tmp/page-latin1.1
/tmp/page-latin1.1: troff or preprocessor input text, ISO-8859 text

Replace /path/to/page.1 with a real file. The -f value describes the input, while -t names the encoding to produce. The command writes converted content to standard output, which is why the shell redirection is present. A successful exit status means the conversion completed; keep the source and inspect the result before using it.

Do not use > /path/to/page.1 for an in-place conversion. Shell redirection truncates the destination before manconv starts, so a typo, failed conversion or unexpected output can destroy the only copy.

3. Try more than one possible input encoding

Manual pages are sometimes installed without an explicit encoding declaration. Pass a colon-separated list when the input is uncertain. manconv tries the encodings in sequence:

$ /usr/libexec/man-db/manconv \
    -f UTF-8:ISO-8859-1:CP1252 \
    -t UTF-8 \
    /tmp/page.1 > /tmp/page-utf8.1
$ file /tmp/page-utf8.1
/tmp/page-utf8.1: troff or preprocessor input text, Unicode text, UTF-8 text

The order matters. Put the most likely encoding first, then check the converted file. A permissive legacy decoder can accept bytes that were intended as another encoding, producing plausible but wrong characters. This is a reason to inspect the page, not a reason to assume that the first successful exit status proves the text is correct.

Checkpoint: compare the result with a trusted rendering or a known-good copy. For a troff page, a quick text-level check is:

$ man --local-file /tmp/page-utf8.1 | less

That command is separate from manconv. It asks the local man program to render the converted file and may use a pager, but it does not change the file.

4. Let an encoding declaration take precedence

manconv recognises an encoding declaration on the first line of a manual page, such as '\" -*- coding: UTF-8 -*-. When it finds one, that declaration overrides the input encodings supplied with -f. This prevents a command-line guess from silently overriding metadata written by the page author.

Do not add or alter a declaration merely to silence an error. That changes the meaning of the source and can make later conversions repeat the mistake. If a page declares one encoding but its bytes were produced with another, preserve the original and resolve that mismatch with the package or page maintainer.

5. Diagnose a failed conversion

Run without --quiet while investigating. The default is to report conversion errors:

$ /usr/libexec/man-db/manconv -f UTF-8 -t ISO-8859-1 /tmp/page.1 > /tmp/page-latin1.1
manconv: ...
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic depends on the bytes in your file. Do not treat the illustrative error line above as a literal string. Check the input path, confirm the claimed source encoding, and try a controlled list of likely encodings. Use --debug when you need manconv's diagnostic trace:

$ /usr/libexec/man-db/manconv --debug -f UTF-8:ISO-8859-1 -t UTF-8 /tmp/page.1 > /tmp/page-debug.1

--quiet suppresses error messages when a page cannot be converted. It does not make bad input valid, so leave it out of an initial test. If a script must use it, check the exit status and verify the output file before passing it to another program.

6. Replace a result only after checking it

If the converted file is intended to replace a working copy, write a temporary sibling first and move it into place only after verification. This changes state, so take a backup when the existing file matters:

$ cp --preserve=all /path/to/page.1 /path/to/page.1.bak
$ /usr/libexec/man-db/manconv -f UTF-8 -t UTF-8 /path/to/page.1 > /path/to/page.1.new
$ test -s /path/to/page.1.new
$ man --local-file /path/to/page.1.new | less
$ mv /path/to/page.1.new /path/to/page.1

If conversion or inspection fails, do not run the final mv. Remove the incomplete .new file when convenient. To recover the previous version, restore the backup with cp --preserve=all /path/to/page.1.bak /path/to/page.1. Do not delete the backup until the replacement has been checked; that deletion is irreversible.