[taler-docs] branch master updated: add man pages for dbconfig commands

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 12a4738f add man pages for dbconfig commands
12a4738f is described below

commit 12a4738f43286fd8da83c00b054e68529339d4df
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Aug 11 20:58:33 2023 +0200

    add man pages for dbconfig commands
---
 conf.py                                            | 28 ++++++++
 core/api-exchange.rst                              |  3 +-
 .../041-wallet-balance-amount-definitions.rst      | 79 ++++++++++++----------
 manpages/sync-dbconfig.1.rst                       | 61 +++++++++++++++++
 manpages/taler-auditor-dbconfig.1.rst              | 61 +++++++++++++++++
 manpages/taler-exchange-dbconfig.1.rst             | 61 +++++++++++++++++
 manpages/taler-merchant-dbconfig.1.rst             | 61 +++++++++++++++++
 7 files changed, 316 insertions(+), 38 deletions(-)

diff --git a/conf.py b/conf.py
index 8d8e49d8..efdf5476 100644
--- a/conf.py
+++ b/conf.py
@@ -495,6 +495,34 @@ man_pages = [
         "GNU Taler contributors",
         1,
     ),
+    (
+        "manpages/taler-auditor-dbconfig.1",
+        "taler-auditor-dbconfig",
+        "configure Taler auditor database",
+        "GNU Taler contributors",
+        1,
+    ),
+    (
+        "manpages/taler-exchange-dbconfig.1",
+        "taler-exchange-dbconfig",
+        "configure Taler exchange database",
+        "GNU Taler contributors",
+        1,
+    ),
+    (
+        "manpages/taler-merchant-dbconfig.1",
+        "taler-merchant-dbconfig",
+        "configure Taler merchant database",
+        "GNU Taler contributors",
+        1,
+    ),
+    (
+        "manpages/sync-dbconfig.1",
+        "sync-dbconfig",
+        "configure sync database",
+        "GNU Taler contributors",
+        1,
+    ),
     (
         "manpages/taler-exchange-dbinit.1",
         "taler-exchange-dbinit",
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index a21a3c14..35fdcc49 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -135,7 +135,7 @@ possibly by using HTTPS.
 
       // Linear cost factor for the STEFAN curve used
       // to (over) approximate fees payable by amount.
-.
+      //
       // Note that the total to be paid is first to be
       // divided by the smallest denomination to obtain
       // the value to be multiplied with.
@@ -231,6 +231,7 @@ possibly by using HTTPS.
       // explicitly as the client might otherwise be confused by clock skew as 
to
       // which signing key was used.
       eddsa_pub: EddsaPublicKey;
+
     }
 
   .. ts:def:: GlobalFees
diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index eb6c3d90..4d90eaad 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -50,15 +50,15 @@ MANUAL_WITHDRAW
   account may charge some fee that can be taken into account
 
   ``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
-  
+
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
-    
+
     ``effective_amount`` = instructed_amount - coins.withdrawal_fee
 
   if instructed_amount mode = effective
     ``raw_amount`` = instructed_amount + coins.withdrawal_fee
-    
+
     ``effective_amount`` = instructed_amount
 
 DEPOSIT
@@ -71,7 +71,7 @@ DEPOSIT
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
 
-    ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee 
+    ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee
 
   if instructed_amount mode = effective
     ``raw_amount`` = instructed_amount - coins.deposit_fee - coins.refresh_fee 
- wire.transfer_fee
@@ -95,25 +95,25 @@ PULL CREDIT (creating an invoice)
     ``raw_amount`` = instructed_amount + coins.withdrawal_fee + purse_fee
 
     ``effective_amount`` = instructed_amount
-  
+
   if instructed_amount mode = counter-party
-    ``raw_amount`` = instructed_amount - coins.counter-party_deposit_fee  
+    ``raw_amount`` = instructed_amount - coins.counter-party_deposit_fee
 
     ``effective_amount`` = instructed_amount - coins.counter-party_deposit_fee 
- coins.withdrawal_fee - purse_fee
 
-  ``counter-party_raw_amount`` = raw_amount 
-  
-  ``counter-party_effective_amount`` = raw_amount + 
coins.counter-party_deposit_fee 
+  ``counter-party_raw_amount`` = raw_amount
+
+  ``counter-party_effective_amount`` = raw_amount + 
coins.counter-party_deposit_fee
 
   .. note::
 
-    counter-party_effective_amount is an estimation since refresh fee is not 
included. 
-    Refresh fee can't be calculated because depends on the coins available in 
the wallet 
+    counter-party_effective_amount is an estimation since refresh fee is not 
included.
+    Refresh fee can't be calculated because depends on the coins available in 
the wallet
     of the counter-party
 
   .. note::
     coins.counter-party_deposit_fee is the minimum deposit_fee that can be 
calculated for the
-    given exchange. Counter-party may pay more if it have different 
preferences doing the coin 
+    given exchange. Counter-party may pay more if it have different 
preferences doing the coin
     selection.
 
 
@@ -134,19 +134,19 @@ PUSH DEBIT (creating a transfer)
     ``raw_amount`` = instructed_amount - coins.deposit_fee - purse_fee
 
     ``effective_amount`` = instructed_amount
- 
+
   if instructed_amount mode = counter-party
-    ``raw_amount`` = instructed_amount + coins.counter-party_withdraw_fee  
+    ``raw_amount`` = instructed_amount + coins.counter-party_withdraw_fee
 
     ``effective_amount`` = instructed_amount - 
coins.counter-party_withdraw_fee - coins.withdrawal_fee - purse_fee
- 
-  ``counter-party_raw_amount`` = raw_amount 
+
+  ``counter-party_raw_amount`` = raw_amount
 
   ``counter-party_effective_amount`` = raw_amount - 
coins.counter-party_withdraw_fee
 
   .. note::
     coins.counter-party_withdraw_fee is the minimum withdraw_fee that can be 
calculated for the
-    given exchange. Counter-party may pay more if it have different 
preferences doing the coin 
+    given exchange. Counter-party may pay more if it have different 
preferences doing the coin
     selection.
 
 
@@ -155,7 +155,7 @@ Transaction types completed by the wallet
 
 Next transaction types are not initiated in the wallet so instructed amount is 
not defined by the wallet user.
 
-We need to calculate effective_amount to check if the wallet is able to 
perform the operation or the user accept 
+We need to calculate effective_amount to check if the wallet is able to 
perform the operation or the user accept
 the fees.
 
 BANK_WITHDRAW
@@ -164,15 +164,15 @@ BANK_WITHDRAW
   account may charge some fee that can be taken into account
 
   ``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
-  
+
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
-    
+
     ``effective_amount`` = instructed_amount - coins.withdrawal_fee
 
   if instructed_amount mode = effective
     ``raw_amount`` = instructed_amount + coins.withdrawal_fee
-    
+
     ``effective_amount`` = instructed_amount
 
 
@@ -180,7 +180,7 @@ BANK_WITHDRAW
   how much wire_fee the merchant is willing to pay
 
   ``merchant_wire_fee`` = min(wire.transfer_fee / 
contractTerms.amortization_factor, contractTerms.max_wire_fee)
-  
+
   ``merchant_deposit_fee`` = min(contractTerms.max_fee, contract_wire_fee)
 
 
@@ -216,10 +216,10 @@ PUSH CREDIT (getting the transfer)
   .. note::
     In the case that the withdrawal_fee of the coin selection for the 
push-credit amount
     is higher than the wire_fee of the exchange, can the wallet ask the 
exchange to make
-    a wire transfer of the purse instead of proceeding? 
+    a wire transfer of the purse instead of proceeding?
 
 PULL DEBIT (paying an invoice)
-  raw amount is the net value of the invoice without fees 
+  raw amount is the net value of the invoice without fees
 
   ``instructed_amount`` = p2pContract.amount
 
@@ -234,7 +234,7 @@ REFUND
 
   ``instructed_amount`` = refund.amount
 
-  ``raw_amount`` = instructed_amount 
+  ``raw_amount`` = instructed_amount
 
   ``effective_amount`` = instructed_amount - refund_fee - refresh_fee
 
