1 files changed, 118 insertions, 16 deletions
diff --git a/man/taler-exchange-offline.1 b/man/taler-exchange-offline.1
index 08bd3e2b..39933434 100644
--- a/man/taler-exchange-offline.1
+++ b/man/taler-exchange-offline.1
@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "TALER-EXCHANGE-OFFLINE" "1" "Apr 16, 2023" "0.9" "GNU Taler"
-.SH NAME
-taler-exchange-offline \- operations using the offline key of a Taler exchange
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "TALER-EXCHANGE-OFFLINE" "1" "May 18, 2023" "0.9" "GNU Taler"
+.SH NAME
+taler-exchange-offline \- operations using the offline key of a Taler exchange
 .SH SYNOPSIS
 .sp
 \fBtaler\-exchange\-offline\fP
@@ -247,11 +247,10 @@ It outputs the signature affirming the removal of the auditor,
 in a format suitable for the \fBupload\fP subcommand.
 .SS enable\-account
 .sp
-This subcommand
-informs an exchange that it should advertise a bank account as belonging to
-the exchange on its \fB/wire\fP endpoint.  Note that this does \fInot\fP ensure that
-the exchange will use this bank account for incoming or outgoing wire
-transfers! For this, the \fBtaler\-exchange\-transfer\fP and
+This subcommand informs an exchange that it should advertise a bank account as
+belonging to the exchange on its \fB/wire\fP endpoint.  Note that this does
+\fInot\fP ensure that the exchange will use this bank account for incoming or
+outgoing wire transfers! For this, the \fBtaler\-exchange\-transfer\fP and
 \fBtaler\-exchange\-wirewatch\fP tools must be configured.  Furthermore, the bank
 account information advertised could theoretically differ from that which
 these tool actually use, for example if the public bank account is only a
@@ -260,6 +259,54 @@ front for the actual internal business accounts.
 The \fBpayto://\fP URI (RFC 8905) of the exchange\(aqs bank account must be given
 as the first argument to the subcommand.
 .sp
