Open Stack

----- Original Message -----
> 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).

There's no real magic possible here, each element in the DOM that has an ID must have a *unique* ID. Including the tables twice results in this not being the case.

> 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.

This is my preference for consistency and to benefit maintenance. At the moment it's kind of difficult for the chapters that don't do this to work out which tables are missing because the ones that are there are spread around in the hierarchy. I would add that really it's a subset of the chapters (particularly compute and block storage) that aren't doing this already.

> 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) ;)

The reason I asked for IDs on these tables in the first place was so I could add a reference from the Libvirt/KVM hypervisor section to the relevant table and avoid duplicating it. I did not realize that we were already duplicating tables :/.

> 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?

I think that the problem we are having is that the config files driving the automation are "flat", as in the option groups are all on the same level:

* api
* apiv3
* xen
* hyperv
* libvirt
* spice
* vnc

There are some obvious logical groupings you can make here like "api configuration", "hypervisor configuration", and "console configuration". That's effectively what's being reflected in the manually handled hierarchy in the guide today for the minority of configuration groups where somebody took the time to write an overview of that component. I'm wonder if the solution isn't something like the flag mappings file for the CLI where we manually map out the hierarchy we expect, obviously we'd need to maintain it as new groups are added.

The script would then generate both the tables (as it does today) and the top level files for the book itself that link the tables into the hierarchy, potentially with a xi:include to a predictable location for the overview for that group if one was written (we would place them into this location) and an xi:fallback to a known small/null snippet to catch cases where none exists (maybe even a call to action, know about this section? help us write an overview!).

Sounding like the rantings of a mad man I know, if I had to decide on what we have today I'd still say all reference tables together but I think the above might be something to think about if we want to solve the illness rather than the symptom :).

-Steve

> 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
> 
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

-- 
Steve Gordon, RHCE
Product Manager, Red Hat Enterprise Linux OpenStack Platform
Red Hat Canada (Toronto, Ontario)