update man page for taler.conf based on DD51

1 files changed, 68 insertions, 1 deletions

diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 5815645f..2959ef74 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -32,7 +32,9 @@ GLOBAL OPTIONS
 --------------
 
 The following options are from the “[taler]” section and used by
-virtually all Taler components.
+virtually all Taler components. Note: work is ongoing to obsolete
+these options, but for now they are in use.
+
 
 CURRENCY
   Name of the currency, e.g. “EUR” for Euro.
@@ -67,6 +69,71 @@ TALER_RUNTIME_DIR
   Where should Taler store system runtime data (like UNIX domain
   sockets). Usually “${TMP}/taler-system-runtime”.
 
+
+CURRENCY SPECIFICATIONS
+-----------------------
+
+Sections with a name of the form “[currency-$NAME]” (where "$NAME" could
+be any unique string) are used to specify details about how currencies
+should be handled (and in particularly rendered) by the user interface.
+A detailed motivation for this section can be found in DD51.
+Different components can have different rules for the same currency. For
+example, a bank or merchant may decide to render Euros or Dollars with
+always exactly two fractional decimals, while an Exchange for the same
+currency may support additional decimals.  The required options in each
+currency specification section are:
+
+ENABLED
+  Set to YES or NO. If set to NO, the currency specification
+  section is ignored. Can be used to disable currencies or
+  select alternative sections for the same CODE with different
+  choices.
+
+CODE
+  Code name for the currency. Can be at most 11 characters,
+  only the letters A-Z are allowed. Primary way to identify
+  the currency in the protocol.
+
+NAME
+  Long human-readable name for the currency. No restrictions,
+  but should match the official name in English.
+
+DECIMAL_SEPARATOR
+  What symbol should be used to separate fractional digits.
+  Typical values are "." or ",".
+
+NUM_FRACTIONAL_INPUT_DIGITS
+  Number of fractional digits that users are allowed to enter
+  manually in the user interface.
+
+NUM_FRACTIONAL_NORMAL_DIGITS
+  Number of fractional digits that will be rendered normally
+  (in terms of size and placement).  Digits shown beyond this
+  number will typically be rendered smaller and raised (if
+  possible).
+
+NUM_FRACTIONAL_TRAILING_ZERO_DIGITS
+  Number of fractional digits to pad rendered amounts with
+  even if these digits are all zero. For example, use 2 to
+  render 1 USD as $1.00.
+
+IS_CURRENCY_NAME_LEADING
+  When rendering amounts, should the currency name or symbol
+  be before the amount ("$10") or after ("3,50 €"). Use "YES"
+  to render the symbol before, "NO" to render it afterwards.
+
+ALT_UNIT_NAMES
+  JSON map determining how to encode very large or very tiny
+  amounts in this currency. Maps a base10 logarithm to the
+  respective currency symbol. Must include at least an
+  entry for 0 (currency unit).  For example, use
+  {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could
+  additionally use {"0":"€","3":"k€"} to render 3000 EUR
+  as 3k€. For BTC a typical map would be
+  {"0":"BTC","-3":"mBTC"}, informing the UI to render small
+  amounts in milli-Bitcoin (mBTC).
+
+
 EXCHANGE OPTIONS
 ----------------