Open Stack

Hi!

This change is raising a big question: how do we handle duplication of 
tables. Tables now have an xml:id attribute, and multiple inclusions of 
tables make the build fail [0]. Here are a few solutions:

1) find a way to include tables multiple times in the config-ref book 
(docbook magic).
2) include tables in pages where they are actually needed, and add a 
"misc options" page which includes all remaining tables.
3) create a page including all the tables, and xlink from other pages.

Personally I'm OK with duplicating tables but it might be hard to get 
this working in docbook, and even harder to convince everyone that it's 
a good idea (based on IRC discussions) ;)

I like solution 3 because it provides a single page with all the config 
options, in which it's easy to search for what you need. The downside 
(IMO) is that hyperlinks makes you jump back and forth between pages.

So what do you think is the best option, or is there an other one we 
didn't think of?


Thanks,
Gauvain


[0] https://review.openstack.org/#/c/79965/



Le 2014-03-11 08:16, Gauvain Pocentek a écrit :
> Hello,
> Just some news about the config ref tools, what's been done and what
> needs to be done.
> I've spent some time trying to improve the autohelp.py script
> recently, and with the help of Andreas, Shaun and Doug (and of course
> thanks to the work of the previous developers), we have now something
> that works quite well.
> In case you've never heard of it, this script extracts configuration
> options from a project and generates docbook tables. There's one
> manual step, config options must be categorized to generate multiple
> tables instead of one huge table. This is done in "flagmappings" files
> [0].
> The main projects tables are generated, but some are not used yet in
> the config ref (ceilometer, heat and trove). A starting point for
> these missing refs would be to have a big page referencing all the
> tables (as is done for glance). I'll try to find some time to work on
> this in the next days, but if anyone wants to step in I'll be happy to
> help in any way I can. There's probably some work to do on the
> categorization of the options too...
> [0]
> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/tools/autogenerate-config-flagmappings
> Cheers,
> Gauvain
> Objectif Libre - Infrastructure et Formations Linux
> http://www.objectif-libre.com
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs