Mailing List Archive

On Thursday 01 November 2007 16:57:53 Josh Saddler wrote:
> Hey guys, it's that time of year again, and I'll again be Handbook
> Release Coordinator. I opened a tracker bug[1] for your viewing pleasure.
>
> I've started doing the initial documentation imports, and will be doing
> the rest and prepping the docs with the small changes later, once I'm
> back from work.
>
> So what I need from you guys is your availability status for working on
> docs -- for the last few releases I've pretty much made all the changes
> singlehandedly, and that's quite a load to bear. So, who's around?
>
> Translators, you're going to have extra fun, as there will be lots of
> changes made in a very short time for you to follow. Actually, what
> active languages do we have? I don't even know that anymore. Who will
> have complete translations ready at some point for 2007.1? This affects
> what I put into our index.xml files.

/de should have x86 & amd64 done less than a week after things settle down,
with other arches in the following week. This estimate of course is dependent
on the size of the changes. I plan on doing 2007.1 personally and will finish
it as quickly as possible. It's nice that things are starting now since I
just finished midterms.

It would be great if commit messages or mailing list posts could include
notices when certain files settle down. Of course that is only possible of
developers are nice and get the changes into the bug report in due time so I
realize that it might not be easy.

Hendrik

Josh Saddler wrote:
> Hey guys, it's that time of year again, and I'll again be Handbook
> Release Coordinator. I opened a tracker bug[1] for your viewing pleasure.
>
> I've started doing the initial documentation imports, and will be doing
> the rest and prepping the docs with the small changes later, once I'm
> back from work.
>
> So what I need from you guys is your availability status for working on
> docs -- for the last few releases I've pretty much made all the changes
> singlehandedly, and that's quite a load to bear. So, who's around?
>
> Translators, you're going to have extra fun, as there will be lots of
> changes made in a very short time for you to follow. Actually, what
> active languages do we have? I don't even know that anymore. Who will
> have complete translations ready at some point for 2007.1? This affects
> what I put into our index.xml files.
>
> We got a lot of docs to cover, not just the installation handbooks. See
> [2], Chapter 2, for a listing.
>
> Anyway, I'll keep you updated as we reach milestones. I say "we" because
> I hope at least some of you will be available to help out. :)
>
> Luck, and a great release,
>
> Josh
>
>
> [1] http://bugs.gentoo.org/show_bug.cgi?id=197814
> [2] http://www.gentoo.org/proj/en/gdp/doc/handbook-release.xml
>

I'll be handling the ppc and ppc64 handbooks this release. I'd like
to combine them actually, since we'll be using the same release
media for both architectures. Would this be fine with you guys?
Did anything ever happen with the templated handbook idea?

-Joe
--
gentoo-doc@gentoo.org mailing list

Joseph Jezak wrote:
> Josh Saddler wrote:
>> Hey guys, it's that time of year again, and I'll again be Handbook
>> Release Coordinator. I opened a tracker bug[1] for your viewing pleasure.
>>
>> I've started doing the initial documentation imports, and will be doing
>> the rest and prepping the docs with the small changes later, once I'm
>> back from work.
>>
>> So what I need from you guys is your availability status for working on
>> docs -- for the last few releases I've pretty much made all the changes
>> singlehandedly, and that's quite a load to bear. So, who's around?
>>
>> Translators, you're going to have extra fun, as there will be lots of
>> changes made in a very short time for you to follow. Actually, what
>> active languages do we have? I don't even know that anymore. Who will
>> have complete translations ready at some point for 2007.1? This affects
>> what I put into our index.xml files.
>>
>> We got a lot of docs to cover, not just the installation handbooks. See
>> [2], Chapter 2, for a listing.
>>
>> Anyway, I'll keep you updated as we reach milestones. I say "we" because
>> I hope at least some of you will be available to help out. :)
>>
>> Luck, and a great release,
>>
>> Josh
>>
>>
>> [1] http://bugs.gentoo.org/show_bug.cgi?id=197814
>> [2] http://www.gentoo.org/proj/en/gdp/doc/handbook-release.xml
>>
>
> I'll be handling the ppc and ppc64 handbooks this release. I'd like
> to combine them actually, since we'll be using the same release
> media for both architectures. Would this be fine with you guys?
> Did anything ever happen with the templated handbook idea?
>
> -Joe

I never heard back from Xavier on the handbook includes proposal, so . .
. who knows. Combining the ppc handbooks seems like it'll take quite a
bit of work though, as I imagine there will need to be a lot of
conditionals for 64/32-bit differences. Well, that's what I'm guessing
anyway. I mean, there's a while extra chapter or something just for
oldworld machines, and other 32-bit ppc platforms.