+Afterwards, optional arguments can be given:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBconversion\-url\fP $URL: specifies that using this bank account is subject
+to currency conversion. $URL must be the address of a currency conversion
+REST API that allows merchants and wallets to determine the current
+conversion rate.
+.IP \(bu 2
+\fBcredit\-restriction\fP $TYPE [$ARGS]: Specifies that there are
+restrictions in place when crediting this bank account. Details depend on
+the restriction $TYPE. This argument may be given multiple times, in which
+case debitor accounts must satisfy all restrictions. Restriction types are
+discussed below.
+.IP \(bu 2
+\fBdebit\-restriction\fP $TYPE [$ARGS]: Specifies that there are restrictions
+in place when receiving money from the exchange. Wallets and merchants
+must check that their target bank account satisfies these restrictions
+before sending deposit requests to the exchange. Details depend on the
+restriction $TYPE. This argument may be given multiple times, in which
+case debitor accounts must satisfy all restrictions. Restriction types are
+discussed below.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+The following types of credit\- and debit\-restrictions are supported:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBdeny\fP: A $TYPE of \fBdeny\fP means that this bank account cannot be used
+for the given operation.  \fBdeny\fP takes no further arguments.
+.IP \(bu 2
+\fBregex\fP $EXPR $HINT $JSON: A $TYPE of \fBregex\fP means that the partner\(aqs
+bank account \fBpayto\fP\-URI representation must follow a certain regular
+expression given in $EXPR where the syntax follows posix\-egrep, but
+without support for character classes, GNU extensions, back\-references or
+intervals. See
+\fI\%Findutils Manual\fP
+for a description of the posix\-egrep syntax. The $HINT must be a
+human\-readable description of the $EXPR.  $JSON should be a JSON array
+mapping IETF BCP 47 language tags to localized versions of $HINT.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
 The subcommand takes no inputs from \fBstdin\fP or other subcommands.
 .sp
 It outputs the signature affirming the addition of the wire account,
@@ -474,13 +521,18 @@ $ taler\-exchange\-offline upload < sigs.json
 .UNINDENT
 .SS Download, sign and upload, all in one (online)
 .sp
-Note that doing this is only recommended in non\-production deployments.
+Note that doing this is only recommended in non\-production deployments,
+as this requires putting the "offline" key onto a system that is actually
+online!
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ taler\-exchange\-offline download sign upload
+$ taler\-exchange\-offline \e
+    download \e
+    sign \e
+    upload
 .ft P
 .fi
 .UNINDENT
@@ -493,18 +545,50 @@ so that \fBsign\fP can see it as input, as in the variant without \fBshow\fP\&.
 .sp
 .nf
 .ft C
-$ taler\-exchange\-offline download show \- sign upload
+$ taler\-exchange\-offline \e
+    download \e
+    show \- \e
+    sign \e
+    upload
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .SS Create signature to enable bank account (offline)
+.sp
+The following command sets up an unrestricted simple exchange bank account
+without conversion:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ taler\-exchange\-offline enable\-account payto://iban/DE24242 > account.json
+$ taler\-exchange\-offline \e
+    enable\-account payto://iban/DE24242?receiver\-name=operator > account.json
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The following command would set up an exchange bank account with conversion
+and restrict it to only receive money from Switzerland and deny its use for
+debit operations:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ taler\-exchange\-offline \e
+  enable\-account payto://x\-taler\-bank/example.com/?receiver\-name=name \e
+  conversion\-url http://conversion.exchange.com/ \e
+  debit\-restriction \e
+    deny \e
+  credit\-restriction \e
+    regex \e
+      \(aqpayto://iban/.*/CH.*?receiver\-name=.*\(aq \e
+      \(aqSwiss only\(aq \e
+      \(aq{ "de" : "nur Schweiz", \e
+         "fr" : "Suisse uniquement" }\(aq
 .ft P
 .fi
 .UNINDENT
@@ -521,16 +605,25 @@ $ taler\-exchange\-offline upload < account.json
 .UNINDENT
 .UNINDENT
 .SS Combine signing keys and enabling bank account (offline)
+.sp
+You can chain multiple commands into one invocation:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ taler\-exchange\-offline sign enable\-account payto://iban/DE24242 < keys.json > combo.json
+$ taler\-exchange\-offline \e
+    sign \e
+    enable\-account \e
+      payto://iban/DE24242 < keys.json > combo.json
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+Note that \fBsign\fP must be first as it consumes the \fBkeys.json\fP
+input.  The resulting output combines the outputs of the \fBsign\fP
+and \fBenable\-account\fP subcommands.
 .SS Upload various signatures (online)
 .INDENT 0.0
 .INDENT 3.5
@@ -543,14 +636,23 @@ $ taler\-exchange\-offline upload < combo.json
 .UNINDENT
 .UNINDENT
 .SS Create multiple revocation messages in one pass (offline)
+.sp
+You can freely combine almost all commands, including those for
+key revocation:
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ taler\-exchange\-offline revoke\-denomination $DKH1 revoke\-denomination $DKH2 > revoke.json
-$ taler\-exchange\-offline revoke\-signkey $SK1 revoke\-signkey $SK2 > revoke.json
-$ taler\-exchange\-offline revoke\-signkey $SK revoke\-denomkey $DKH > mix.json
+$ taler\-exchange\-offline \e
+    revoke\-denomination $DKH1 \e
+    revoke\-denomination $DKH2 > revoke.json
+$ taler\-exchange\-offline \e
+    revoke\-signkey $SK1 \e
+    revoke\-signkey $SK2 > revoke.json
+$ taler\-exchange\-offline \e
+    revoke\-signkey $SK \e
+    revoke\-denomkey $DKH > mix.json
 .ft P
 .fi
 .UNINDENT