[Openstack-docs] Config reference news
Andreas Jaeger
aj at suse.com
Wed Mar 12 19:38:55 UTC 2014
On 03/12/2014 07:55 PM, Gauvain Pocentek wrote:
> 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).
> 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.
If we want duplicated tables, we can remove the xml:id attributes again
from the tables.
> 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) ;)
>
> 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 suggest to go one step further back and look at the config files as well.
We do now include some complete conf files like:
Neutron, Keystone: Complete conf files:
http://docs.openstack.org/trunk/config-reference/content/section_keystone.conf.html
http://docs.openstack.org/trunk/config-reference/content/section_neutron.conf.html
For others we have all tables at one place:
http://docs.openstack.org/trunk/config-reference/content/list-of-compute-config-options.html
I think we should look at these together and design one solution.
We can have:
a) Include complete config files
a.1) Do not include tables at all
a.2) Include tables in the text where they fit in, leave others out.
a.3) Include all tables in one section, reference them from other text
a.4) Include tables in the text where they fit in, add one section
with *all* tables as reference
....
b) Do not include config files where we have tables for:
b.2) Include tables in the text where they fit in, add one misc section
b.3) Include all tables in one section, reference them from other text
b.4) Include tables in the text where they fit in, add one section
with *all* tables as reference
I'd like to avoid duplication as much as possible.
a.2 would be one option but my preference would be to take care that we
do not need the complete config files (those are in the packages and
easy to see) and instead go to b.2 or b.3. Neither of them strikes me as
ideal - too many cross-references (b.3) would be bad but a misc section
is also a bit odd.
/me can't think straight right now ;(
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
More information about the Openstack-docs
mailing list