Still, let's take a look at the code and see what duplicates what. I'm
sure we can think of something. :)

(Though it really really would be nice to finally get handbook includes
for everything! --hint hint)

Joseph Jezak wrote:
> I'll be handling the ppc and ppc64 handbooks this release. I'd like
> to combine them actually, since we'll be using the same release
> media for both architectures. Would this be fine with you guys?

Sure. Using the conditionals like we did for x86/amd64 should help. IA64
shares one of the joined files iirc.
You don't have to join all 4 distinct files btw. Combine the files that share
a lot of content, but keep the very different ones separate.

Just ask if you need help to use those conditionals.

> Did anything ever happen with the templated handbook idea?

Templated hanbook idea? Did you mean the include idea like Josh guessed?
If so, it's *almost* working on my home box (not the public one), but I still
need to fix some anchors and the comparison of translations vs. originals
When & whether it will make it to our guide.xsl is still not clear, but it
would take plenty of time, motivation and testing before it ends up on
www.g.o. I hope we'd be able to use a test web node, maybe bluejay of pheasant.


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/

Xavier Neys wrote:
> Templated hanbook idea? Did you mean the include idea like Josh guessed?
> If so, it's *almost* working on my home box (not the public one), but I still
> need to fix some anchors and the comparison of translations vs. originals
> When & whether it will make it to our guide.xsl is still not clear, but it
> would take plenty of time, motivation and testing before it ends up on
> www.g.o. I hope we'd be able to use a test web node, maybe bluejay of pheasant.


I love it when you talk dirty. :D

Seriously though, I'm thrilled that you've got it to where it is now;
I'd love to see it in place on our website. Who do we bug for access to
bluejay? Infra? Or www@ ?

Josh Saddler wrote:
> Translators, you're going to have extra fun, as there will be lots of
> changes made in a very short time for you to follow. Actually, what
> active languages do we have? I don't even know that anymore. Who will
> have complete translations ready at some point for 2007.1? This affects
> what I put into our index.xml files.

Simplified Chinese team is standing by.

--
Zhang Le, Robert
GPG key ID: 1E4E2973
Fingerprint: 0260 C902 B8F8 6506 6586 2B90 BC51 C808 1E4E 2973
--
gentoo-doc@gentoo.org mailing list

Il Monday 05 November 2007 20:45:20 Zhang Le ha scritto:
> Josh Saddler wrote:
> > Translators, you're going to have extra fun, as there will be lots of
> > changes made in a very short time for you to follow. Actually, what
> > active languages do we have? I don't even know that anymore. Who will
> > have complete translations ready at some point for 2007.1? This affects
> > what I put into our index.xml files.
>
> Simplified Chinese team is standing by.
>

And Italian team is ready too 8)

Cheers,

--
Davide Cendron

Gentoo Documentation Project
Italian Lead Translator

http://www.gentoo.org/doc/it/

Davide Cendron írta:
> Il Monday 05 November 2007 20:45:20 Zhang Le ha scritto:
>
>> Josh Saddler wrote:
>>
>>> Translators, you're going to have extra fun, as there will be lots of
>>> changes made in a very short time for you to follow. Actually, what
>>> active languages do we have? I don't even know that anymore. Who will
>>> have complete translations ready at some point for 2007.1? This affects
>>> what I put into our index.xml files.
>>>
>> Simplified Chinese team is standing by.
>>
>>
>
> And Italian team is ready too 8)
>
> Cheers,
>
>
The Hungarian team is also ready to work :)

--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Németh Balázs

web: http://kac.duf.hu/~balage

Public GPG key: http://kac.duf.hu/~balage/downloads/Nemeth_Balazs_public_key_0xB0B0F0D9.asc

Josh Saddler wrote:
> Xavier Neys wrote:
>> Templated hanbook idea? Did you mean the include idea like Josh guessed?
>> If so, it's *almost* working on my home box (not the public one), but I still
>> need to fix some anchors and the comparison of translations vs. originals
>> When & whether it will make it to our guide.xsl is still not clear, but it
>> would take plenty of time, motivation and testing before it ends up on
>> www.g.o. I hope we'd be able to use a test web node, maybe bluejay of pheasant.
>
> Seriously though, I'm thrilled that you've got it to where it is now;
> I'd love to see it in place on our website. Who do we bug for access to
> bluejay? Infra? Or www@ ?

I have root on bluejay (it runs off a snapshot of htdocs atm.) but since
there's nothing available to be put on it for testing...