@@ -242,7 +242,7 @@ REFUND
     There may be the case that the merchant should refund all the value of the 
purchase
     and that may include paying for the refund_fee.
 
-    Is there a way that the merchant can initiate a refund of purchase + 
refund_fee so 
+    Is there a way that the merchant can initiate a refund of purchase + 
refund_fee so
     the wallet will get the same effective_amount?
 
 TIP
@@ -252,11 +252,11 @@ TIP
 
   ``raw_amount`` = instructed_amount + withdrawal_fee
 
-  ``effective_amount`` = instructed_amount 
+  ``effective_amount`` = instructed_amount
 
-  .. note:: 
+  .. note::
     We should not show fee for tips in the wallet since the merchant is the 
one choosing
-    the exchange and we can assume that those tips are paid by the merchant. 
+    the exchange and we can assume that those tips are paid by the merchant.
     So the wallet only care about the effective.
 
 Coin selection algorithm
@@ -266,17 +266,22 @@ Is an internal optimization algorithm that will choose 
coins given a denominatio
 until amount is reached. The coins selected to minimize the fee spent.
 
 ``select-coin-for-operation`` will receive 3 parameters:
+
   * operation: define if the coins are selected from wallet database or from 
denomination list. Possible values are:
-   - credit: reduce withdrawal fee, use exchange denomination list
-   - debit: reduce deposit fee, use database denomination and current coin 
count
+
+    - credit: reduce withdrawal fee, use exchange denomination list
+    - debit: reduce deposit fee, use database denomination and current coin 
count
+
   * amount: how much value the coins need to sum up
   * mode: the interpretation of the amount parameter
+
     - net: the amount does not include the operation fee
     - gross: the amount include the operation fee
 
 If the operation is debit and with the current coins there is no way to reach 
the amount then
- 1. an optimized withdrawal operation can be suggested (list of denominations)
- 2. an optimized refresh operation can be suggested (amount gap, coin to be 
refreshed and list of denominations to withdraw)
+
+  1. an optimized withdrawal operation can be suggested (list of denominations)
+  2. an optimized refresh operation can be suggested (amount gap, coin to be 
refreshed and list of denominations to withdraw)
 
 .. note::
 
@@ -287,8 +292,8 @@ If the operation is debit and with the current coins there 
is no way to reach th
 
     withdrawal_fee = amount1 - amount2
 
-  then the wallet should select the same coins using the correct mode 
-  
+  then the wallet should select the same coins using the correct mode
+
     select-coin(withdraw, raw, amount1) == select-coin(withdraw, effective, 
amount2)
 
 
@@ -312,7 +317,7 @@ For deposits (where there is no contract that already 
specifies an amount):
 * ``raw-mode`` (default): The instructed amount is what will be paid to the 
