Open Stack

----- Original Message -----
> Le 2014-03-12 20:36, Steve Gordon a écrit :
> > ----- 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 think I like this option, but I'm not sure I understand it fully...
> Do you think you could provide a basic example of what you'd expect to
> see (only xi:include's and tables)?

Yeah, understand - I'll try dummy something up over the weekend. As I kind of alluded to in my email I think this would be something to bring to the summit and then discuss there for the Juno cycle rather than something to do now.

-Steve