3 files changed, 92 insertions, 1 deletions
diff --git a/man/man1/man-recode.man1 b/man/man1/man-recode.man1
new file mode 100644
index 00000000..0705a570
--- /dev/null
+++ b/man/man1/man-recode.man1
@@ -0,0 +1,85 @@
+.\" Man page for man-recode
+.\"
+.\" Copyright (C) 2019 Colin Watson <cjwatson@debian.org>
+.\"
+.\" You may distribute under the terms of the GNU General Public
+.\" License as specified in the file COPYING that comes with the
+.\" man-db distribution.
+.pc
+.TH %thman_recode% 1 "%date%" "%version%" "Manual pager utils"
+.SH NAME
+%man_recode% \- convert manual pages to another encoding
+.SH SYNOPSIS
+.B %man_recode%
+.B \-t
+.I to-code
+{\|\fB\-\-suffix=\fIsuffix\/\fR\||\|\c
+.BR \-\-in\-place \|}
+.RB [\| \-dqhV \|]
+.RI [\| filename \|]
+.SH DESCRIPTION
+.B %man_recode%
+converts multiple manual pages from one encoding to another, guessing the
+appropriate input encoding for each one.
+It is useful when permanently recoding pages written in legacy character
+sets, or in build systems that need to recode a set of pages to a single
+common encoding (usually UTF\-8) for installation.
+When converting many manual pages, this program is much faster than running
+.B %man% \-\-recode
+or
+.B %manconv%
+on each page.
+.PP
+If an encoding declaration is found on the first line of a manual page, then
+that declaration is used as the input encoding for that page.
+Failing that, the input encoding is guessed based on the file name.
+.PP
+Encoding declarations have the following form:
+.PP
+.RS
+.nf
+.if !'po4a'hide' \&\(aq\e" \-*\- coding: UTF\-8 \-*\-
+.fi
+.RE
+.PP
+or (if manual page preprocessors are also to be declared):
+.PP
+.RS
+.nf
+.if !'po4a'hide' \&\(aq\e" t \-*\- coding: ISO\-8859\-1 \-*\-
+.fi
+.RE
+.SH OPTIONS
+.TP
+\fB\-t\fR \fIencoding\/\fR, \fB\-\-to\-code=\fIencoding\fR
+Convert manual pages to
+.IR encoding .
+.TP
+\fB\-\-suffix=\fIsuffix\fR
+Form each output file name by appending
+.IR suffix
+to the input file name, after removing any compression extension.
+.TP
+.if !'po4a'hide' .B \-\-in\-place
+Overwrite each input file with the output, after removing any compression
+extension.
+.TP
+.if !'po4a'hide' .BR \-q ", " \-\-quiet
+Do not issue error messages when the page cannot be converted.
+.TP
+.if !'po4a'hide' .BR \-d ", " \-\-debug
+Print debugging information.
+.TP
+.if !'po4a'hide' .BR \-h ", " \-\-help
+Print a help message and exit.
+.TP
+.if !'po4a'hide' .BR \-V ", " \-\-version
+Display version information.
+.SH "SEE ALSO"
+.if !'po4a'hide' .IR iconv (1),
+.if !'po4a'hide' .IR %man% (1),
+.if !'po4a'hide' .IR %manconv% (1)
+.SH AUTHOR
+.nf
+.if !'po4a'hide' Colin Watson (cjwatson@debian.org).
+.fi
diff --git a/man/man1/man.man1 b/man/man1/man.man1
index 3ef6517f..3e313aa6 100644
--- a/man/man1/man.man1
+++ b/man/man1/man.man1
@@ -542,6 +542,11 @@ However, this option allows you to convert several manual pages to a single
 encoding without having to explicitly state the encoding of each, provided
 that they were already installed in a structure similar to a manual page
 hierarchy.
+.IP
+Consider using
+.BR %man_recode% (1)
+instead for converting multiple manual pages, since it has an interface
+designed for bulk conversion and so can be much faster.
 .SS "Finding manual pages"
 .TP
 .BI \-L\  locale \fR,\ \fB\-\-locale= locale
diff --git a/man/man1/manconv.man1 b/man/man1/manconv.man1
index 133f7dc1..29f38628 100644
--- a/man/man1/manconv.man1
+++ b/man/man1/manconv.man1
@@ -72,7 +72,8 @@ Print a help message and exit.
 Display version information.
 .SH "SEE ALSO"
 .if !'po4a'hide' .IR iconv (1),
-.if !'po4a'hide' .IR man (1)
+.if !'po4a'hide' .IR %man% (1),
+.if !'po4a'hide' .IR %man_recode% (1)
 .SH AUTHOR
 .nf
 .if !'po4a'hide' Colin Watson (cjwatson@debian.org).