Open Stack

On Wed, Mar 12, 2014 at 2:36 PM, Steve Gordon <sgordon at redhat.com> wrote:

> ----- 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!).
>
>
I like mad men and this sounds like a good idea for the future. I agree
that the overviews have some value but the maintenance and consistence are
my main priorities in the flood of update work.

This is really great work --- thanks Gauvain for the communication, updates
and work. Thanks Shaun and Doug for collaborating in the common.


> 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)
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140313/0e2fe601/attachment.html>