Yannick Poireault created SLING-6302:
----------------------------------------
Summary: Enhance Sling configuration files documentation
Key: SLING-6302
URL: https://issues.apache.org/jira/browse/SLING-6302
Project: Sling
Issue Type: Improvement
Components: Documentation
Reporter: Yannick Poireault
There are some lacking information in the following documentation:
"Configuration Installer Factory" -
https://sling.apache.org/documentation/bundles/configuration-installer-factory.html
1. Two different configuration files format are presented, but nothing explain
the differences and advantages/inconvenient of each format, thus making the
choice between one or the other impossible or random.
We could for example specify that the .cfg is the legacy format, and the
.config format has been introduced later by the Felix framework and offer more
flexibility / features.
Then adding the few advantages of config files over cfg files, like the support
for typed values.
And what is clearly the most important for me would be the point 2 below.
2. State that .cfg files doesn't support multiple values ! Or does it ? If it
is the case then the syntax is really not clear.
On this subject, unlike for the .config file, the grammar definition for .cfg
below is beyond understanding:
header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
-> It sounds like a property definition can be recursive ?
-> The <value> which is the content is not described.
-> We should assume that <nl> means "new line", but what about the quoting ?
Regarding the last thing, the multiples values definition is corresponding to
the java.util.Properties (and not java.util.Property as written in the doc)
which ends up with a single property containing all the values concatenated and
not as an Array of values as expected.
3. Related to the point above, mention that only .config files can supports the
multiples values properties used by the OSGi bundles / configuration.
An interesting information would be the difference by using the [] notation and
the () one. I know that using square bracket gives an Array of values, and
using round bracket gives a collection of values.
I think that only the first one is used/supported in OSGi, but I may be
mistaken, and that should be explained.
4. Please add some simple example for the key features. Using grammar
specification is fine, but examples are often more useful and easier to
understand.
For example for multiple values in .config files:
primary.allowed-client-ip-ranges=["10.20.30.0","10.20.85.0"]
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
