Convert a Manual Page Between Encodings with manconv

A manual page written in ISO-8859-1 turns to garbage once your pipeline expects UTF-8, and manconv fixes that without touching the original file. Examples use manconv from man-db 2.12.0, package version 2.12.0-4build2. Allow about ten minutes.

You need a shell, a readable manual-page file and a writable output directory. This guide runs as an ordinary user and never edits anything under /usr/share/man, so sudo is not normally needed.

1. Check the installed command

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

$ 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. If command -v manconv returns a path, use that; otherwise substitute the path your package manager reports.
• -f names the source encoding, -t the destination. An optional file name follows; output always goes to standard output.

2. Convert a known UTF-8 page

Make a working copy first. That avoids writing into a package-managed directory and leaves you a file you can compare against 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 your real file. A zero exit status only means the conversion ran; keep the source and inspect the result before relying on it.

3. Try more than one input encoding when you are not sure

Manual pages sometimes ship with no explicit encoding declaration. Pass a colon-separated list and manconv tries each in order:

$ /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

Order matters: put the most likely encoding first, then actually check the result. A permissive legacy decoder can happily accept bytes meant for a different encoding and produce plausible but wrong characters, so a clean exit status is not proof the text is correct.

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

That command is separate from manconv. It asks man to display the converted file through a pager; it never changes the file itself.

4. Let a first-line declaration win

manconv recognises an encoding declaration on a page's first line, such as '\" -*- coding: UTF-8 -*-. Once it finds one, that declaration overrides whatever you pass with -f, so a command-line guess cannot silently override metadata the page author wrote in.

Do not add or edit a declaration just to silence an error. That changes the meaning of the source and will make a later conversion repeat the same mistake. If a page declares one encoding but its actual bytes came from another, leave the original alone and resolve the mismatch with the package or page maintainer.

5. Diagnose a failed conversion

Run without --quiet while you are investigating, since 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, so treat the line above as illustrative, not literal. Check the input path, confirm the claimed source encoding, and try a controlled list of likely candidates. Use --debug for a diagnostic trace when nothing obvious explains the failure:

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

--quiet suppresses the error messages, it does not make bad input valid. Leave it out of a first test; if a script needs it, check the exit status and verify the output file regardless.

6. Replace a working copy only after checking it

Write a temporary sibling first and move it into place only once you have looked at it. This changes state, so back up anything that matters first:

$ 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 that final mv. Remove the incomplete .new file when convenient.