GOOD news:
I believe I've got it right on my box.
I tested two guides[1][2] (I already had this feature in mind when I rewrote
the quick guide and its lvm+raid sibling), and a bit of a handbook[3].

BAD news:
I still don't know when, or even whether, this would be available in Gentoo's
own XSL. Almost all templates need to be changed and it's *not* going to
happen overnight.

[1] http://gentoo.neysx.org/mystuff/gentoo-x86+raid+lvm2-quickinstall.xml
[2] http://gentoo.neysx.org/mystuff/gentoo-x86-quickinstall.xml
[3] http://gentoo.neysx.org/mystuff/handbook/handbook-x86.xml?part=1&chap=4

The logic is chapters, sections and bodies can all be included, i.e. they
either have the current structure or contain a single <include href=""/>
element. A chapter can include chapters, a section can include sections and a
body can include bodies.

It's a bit unfair to let you know all this without knowing when or whether you
can use it, but at least you know...


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/

Xavier Neys wrote:
> GOOD news:
> I believe I've got it right on my box.
> I tested two guides[1][2] (I already had this feature in mind when I rewrote
> the quick guide and its lvm+raid sibling), and a bit of a handbook[3].

That IS good news!

> BAD news:
> I still don't know when, or even whether, this would be available in Gentoo's
> own XSL. Almost all templates need to be changed and it's *not* going to
> happen overnight.
>
> [1] http://gentoo.neysx.org/mystuff/gentoo-x86+raid+lvm2-quickinstall.xml
> [2] http://gentoo.neysx.org/mystuff/gentoo-x86-quickinstall.xml
> [3] http://gentoo.neysx.org/mystuff/handbook/handbook-x86.xml?part=1&chap=4
>
> The logic is chapters, sections and bodies can all be included, i.e. they
> either have the current structure or contain a single <include href=""/>
> element. A chapter can include chapters, a section can include sections and a
> body can include bodies.

Awesome. So the includes are all inline, and don't need to be specified
in the handbook-$arch.xml files.

Now, where are those includes being pulled from? Let's take
hb-install-sparc-disk.xml. There's quite a bit of common stuff to all
the other handbooks, as well as Sparc-specific partitioning sections.
For the common stuff, such as the "Block Devices" subsection, is it
reading that from a separate xml file? like block-devices.xml, that
contains just a tiny bit of xml for the block devices subsection?

I just want to be clear on how the includes are actually working.

> It's a bit unfair to let you know all this without knowing when or whether you
> can use it, but at least you know...

No, that's okay. As when I emailed the list back around the 2007.0
release, it was understood that it wasn't a change that could be made
right away, and I wasn't expecting it to be completely ready for the
2007.1 release either.

However, say it gets ready some time in the next 3 months, about halfway
between releases. How about putting it into effect right away on the
online handbooks well in advance of the next release? I'm willing to do
the work on converting the handbooks myself, if need be. Sure, the docs
on the CDs would have a different structure, but we can't do anything
about those anyway once they're packaged up.

Josh Saddler wrote:
> Xavier Neys wrote:
>> GOOD news:
>> I believe I've got it right on my box.
>> I tested two guides[1][2] (I already had this feature in mind when I rewrote
>> the quick guide and its lvm+raid sibling), and a bit of a handbook[3].
>
> That IS good news!

If you say so ;-)
Wait until you have to start using it.

>> BAD news:
>> I still don't know when, or even whether, this would be available in Gentoo's
>> own XSL. Almost all templates need to be changed and it's *not* going to
>> happen overnight.
>>
>> [1] http://gentoo.neysx.org/mystuff/gentoo-x86+raid+lvm2-quickinstall.xml
>> [2] http://gentoo.neysx.org/mystuff/gentoo-x86-quickinstall.xml
>> [3] http://gentoo.neysx.org/mystuff/handbook/handbook-x86.xml?part=1&chap=4
>>
>> The logic is chapters, sections and bodies can all be included, i.e. they
>> either have the current structure or contain a single <include href=""/>
>> element. A chapter can include chapters, a section can include sections and a
>> body can include bodies.
>
> Awesome. So the includes are all inline, and don't need to be specified
> in the handbook-$arch.xml files.

They appear where they are supposed to be included, just like in the current
handbook format, e.g. a <chapter> either contains its content as it does now
*xor* a single <include> element that points to an xml files that contains
chapter(s).

Including chapters in a guide:

<chapter id="foo" test="1">
<include href="bar.xml"/>
</chapter>

or in a handbook:

