Open Stack

Hi,


Le 2014-03-14 15:06, Steve Gordon a écrit :
> ----- 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.

Discussing this at the summit would be nice, and then take proper 
action in the juno cycle. I guess we should register a session, I'll 
look into that, that's totally new to me.

In the meantime, I suggest that we introduce the xml:id in the tables 
(some are already published and used), xi:include the tables in the 
"here are all the options" page, and use xref from other pages 
referencing the tables.

Does this sound good enough for the icehouse release?

Thanks,
Gauvain