View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0006134||Taler||documentation||public||2020-03-23 09:47||2021-08-24 16:23|
|Reporter||Florian Dold||Assigned To||ttn|
|Priority||normal||Severity||text||Reproducibility||have not tried|
|Target Version||0.8||Fixed in Version||0.8|
|Summary||0006134: configuration file format is insufficiently documented in GNUnet and Taler|
|Description||There is no place other than the source code that comprehensively defines the configuration file format.|
The GNUnet man page has some bits, but is very specific to GNUnet. It doesn't mention the include mechanism, and the format is underspecified. For example:
* "Boolean values are given as "YES" and "NO"."
=> the manpage doesn't mention anything about case (in)sensitivity
* "Empty lines and lines beginning with a "#" are treated as comments."
=> What about comment lines that begin with a whitespace? Are they allowed?
=> How is whitespace handled in *front* of option names and section names?
* "A section contains a number of options of the form "OPTION=VALUE""
=> What lexical syntax does "OPTION" have? Does it allow whitespace, like many ini parsers do?
The GNUnet handbook isn't any more helpful. The Taler documentation and man pages also don't contain sufficient information.
The variable substitution syntax isn't explained properly either.
How string quotes work and if there are any escape symbols isn't clear from the docs.
Neither is the include mechanism.
|Tags||No tags attached.|
||taler-config / gnunet-config and the configuration format itself are also documented in several places IIRC. Would be good to only write the generic text once and reference (or include) it, instead of repeating it in various places... ;-).|
How about a new manual "Configuration Tools" that describes the format and also the tools that read/write the format? This would describe:
- comment syntax
- section/key case-insensitivity / syntax
- quoting syntax
- value types (boolean, numeric, symbol, string) / syntax
- variable substitution
- include mechanism
- conventions in the examples
- CLI program (taler-config/gnunet-config) invocation
- configuration files
Alternatively, all the above can be placed in the respective tool manpages, w/ the common bits factored and included as necessary. Hmm...
I expect that we'll soon have a few exchange-specific configuration tools (like "generate fee structure" or "configure auditor"). But those are exchange-specific, and so it would be good if the manual title were clear on being only about taler-config (or gnunet-config). Also, you might want to run 'less' on taler-config, you may be slightly surprised.
We do have a man-page 'man 5 taler.config', in case you missed that one, and there is also a man-page 'man 1 gnunet-config' -- which (if it were perfect) would apply 1:1 to taler-config.
I was thinking of #including a chapter on "Configuration file syntax and editing" or something like that in each of the manuals that have a specific audience where this applies (merchant backend operator, exchange operator for now). A new manual felt a bit like overkill, we already have a very large number of those IMO. But, if you feel a new top-level manual is better, I won't object.
||Oh, last point: as GNUnet uses the same configuration (tooling, format), we might want a solution that _also_ can be re-used for docs.gnunet.org, except there it's 'gnunet.conf' instead of 'taler.conf' and gnunet-config instead of taler-config, and the defaults are in ~/share/gnunet/config.d/ instead of ~/share/taler/config.d/ -- but otherwise they are identical.|
||I see that taler-config is at its heart gnunet-config. :-D I'm off to study some source code...!|
Please see recent commit to docs.git:
Still to go:
- variable substitution (e.g. $HOME)
- escaping quotes and other characters
||That's it, IMO.|
I've added a new manpage -- taler-config(1):
Hopefully, between this manpage and the existing taler.conf(5), the format is documented enough to be able to close this bug (at least, for the GNU Taler side of things). What do people think?
||Looks good to me -- just section 2.3.1/2.3.2 should probably be also included in the merchant operator manual (chapter 3.4) and the auditor manual (chapter 10.3). And 2.3.1 could make it into the GNUnet handbook as well!|
I found https://git.gnunet.org/gnunet.git/tree/doc/handbook/chapters/configuration.texi
-- is that what you have in mind?
There, or here: https://git.gnunet.org/gnunet.git/tree/doc/handbook/chapters/installation.texi
Depends. Not sure what is best
I've made two commits to gnunet.org/gnunet.git:
Of these, i'm more concerned about the accuracy of the first one. PTAL critically.
Haha, it turns out the second one caused an error w/ buildbot:
I have added another commit to remedy this:
Hopefully buildbot will be happy now.
I realize now that the "Configuration Handbook" chapter was never included in the final output.
This commit changes that:
Sigh, another buildbot grumbling:
This time, i actually built locally (in the pre-installation gnunet-0.14.0 directory).
These commits result in no error and a correct build:
||Is there anything else to do for this bug?|
||I'm happy. Let's give Florian a few days to comment, if he has nothing, let's call it resolved.|
I really like the new configuration man page, it addresses all concerns I had and is very readable.
Minor nitpick: Maybe mention that unlike in "/bin/sh"-style double quotes, escape characters are *not* supported and the entire string within double quotes (including other double quotes!) is taken verbatim? GNUnet seems to support some form of escaping (see escape_name in src/util/configuration.c), but that is only used for lists of file names (to escape spaces) and AFAICT *not* used in Taler at all.
Thanks for the feedback. I've just now pushed:
|2020-03-23 09:47||Florian Dold||New Issue|
|2020-03-23 09:47||Florian Dold||Status||new => assigned|
|2020-03-23 09:47||Florian Dold||Assigned To||=> Christian Grothoff|
|2020-03-23 09:48||Florian Dold||Description Updated|
|2020-03-23 12:56||Christian Grothoff||Assigned To||Christian Grothoff => Stefan|
|2020-09-05 13:59||Christian Grothoff||Severity||minor => text|
|2020-11-20 20:01||Christian Grothoff||Assigned To||Stefan => ttn|
|2020-11-23 00:04||Christian Grothoff||Note Added: 0017150|
|2020-11-25 04:23||ttn||Note Added: 0017153|
|2020-11-25 11:18||Christian Grothoff||Note Added: 0017154|
|2020-11-25 11:20||Christian Grothoff||Note Added: 0017155|
|2020-11-25 23:47||ttn||Note Added: 0017156|
|2020-12-01 08:46||ttn||Note Added: 0017159|
|2020-12-01 08:48||ttn||Note Edited: 0017159|
|2020-12-01 08:50||ttn||Note Edited: 0017159|
|2020-12-09 05:24||ttn||Note Added: 0017178|
|2020-12-09 07:29||Christian Grothoff||Note Added: 0017180|
|2020-12-10 09:34||ttn||Note Added: 0017181|
|2020-12-10 10:11||Christian Grothoff||Note Added: 0017184|
|2020-12-11 21:38||ttn||Note Added: 0017190|
|2020-12-11 22:37||Christian Grothoff||Note Added: 0017191|
|2020-12-15 09:51||ttn||Note Added: 0017203|
|2020-12-15 10:17||ttn||Note Added: 0017204|
|2020-12-15 10:59||ttn||Note Added: 0017205|
|2020-12-15 11:14||ttn||Note Added: 0017206|
|2020-12-18 20:11||ttn||Note Added: 0017214|
|2020-12-18 20:30||Christian Grothoff||Note Added: 0017215|
|2020-12-21 13:00||Florian Dold||Note Added: 0017222|
|2020-12-23 05:25||ttn||Note Added: 0017227|
|2021-01-01 16:39||Christian Grothoff||Status||assigned => resolved|
|2021-01-01 16:39||Christian Grothoff||Resolution||open => fixed|
|2021-01-01 16:39||Christian Grothoff||Fixed in Version||=> 0.9|
|2021-07-30 13:57||Christian Grothoff||Fixed in Version||0.9 => 0.8.1|
|2021-07-30 13:59||Christian Grothoff||Target Version||=> 0.8.1|
|2021-07-30 14:01||Christian Grothoff||Fixed in Version||0.8.1 => 0.8|
|2021-07-30 14:01||Christian Grothoff||Target Version||0.8.1 => 0.8|
|2021-08-24 16:23||Christian Grothoff||Status||resolved => closed|