<section id="foo" test="1">
<include href="bar.xml"/>
</section>

The included file is expected to contain one or more <chapter>


Including sections in a guide:

<section id="foo" test="1">
<include href="bar.xml"/>
</section>

or in a handbook:

<subsection id="foo" test="1">
<include href="bar.xml"/>
</subsection>

The included file is expected to contain one or more <section>


Including bodies:

<body id="foo" test="1">
<include href="bar.xml"/>
</body>

The included file is expected to contain one or more <body>

BTW, I still think it sucks to have different names for the same things in
guides and books, and even more to have the same names for different things :(

Conditional still apply to the same elements, nothing's changed at all.
Nothing is preventing an included chapter from including sections.

> Now, where are those includes being pulled from? Let's take
> hb-install-sparc-disk.xml. There's quite a bit of common stuff to all
> the other handbooks, as well as Sparc-specific partitioning sections.
> For the common stuff, such as the "Block Devices" subsection, is it
> reading that from a separate xml file? like block-devices.xml, that
> contains just a tiny bit of xml for the block devices subsection?
>
> I just want to be clear on how the includes are actually working.

Take a look at the xml I posted links to.
I only used the file systems part of hb*disk*xml as an example.
Maybe I'll factor out more common bits from the hb*disk*xml files in the
coming days.

Please note that it's very much useless to factor out just a couple of
sentences. It adds unnecessary complexity and it makes it harder to evaluate
the impact of a change to a shared file.

>> It's a bit unfair to let you know all this without knowing when or whether you
>> can use it, but at least you know...
>
> No, that's okay. As when I emailed the list back around the 2007.0
> release, it was understood that it wasn't a change that could be made
> right away, and I wasn't expecting it to be completely ready for the
> 2007.1 release either.

It won't be available for the next release and it wouldn't be reasonable to
implement this right before a release.

> However, say it gets ready some time in the next 3 months, about halfway
> between releases. How about putting it into effect right away on the
> online handbooks well in advance of the next release? I'm willing to do
> the work on converting the handbooks myself, if need be. Sure, the docs
> on the CDs would have a different structure, but we can't do anything
> about those anyway once they're packaged up.

Right between two releases would be ideal.
I don't know about 3 months and I don't know between which two releases this
could become available.
At least, if I had an ETA, I'd make it public ;)


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/

>>> The logic is chapters, sections and bodies can all be included, i.e. they
>>> either have the current structure or contain a single <include href=""/>
>>> element. A chapter can include chapters, a section can include sections and a
>>> body can include bodies.
>> Awesome. So the includes are all inline, and don't need to be specified
>> in the handbook-$arch.xml files.
>
> They appear where they are supposed to be included, just like in the current
> handbook format, e.g. a <chapter> either contains its content as it does now
> *xor* a single <include> element that points to an xml files that contains
> chapter(s).
>
> Including chapters in a guide:
>
> <chapter id="foo" test="1">
> <include href="bar.xml"/>
> </chapter>
>
> or in a handbook:
>
> <section id="foo" test="1">
> <include href="bar.xml"/>
> </section>
>
> The included file is expected to contain one or more <chapter>
>
>
> Including sections in a guide:
>
> <section id="foo" test="1">
> <include href="bar.xml"/>
> </section>
>
> or in a handbook:
>
> <subsection id="foo" test="1">
> <include href="bar.xml"/>
> </subsection>
>
> The included file is expected to contain one or more <section>
>
>
> Including bodies:
>
> <body id="foo" test="1">
> <include href="bar.xml"/>
> </body>
>
> The included file is expected to contain one or more <body>


***
Read the above explanation again, twice, because that's the only documentation
available at the moment :)
***


> BTW, I still think it sucks to have different names for the same things in
> guides and books, and even more to have the same names for different things :(

Still does.

> Conditional still apply to the same elements, nothing's changed at all.
> Nothing is preventing an included chapter from including sections.
>
> Please note that it's very much useless to factor out just a couple of
> sentences. It adds unnecessary complexity and it makes it harder to evaluate
> the impact of a change to a shared file.
>
> It won't be available for the next release and it wouldn't be reasonable to
> implement this right before a release.

Since Gentoo does not have any releases... ;-)

I had a full day at home and I thought I could get this done.
DTDs and XSLs have been edited.
x86 guick guides (normal & raid+lvm2) make use of this feature.
If you notice anything weird, think again, then ask/file a bug, I probably
forgot something.

FYI, <pre> in handbooks are now numbered exactly as they are in normal guides,
and they are unique in ?full=1 versions.


Happy New Year,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/