Add a new man-recode program

This has an interface designed for bulk conversion, and so can be much
faster than running "man --recode" on each page.

Fixes Debian bug #933576.

* bootstrap.conf (gnulib_modules): Add renameat, tempname, and unlinkat.
* src/man-recode.c: New file.
* src/Makefile.am (bin_PROGRAMS): Add man-recode.
(man_recode_LDADD, man_recode_SOURCES): Add.
* src/tests/man-recode-in-place, src/tests/man-recode-suffix: New files.
* src/tests/Makefile.am (ALL_TESTS): Add man-recode-in-place and
man-recode-suffix.
* .gitignore: Add src/man-recode.
* po/POTFILES.in: Add src/man-recode.c.

* m4/man-trans-subst.m4 (MAN_TRANS_SUBST): Adjust to support program
names containing dashes.
* configure.ac: Add substitutions for man-recode.

* man/man1/man-recode.man1: New file.
* man/man1/man.man1 (Main modes of operation): Add a note to the
description of --recode suggesting man-recode instead.
* man/man1/manconv.man1 (SEE ALSO): Add reference to man-recode(1).
* man/Makefile.am (man1_MANS): Add man1/man-recode.1.
* man/da/Makefile.am (man1_MANS): Likewise.
* man/de/Makefile.am (man1_MANS): Likewise.
* man/es/Makefile.am (man1_MANS): Likewise.
* man/fr/Makefile.am (man1_MANS): Likewise.
* man/id/Makefile.am (man1_MANS): Likewise.
* man/ja/Makefile.am (man1_MANS): Likewise.
* man/nl/Makefile.am (man1_MANS): Likewise.
* man/pl/Makefile.am (man1_MANS): Likewise.
* man/pt/Makefile.am (man1_MANS): Likewise.
* man/pt_BR/Makefile.am (man1_MANS): Likewise.
* man/ru/Makefile.am (man1_MANS): Likewise.
* man/sr/Makefile.am (man1_MANS): Likewise.
* man/sv/Makefile.am (man1_MANS): Likewise.
* man/tr/Makefile.am (man1_MANS): Likewise.
* man/zh_CN/Makefile.am (man1_MANS): Likewise.
* man/po4a/po4a.cfg: Add support for man-recode.
* man/replace.sin.in: Substitute %man_recode% and %thman_recode%.

* NEWS: Document this.

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).