"merchant" (or the customer's bank account), ignoring wire fees
 * ``effective-mode``: The instructed amount is how the wallet's balance will 
be affected. Difficult to compute accurately because refresh is involved. Note 
that the calculation should ideally again be made available when the user is 
asked to specify an amount when using a template.
 
-  
+
 For peer-push-debit:
 
 * ``raw-mode`` (default): The instructed amount is what will be paid, deposit 
fees are covered by the sender, withdrawal fees from the reserve by the receiver
@@ -402,7 +407,7 @@ Balance Mismatch
 ----------------
 
 The wallet uses the following terminology when an operation can't succeed
-because the balance is too low, even though the instructed amount 
+because the balance is too low, even though the instructed amount
 
 - "fee-gap-estimate": Additional (material) balance that the wallet estimates 
it
   still needs for the operation to succeed.
diff --git a/manpages/sync-dbconfig.1.rst b/manpages/sync-dbconfig.1.rst
new file mode 100644
index 00000000..c1820f70
--- /dev/null
+++ b/manpages/sync-dbconfig.1.rst
@@ -0,0 +1,61 @@
+sync-dbconfig(1)
+################
+
+.. only:: html
+
+   Name
+   ====
+
+   **sync-dbconfig** - configure sync database
+
+
+Synopsis
+========
+
+**sync-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**sync-dbconfig** is a simple shell script that configures
+a Postgresql database for use by ``sync-httpd``.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+   Write the database configuration to FILENAME. The tool
+   will append the required ``CONFIG`` option for the
+   Postgresql access to the respective file.
+
+**-h**
+   Print short help on options.
+
+**-n** *DBNAME*
+   Use DBNAME for the name of the created database.
+
+**-r**
+   Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+   Skip database initialization. Useful if you want to run
+   ``sync-dbinit`` manually.
+
+**-u** *USER*
+   Specifies the (main) sync user that will access the database.
+
+See Also
+========
+
+sync-dbinit(1), sync.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-auditor-dbconfig.1.rst 
b/manpages/taler-auditor-dbconfig.1.rst
new file mode 100644
index 00000000..7e83b87a
--- /dev/null
+++ b/manpages/taler-auditor-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-auditor-dbconfig(1)
+#########################
+
+.. only:: html
+
+   Name
+   ====
+
+   **taler-auditor-dbconfig** - configure Taler auditor database
+
+
+Synopsis
+========
+
+**taler-auditor-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-auditor-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler auditor.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+   Write the database configuration to FILENAME. The tool
+   will append the required ``CONFIG`` option for the
+   Postgresql access to the respective file.
+
+**-h**
+   Print short help on options.
+
+**-n** *DBNAME*
+   Use DBNAME for the name of the created database.
+
+**-r**
+   Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+   Skip database initialization. Useful if you want to run
+   ``taler-auditor-dbinit`` manually.
+
+**-u** *USER*
+   Specifies the (main) auditor user that will access the database.
+
+See Also
+========
+
+taler-auditor-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-exchange-dbconfig.1.rst 
b/manpages/taler-exchange-dbconfig.1.rst
new file mode 100644
index 00000000..0363705c
--- /dev/null
+++ b/manpages/taler-exchange-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-exchange-dbconfig(1)
+##########################
+
+.. only:: html
+
+   Name
+   ====
+
+   **taler-exchange-dbconfig** - configure Taler exchange database
+
+
+Synopsis
+========
+
+**taler-exchange-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-exchange-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler exchange.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+   Write the database configuration to FILENAME. The tool
+   will append the required ``CONFIG`` option for the
+   Postgresql access to the respective file.
+
+**-h**
+   Print short help on options.
+
+**-n** *DBNAME*
+   Use DBNAME for the name of the created database.
+
+**-r**
+   Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+   Skip database initialization. Useful if you want to run
+   ``taler-exchange-dbinit`` manually.
+
+**-u** *USER*
+   Specifies the (main) exchange user that will access the database.
+
+See Also
+========
+
+taler-exchange-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant-dbconfig.1.rst 
b/manpages/taler-merchant-dbconfig.1.rst
new file mode 100644
index 00000000..d84bd5cd
--- /dev/null
+++ b/manpages/taler-merchant-dbconfig.1.rst
@@ -0,0 +1,61 @@
+taler-merchant-dbconfig(1)
+##########################
+
+.. only:: html
+
+   Name
+   ====
+
+   **taler-merchant-dbconfig** - configure Taler merchant database
+
+
+Synopsis
+========
+
+**taler-merchant-dbconfig**
+[**-c** *FILENAME* *]
+[**-h**]
+[**-n** *NAME* *]
+[**-r**]
+[**-s**]
+[**-u** *USER* *]
+
+Description
+===========
+
+**taler-merchant-dbconfig** is a simple shell script that configures
+a Postgresql database for use by the GNU Taler merchant.
+
+Its options are as follows:
+
+**-c** *FILENAME*
+   Write the database configuration to FILENAME. The tool
+   will append the required ``CONFIG`` option for the
+   Postgresql access to the respective file.
+
+**-h**
+   Print short help on options.
+
+**-n** *DBNAME*
+   Use DBNAME for the name of the created database.
+
+**-r**
+   Reset any existing database. Looses all existing data. DANGEROUS.
+
+**-s**
+   Skip database initialization. Useful if you want to run
+   ``taler-merchant-dbinit`` manually.
+
+**-u** *USER*
+   Specifies the (main) merchant user that will access the database.
+
+See Also
+========
+
+taler-merchant-dbinit(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.