Open Stack

On Wed, 2014-03-12 at 15:36 -0400, Steve Gordon 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.

XInclude 1.1 has a way of handling this. But it's still just a working
draft, and I doubt our tools support it. (dcramer: ping)

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

I agree with this, because...

[snip]

> 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 agree with this. As you generate the tables right now, you have to
make sure new tables are included, and watch out for deleted tables.
When tables are added, it's sometimes hard to fit them into the ad-hoc
narrative. When tables are deleted, sometimes the file that included
them has to be deleted, and you have to follow the chain up of including
files. It's really a pain. I'd much rather auto-generate everything.

--
Shaun