<div dir="ltr">I'm leaning towards a full row for [DEFAULT] and other sections, like Andreas describes. Then the filename itself is clear because it's grouped in a table. <div><br></div><div>One design oddity that sticks out is, why are there groupings if they're not also logically in a single table anyway? Are devs picking poor groupings or are there too many items in DEFAULT? I ask because I would think the groupings would help with the mappings.</div>

<div><br></div><div>Thanks for asking Shaun!</div><div>Anne<br><div><br></div><div><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Jan 18, 2014 at 2:13 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On 01/17/2014 09:58 PM, Shaun McCance wrote:<br>
> I've been doing a lot of work on the autohelp.py script that generates<br>
> our reference tables of configuration options. One of the problems it<br>
> had was that it couldn't distinguish between options with the same name<br>
> in different groups. For example, these are both options in nova:<br>
><br>
> [spice]<br>
> enabled = False<br>
><br>
> [osapi_v3]<br>
> enabled = False<br>
><br>
> The old code would duplicate these, putting the reference for both of<br>
> them in both nova-spice.xml and nova-apiv3.xml. I've fixed that.<br>
><br>
> But the DocBook still doesn't specify the group, which is a pretty<br>
> important piece of information to have. I'm trying to think of a good<br>
> way to add it, and I'd like feedback. Currently we have:<br>
><br>
> <td>option = default</td><td>help string</td><br>
><br>
> We could do<br>
><br>
> <td><programlisting>[group]<br>
> option = default</td><td>help string</td><br>
><br>
> That's a pretty good indication of how you'd actually write the config<br>
> file, but it makes the tables longer. We could do<br>
><br>
> <td>[group]</td><td>option = default</td><td>help string</td><br>
><br>
> That makes the tables wider, and/or gives less space to the help string.<br>
> Or we could write out separate tables for anything that's in a group<br>
> other than DEFAULT, and put the group name in the caption.<br>
><br>
> Thoughts?<br>
<br>
</div></div>I would do it similar to how the conf files look like, for example for<br>
this snippet<br>
[DEFAULT]<br>
option1 = text<br>
[database]<br>
connection= text<br>
<br>
This would be:<br>
<th><br>
<tr><br>
<div class="im"><td>option = default</td><td>help string</td><br>
</div></tr><br>
</th><br>
<tbody><br>
<tr><br>
<th colspan="2"><code>[DEFAULT]</code></th></tr><br>
<tr><br>
<td>option1 = text</td><td>Explanation</td><br>
</tr><br>
<th colspan="2"><code>[database]</code></th></tr><br>
<tr>connection = text...<br>
<br>
So, use a separate header line for each new section,<br>
<br>
Andreas<br>
<span class="HOEnZb"><font color="#888888">--<br>
 Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)<br>
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</div></div></blockquote></div><br></div></div></div>