<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 6/11/14, 12:24 PM, Tomek Mrugalski
wrote:<br>
</div>
<blockquote cite="mid:539882C6.3030701@isc.org" type="cite">
<pre wrap="">I'm working on a ticket #3418 that updates Kea User's Guide (formerly
also known as BIND10 Guide or Administrator Reference for BIND10/Kea).
Major part of that work is to convert all bindctl examples to JSON
format. I did convert couple sections and would like to ask for your
feedback.
You can either get the code from trac3418 or use that generated file:
<a class="moz-txt-link-freetext" href="http://git.kea.isc.org/~tomek/kea/kea-guide.html">http://git.kea.isc.org/~tomek/kea/kea-guide.html</a>
In particular, please note sections 4. (general overview of the
configuration) and sections 5.2 (example config for Kea4) and 5.2.1
Default storage for leases. I'm particularly interested in your comments
on this one. It lists a number of parameters, but each of them is
presented in slightly different way. Let me know which of those formats
is easiest to read.
Couple random comments:
Section 5.2 includes an example that has line numbers. The obvious
advantage is that it's easier to reference them. The disadvantages are
that it's not possible to copy/paste the example and it's awkward to
maintain (e.g. when you need to add a line somewhere at the beginning).
</pre>
</blockquote>
The example file is actually rather cluttered. Between the line
numbers and the comments <br>
you can't see the file structure and syntax. Maybe try thinning it
out:<br>
<br>
<tt><br>
</tt><b><tt>{ </tt></b><b><tt><br>
</tt></b><b><tt># start Dhcp4 </tt></b><b><tt><br>
</tt></b><b><tt>"Dhcp4": {</tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt># First we set up global values</tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt> interfaces": [ "eth0" ],</tt></b><b><tt><br>
</tt></b><b><tt> "valid-lifetime": 4000,</tt></b><b><tt><br>
</tt></b><b><tt> "renew-timer": 1000,</tt></b><b><tt><br>
</tt></b><b><tt> "rebind-timer": 2000,</tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt># Next we, specify the type of lease database </tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt> "lease-database": {</tt></b><b><tt><br>
</tt></b><b><tt> "type": "memfile"</tt></b><b><tt><br>
</tt></b><b><tt> },</tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt># Finally, we List the subnets from which we will
be leasing.</tt></b><b><tt><br>
</tt></b><b><tt><br>
</tt></b><b><tt> "subnet4": [ </tt></b><b><tt><br>
</tt></b><b><tt> { </tt></b><b><tt><br>
</tt></b><b><tt> "subnet": "192.0.2.0/24"</tt></b><b><tt>,<br>
</tt></b><b><tt> "pool": [ "192.0.2.1 - 192.0.2.200" ]</tt></b><b><tt><br>
</tt></b><b><tt> } </tt></b><b><tt><br>
</tt></b><b><tt> ]</tt></b><b><tt><br>
</tt></b><b><tt>} </tt></b><b><tt><br>
</tt></b><b><tt>}</tt></b><tt><br>
</tt><tt><br>
</tt>Thinning out the comments should make it a lot easier to
discuss each 'section' without using line numbers.<br>
<br>
Also, notice that you can rearrange the order of the entries so
they make more sense naturally. You are showing them in the order
they would have as Elements which is lexical based on Element name
and also influenced by Element type. There is nothing stopping us
from putting them in logical order. It makes the file much easier
to discuss and follow.<br>
<br>
Just as your example farther on, if you simply swap the order of
pool and subnet, it reads much better:<br>
<br>
<tt><b> "subnet4": [</b></tt><tt><b><br>
</b></tt><tt><b> { "subnet": "192.0.2.0/24", </b></tt><tt><b><br>
</b></tt><tt><b> "pool": [ "192.0.2.1 - 192.0.2.200" ]</b></tt><tt><b><br>
</b></tt><tt><b> },</b></tt><tt><b><br>
</b></tt><tt><b> { "subnet": "192.0.3.0/24", </b></tt><tt><b><br>
</b></tt><tt><b> "pool": [ "192.0.3.100 - 192.0.3.200" ]</b></tt><tt><b><br>
</b></tt><tt><b> },</b></tt><tt><b><br>
</b></tt><tt><b> { "subnet": "192.0.4.0/24",</b></tt><tt><b><br>
</b></tt><tt><b> "pool": [ "192.0.4.1 - 192.0.4.254" ]</b></tt><tt><b><br>
</b></tt><tt><b> }]</b></tt><br>
<br>
and it will parse just fine.<br>
<br>
The existing example also shows rebind-timer and renew-timer
"commented out" which I assume implies they<br>
would have a default value which gives the behavior described in the
comments. First, this won't currently work because we don't
automatically fill in default values. If we did, I think using
that in the first example file shown<br>
is clutter. I think that is something that can be described in the
reference section.<br>
<br>
Until we resolve the defaults issue, our examples should probably
show what's required to work. I'm guessing the<br>
example shown would probably get rejected as lease-database does not
have all its values and the two timers<br>
already mentioned.<br>
<br>
<blockquote cite="mid:539882C6.3030701@isc.org" type="cite">
<pre wrap="">
Section 4.2.2 explains the notation that is used throughout the doc. It
was a directly applicable in bindctl, but I think it's convenient to
keep it after migration to JSON, even though it won't be directly usable
any more.</pre>
</blockquote>
<br>
I would suggest perhaps replacing the word "array" with the word
"list". <br>
When people are writing configuration files they tend to think
"list" not "array".<br>
I know if I were discussing the pools in a subnet, I would refer to
it as "the list of<br>
pools in the subnet".<br>
<br>
<blockquote cite="mid:539882C6.3030701@isc.org" type="cite">
<pre wrap="">
I'm adding many <!-- @todo --> comments in the XML file. We expect parts
of the guide to be rewritten once their respective tickets are done
(e.g. start/stop after #3422 script is implemented).
I've removed a lot of sections that were related to BIND10 framework.
The guide is now split into a number of XML files, rather than one large
XML. I think it will be easier to maintain, as finding something in 7k
lines file was increasingly awkward.
Thoughts? Comments?
Tomek
_______________________________________________
kea-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:kea-dev@lists.isc.org">kea-dev@lists.isc.org</a>
<a class="moz-txt-link-freetext" href="https://lists.isc.org/mailman/listinfo/kea-dev">https://lists.isc.org/mailman/listinfo/kea-dev</a>
</pre>
</blockquote>
<br>
</body>
</html>