openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all,
Just updated the review patchset with a test set using attributes and
profile.arch, but I'm pretty clueless about where to put it (is it really
profile.arch? Oxygen never validated it no matter where I put it), and the
build isn't filtering out stuff with "rhel;centos;fedora" attributes as
expected- David can you take  a look when you get a chance?

https://review.openstack.org/7431

The small bucket approach might be more difficult than I anticipated since
Fedora has this openstack-config command - but maybe it'll sort itself out
with some simpler paragraphs introducing that command.

Thanks,
Anne


On Tue, May 22, 2012 at 2:23 AM, Razique Mahroua
<razique.mahroua@xxxxxxxxx>wrote:

> Hi,
> +1 for the small bucke approach, but it's just I know that approach better.
> Would the per-distro filtering that efficient ? In term of usage and
> maintenance ?
> Is there somewhere an example to see it working ?
> Best regards,
> Razique
>
>  Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx>
>  22 mai 2012 03:27
> 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
>
>
>
>
>
>
>
>   Anne Gentle <anne@xxxxxxxxxxxxx>
>  21 mai 2012 16:18
> 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
>
>
>
>   David Cramer <david.cramer@xxxxxxxxxxxxx>
>  21 mai 2012 15:58
>
> -----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> <anne@xxxxxxxxxxxxx> Gerrit-Reviewer:
> Anne Gentle <anne@xxxxxxxxxxxxx> <anne@xxxxxxxxxxxxx> Gerrit-Reviewer: David Cramer<david@xxxxxxxxxxxx> <david@xxxxxxxxxxxx> Gerrit-Reviewer: Lorin Hochstein<lorin@xxxxxxxxxxxxxxxxxx> <lorin@xxxxxxxxxxxxxxxxxx> Gerrit-Reviewer: Razique Mahroua<razique.mahroua@xxxxxxxxx> <razique.mahroua@xxxxxxxxx> Gerrit-Reviewer: Tom Fifield
> Gerrit-Reviewer: p-draigbrady <P@xxxxxxxxxxxxxx> <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-----
>
>
>   Lorin Hochstein (Code Review) <review@xxxxxxxxxxxxx>
>  20 mai 2012 18:56
> 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>
>
> 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> <anne@xxxxxxxxxxxxx>
> Gerrit-Reviewer: Anne Gentle <anne@xxxxxxxxxxxxx> <anne@xxxxxxxxxxxxx>
> Gerrit-Reviewer: David Cramer <david@xxxxxxxxxxxx> <david@xxxxxxxxxxxx>
> Gerrit-Reviewer: Lorin Hochstein <lorin@xxxxxxxxxxxxxxxxxx><lorin@xxxxxxxxxxxxxxxxxx>
> Gerrit-Reviewer: Razique Mahroua <razique.mahroua@xxxxxxxxx><razique.mahroua@xxxxxxxxx>
> Gerrit-Reviewer: Tom Fifield
> Gerrit-Reviewer: p-draigbrady <P@xxxxxxxxxxxxxx> <P@xxxxxxxxxxxxxx>
>
>
> --
> Nuage & Co - Razique Mahroua
> razique.mahroua@xxxxxxxxx
>
>
>
>