-add missing man page

2 files changed, 112 insertions, 14 deletions

diff --git a/man/taler-auditor-sync.1 b/man/taler-auditor-sync.1
new file mode 100644
index 00000000..a686976a
--- /dev/null
+++ b/man/taler-auditor-sync.1
@@ -0,0 +1,95 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "TALER-AUDITOR-SYNC" "1" "Aug 08, 2021" "0.8" "GNU Taler"
+.SH NAME
+taler-auditor-sync \- tool to safely synchronize auditor database
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+\fBtaler\-auditor\-sync\fP
+[\fB\-s\fP\ \fIFILENAME\fP\ |\ \fB–source\-configuration=\fP‌\fIFILENAME\fP]
+[\fB\-d\fP\ \fIFILENAME\fP\ |\ \fB–destination\-configuration=\fP‌\fIFILENAME\fP]
+[\fB\-h\fP\ |\ \fB–help\fP]
+[\fB\-b\fP\ \fISIZE\fP\ |\ \fB–batch=\fP‌\fISIZE\fP]
+[\fB\-t\fP\ |\ \fB–terminate\-when\-synchronized\fP]
+[\fB\-v\fP\ |\ \fB–version\fP]
+[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP‌\fILOGLEVEL\fP]
+.SH DESCRIPTION
+.sp
+\fBtaler\-auditor\-sync\fP is a command\-line tool to synchronize the
+Taler auditor’s database in a safe way from a Taler exchange
+database. If the exchange database violates the assumed database
+invariants (as expressed by database constraints) or attempts to
+DELETE or UPDATE tables (at least those that the auditor relies
+upon), \fBtaler\-auditor\-sync\fP will not replicate those changes
+and instead halt with an error.
+.sp
+Its options are as follows:
+.INDENT 0.0
+.TP
+\fB\-s\fP \fIFILENAME\fP | \fB–source\-configuration=\fP‌\fIFILENAME\fP
+Use the configuration in \fIFILENAME\fP to access the original (source) exchange
+database to copy records from.
+.TP
+\fB\-d\fP \fIFILENAME\fP | \fB–destination\-configuration=\fP‌\fIFILENAME\fP
+Use the configuration in \fIFILENAME\fP to access the target (destination) exchange
+database to copy records to.
+.TP
+\fB\-t\fP | \fB–terminate\-when\-synchronized\fP
+The program should exit once the two databases are in sync, instead of continuously
+copying more records when the source database is updated.
+.TP
+\fB\-h\fP | \fB–help\fP
+Print short help on options.
+.TP
+\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP‌\fILOGLEVEL\fP
+Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP,
+\fBWARNING\fP, \fBERROR\fP\&.
+.TP
+\fB\-b\fP \fISIZE\fP | \fB–batch=\fP‌\fISIZE\fP
+Target number of records to copy in one transaction. Once the databases are
+in sync, the batch size is used to determine how long the process sleeps before
+trying to again synchronize the two databases. Not useful if \fB\-t\fP is used.
+.TP
+\fB\-v\fP | \fB–version\fP
+Print version information.
+.UNINDENT
+.SH SEE ALSO
+.sp
+taler\-auditor(1), taler.conf(5).
+.SH BUGS
+.sp
+Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic
+mail to <\fI\%taler@gnu.org\fP>.
+.SH AUTHOR
+GNU Taler contributors
+.SH COPYRIGHT
+2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+)
+.\" Generated by docutils manpage writer.
+.
diff --git a/man/taler.conf.5 b/man/taler.conf.5
index e23421ff..1300d3de 100644
--- a/man/taler.conf.5
+++ b/man/taler.conf.5
@@ -72,7 +72,10 @@ overrides these defaults.
 A configuration file may include another, by using the \fB@INLINE@\fP directive,
 for example, in \fBmain.conf\fP, you could write \fB@INLINE@ sub.conf\fP to
 include the entirety of \fBsub.conf\fP at that point in \fBmain.conf\fP\&.
-.. TODO: Document ‘taler\-config \-V’ in light of ‘@INLINE@’ in taler\-config(1).
+.sp
+Be extra careful when using \fBtaler\-config \-V VALUE\fP to change configuration
+values: it will destroy all uses of \fB@INLINE@\fP and furthermore remove all
+comments from the configuration file!
 .SS GLOBAL OPTIONS
 .sp
 The following options are from the “[taler]” section and used by
@@ -122,7 +125,7 @@ Port on which the HTTP server listens, e.g.\ 8080.
 .TP
 .B MASTER_PUBLIC_KEY
 Crockford Base32\-encoded master public key, public version of the
-exchange’s long\-time offline signing key.
+exchange\(aqs long\-time offline signing key.
 .TP
 .B MASTER_PRIV_FILE
 Location of the master private key on disk. Only used by tools that
@@ -145,12 +148,12 @@ For how long should clients cache \fB/keys\fP responses at most?
 .B TERMS_DIR
 Directory where the terms of service of the exchange operator can be fund.
 The directory must contain sub\-directories for every supported language,
-using the two\-character language code in lower case, e.g. “en/” or “fr/”.
+using the two\-character language code in lower case, e.g. "en/" or "fr/".
 Each subdirectory must then contain files with the terms of service in
 various formats.  The basename of the file of the current policy must be
 specified under \fBTERMS_ETAG\fP\&.  The extension defines the mime type.
-Supported extensions include “html”, “htm”, “txt”, “pdf”, “jpg”, “jpeg”,
-“png” and “gif”.  For example, using a \fBTERMS_ETAG\fP of “0”, the structure
+Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg",
+"png" and "gif".  For example, using a \fBTERMS_ETAG\fP of "0", the structure
 could be the following:
 .INDENT 7.0
 .IP \(bu 2
@@ -169,7 +172,7 @@ $TERMS_DIR/de/0.txt
 .TP
 .B TERMS_ETAG
 Basename of the file(s) in the \fBTERMS_DIR\fP with the current terms of service.
-The value is also used for the “Etag” in the HTTP request to control
+The value is also used for the "Etag" in the HTTP request to control
 caching.  Whenever the terms of service change, the \fBTERMS_ETAG\fP MUST also
 change, and old values MUST NOT be repeated.  For example, the date or
 version number of the terms of service SHOULD be used for the Etag.  If
@@ -185,7 +188,7 @@ Works the same as \fBTERMS_ETAG\fP, just for the privacy policy.
 .UNINDENT
 .SS EXCHANGE OFFLINE SIGNING OPTIONS
 .sp
-The following options must be in the section “[exchange\-offline]”.
+The following options must be in the section "[exchange\-offline]".
 .INDENT 0.0
 .TP
 .B MASTER_PRIV_FILE
@@ -211,7 +214,7 @@ this option will also be ignored.
 .UNINDENT
 .SS EXCHANGE RSA CRYPTO HELPER OPTIONS
 .sp
-The following options must be in the section “[taler\-exchange\-secmod\-rsa]”.
+The following options must be in the section "[taler\-exchange\-secmod\-rsa]".
 .INDENT 0.0
 .TP
 .B LOOKAHEAD_SIGN
@@ -238,7 +241,7 @@ Note that the \fBtaler\-exchange\-secmod\-rsa\fP also evaluates the \fB[coin_*]\
 configuration sections described below.
 .SS EXCHANGE EDDSA CRYPTO HELPER OPTIONS
 .sp
-The following options must be in the section “[taler\-exchange\-secmod\-eddsa]”.
+The following options must be in the section "[taler\-exchange\-secmod\-eddsa]".
 .INDENT 0.0
 .TP
 .B LOOKAHEAD_SIGN
@@ -265,7 +268,7 @@ On which path should the security module listen for signing requests?
 .UNINDENT
 .SS EXCHANGE DATABASE OPTIONS
 .sp
-The following options must be in the section “[exchangedb]”.
+The following options must be in the section "[exchangedb]".
 .INDENT 0.0
 .TP
 .B IDLE_RESERVE_EXPIRATION_TIME
@@ -318,7 +321,7 @@ URL of the wire gateway.  Typically of the form
 \fBhttps://$HOSTNAME[:$PORT]/taler\-wire\-gateway/$USERNAME/\fP
 where $HOSTNAME is the hostname of the system running the bank
 (such as the Taler Python bank or the Nexus) and \fB$USERNAME\fP is
-the username of the exchange’s bank account (usually matching
+the username of the exchange\(aqs bank account (usually matching
 the \fBUSERNAME\fP option used for authentication).  Example:
 \fBhttps://bank.demo.taler.net/taler\-wire\-gateway/Exchange/\fP\&.
 .TP
@@ -420,7 +423,7 @@ Base URL of the exchange, e.g.\ “\fI\%https://exchange.demo.taler.net/\fP”
 .TP
 .B MASTER_KEY
 Crockford Base32 encoded master public key, public version of the
-exchange’s long\-time offline signing key.  Can be omitted, in that
+exchange\(aqs long\-time offline signing key.  Can be omitted, in that
 case the exchange will NOT be trusted unless it is audited by
 a known auditor.
 Omitting \fBMASTER_KEY\fP can be useful if we do not trust the exchange
@@ -479,8 +482,8 @@ The following options must be in section “[auditordb\-postgres]” if the
 .INDENT 0.0
 .TP
 .B CONFIG
-How to access the database, e.g.\ “postgres:///taler” to use the
-“taler” database. Testcases use “talercheck”.
+How to access the database, e.g.\ "postgres:///taler" to use the
+"taler" database. Testcases use “talercheck”.
 .UNINDENT
 .SH SEE ALSO
 .sp