openstack-doc-core team mailing list archive

[Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx>]

I've never done either, so I have no direct experience here. That being said, I like the small bucket approach because it seems like there are many cases where the differences across versions are small, and having large buckets would incur a lot of duplication.

If there are sections where there are large differences across distributions, we can just write separate documents and conditionally include them, assuming this works:

<command arch="rhel;centos;fedora"> <xi:include href="fedora-foo.xml" /></command>
<command arch="debian;ubuntu"> <xi:include href="ubuntu-foo.xml" /></command>

Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.
www.nimbisservices.com





On May 21, 2012, at 10:18 AM, Anne Gentle wrote:

> So, yes, what is the best solution here? I can see it working another way, but there may be maintenance tradeoffs. 
> 
> Large buckets:
> Only chapter-level inclusion to indicate which distro. Each chapter contains "normal" markup according to our conventions. There would be two book files, one for ubuntu/deb, one for rhel/centos/fedora, with conditional includes only on the xi:include code in the book file.
> 
> Small buckets:
> Keep the same chapter files we have now, but markup inside the files with <command arch="rhel;centos;fedora"> on each command. 
> 
> I've maintained doc sets both ways - so for me, either way is reasonable. But I worry some about adding more markup within files that we have to explain and understand ourselves. 
> 
> Thoughts?
> 
> Anne
> 
> 
> On Mon, May 21, 2012 at 8:58 AM, David Cramer <david.cramer@xxxxxxxxxxxxx> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> On 05/20/2012 11:56 AM, Lorin Hochstein (Code Review) wrote:
> > Lorin Hochstein has posted comments on this change.
> >
> > Change subject: Adding Fedora/RHEL/Centos instructions.
> > ......................................................................
> >
> >
> >
> > Patch Set 4: Looks good to me, but someone else must approve
> >
> > (1 inline comment)
> >
> > This looks a good way to start.
> >
> > Ultimately, I think it would be really cool if we could use XML to
> > mark up distribution-specific content and generate a separate
> > manual for each distribution.  For example, something like:
> >
> > <distro> <ubuntu>apt-get install foo</ubuntu> <fedora>yum install
> > foo</fedora> </distro>
> 
> I'd suggest using attributes for that kind of thing. Depending on what
> you want to achieve you could do:
> 
> <command arch="rhel">apt-get install foo</command>
> <command arch="ubuntu">yum install foo</command>
> 
> Then create different versions of the guide by filtering out one or
> the other (by adding <profile.arch>rhel</profile.arch> or
> <profile.arch>ubuntu</profile.arch> to your pom).
> 
> If you have a more complex situation, you can even do things like:
> 
> <command arch="rhel;centos;fedora">apt-get install foo</command>
> <command arch="ubuntu;deb">yum install foo</command>
> 
> And in the pom things like <profile.arch>rhel;deb</profile.arch>.
> 
> Alternatively, you could do something like:
> 
> <para arch="rhel">Blah de blah.</para>
> <para arch="ubuntu">Ipsum lorem.</para>
> 
> and then, based on the attribute, have the xslts put an icon off to
> the side (or use some other mechanism) indicating that this
> information applies to rhel, ubuntu, or whatever.
> 
> Those are just some examples to get discussion started. Figure out
> your needs and we can tweak the xslts to make it happen.
> 
> David
> 
> >
> > But I'd rather start getting this content in now.
> >
> > I'd also like to see a section at the beginning that discusses how
> > well supported OpenStack is on different distributions. In
> > particular, there are some distributions where OpenStack is a
> > "first-class citizen" (Ubuntu, Fedora) in the sense that the
> > distribution has official packages. There are other distros where
> > there is package support provided by third parties (e.g., SLES).
> >
> > I have no idea what the state of OpenStack is on RHEL. Do we use
> > official Fedora packages for that? GridDynamics packages? And are
> > CentOS and Scientific Linux supported by being RHEL-alike, or are
> > there people on those projects that look at OpenStack support?
> >
> > .................................................... File
> > doc/src/docbkx/openstack-install/ch_assumptions.xml Line 15:
> > CentOS 6 + CR distributions.</para></listitem> What does "+CR"
> > refer to? Also, what about Debian, openSUSE and SLES?
> >
> > -- To view, visit https://review.openstack.org/7431 To unsubscribe,
> > visit https://review.openstack.org/settings
> >
> > Gerrit-MessageType: comment Gerrit-Change-Id:
> > Idd81d39567a89fb6905901dab9551ecfe27ee847 Gerrit-PatchSet: 4
> > Gerrit-Project: openstack/openstack-manuals Gerrit-Branch: master
> > Gerrit-Owner: Anne Gentle <anne@xxxxxxxxxxxxx> Gerrit-Reviewer:
> > Anne Gentle <anne@xxxxxxxxxxxxx> Gerrit-Reviewer: David Cramer
> > <david@xxxxxxxxxxxx> Gerrit-Reviewer: Lorin Hochstein
> > <lorin@xxxxxxxxxxxxxxxxxx> Gerrit-Reviewer: Razique Mahroua
> > <razique.mahroua@xxxxxxxxx> Gerrit-Reviewer: Tom Fifield
> > Gerrit-Reviewer: p-draigbrady <P@xxxxxxxxxxxxxx>
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
> 
> iQEcBAEBAgAGBQJPukn2AAoJEMHeSXG7afUhyJ4H/36HjNoMTkNRuK0XNCFEEV45
> S/q3EqiIrqrithGYfP00WzOp17kufY8IVnsjBG/LOD89PYhIIfX3nShZyxmNgfex
> ahwjLv47lov827m/OshQTvlwDhrjsd7FV3+QYz+sAXVjTDXL4u3Hv7zKvYAkke1Y
> C/QzOGBbF0ZXcHsRBejxk8BvkXFLVKqbmdwTPUD9pUY364TbRMafP4ke3oe578AU
> iorEGj4HF/QpZAnuF2FHsbYGdo7YW4WBozW/qH08nzqU5emvBV45xPvS+M1+dbpF
> fHOFcuf3VfD4FtpI1gS6QjOS/AaKFq5yAO2slUGgOkrYQcqqhSrWR/2l0v3FJ00=
> =JsiF
> -----END PGP SIGNATURE-----
> 
> --
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
> 
> -- 
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp