Re: [Openstack-doc-core] Change in openstack/openstack-manuals[master]: Adding Fedora/RHEL/Centos instructions.

Tue, 22 May 2012 00:23:49 -0700

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
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="" /></command>
<command arch="debian;ubuntu"> <xi:include href="" /></command>

Take care,

Lorin
--
Lorin Hochstein
Lead Architect - Cloud Services
Nimbis Services, Inc.







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



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 <[email protected]> Gerrit-Reviewer:
Anne Gentle <[email protected]> Gerrit-Reviewer: David Cramer
<[email protected]> Gerrit-Reviewer: Lorin Hochstein
<[email protected]> Gerrit-Reviewer: Razique Mahroua
<[email protected]> Gerrit-Reviewer: Tom Fifield 
Gerrit-Reviewer: p-draigbrady <[email protected]>

-----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 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 <[email protected]>
Gerrit-Reviewer: Anne Gentle <[email protected]>
Gerrit-Reviewer: David Cramer <[email protected]>
Gerrit-Reviewer: Lorin Hochstein <[email protected]>
Gerrit-Reviewer: Razique Mahroua <[email protected]>
Gerrit-Reviewer: Tom Fifield
Gerrit-Reviewer: p-draigbrady <[email protected]>

--
Nuage & Co - Razique Mahroua
[email protected]

  

-- 
Mailing list: https://launchpad.net/~openstack-doc-core
Post to     : [email protected]
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help   : https://help.launchpad.net/ListHelp

Reply via email to