openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

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
>