Mailing List Archive: GuideXML: define values & use conditional tags

GuideXML: define values & use conditional tags

Jun 22, 2006, 4:11 AM

Post #1 of 10 (2932 views)

Hi *,

With a new release coming out soon(-ish), we're going to have to hunt and
update quite a few variable data such as snapshot names/locations, CD sizes,
kernel versions in all our handbooks.
Some time ago, we discussed the possibility of defining values at the
beginning of the handbooks so that we need only update each value once, always
at the same place.

Besides, allowing conditional bodies would let us solve bugs like
http://bugs.gentoo.org/show_bug.cgi?id=52856 or the latest
http://bugs.gentoo.org/show_bug.cgi?id=132816. Paragraphs like "Sparc users or
PPC machines blah blah di blah" are getting more and more common and
inconsistencies such as the partitioning schemes in the the hb-ARCH-disk.xml
files and the common hb-install-config.xml are inevitable without conditionals.

Please have a look at the following links and compare:

Define values in books:
http://gentoo.neysx.org/mystuff/handbook/handbook-mips.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-hppa.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-alpha.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-ppc64.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-ppc.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-amd64.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-sparc.xml?passthru=1
http://gentoo.neysx.org/mystuff/handbook/handbook-x86.xml?passthru=1

Use them:
http://gentoo.neysx.org/mystuff/handbook/hb-install-config.xml?passthru=1

I did not want to make block tags conditional to avoid having to test all
p,table,pre,ul,dl... and added a test attribute to the body tag. The only
change to the DTD would be to make "body+" and add the test attribute.
The test can be any XPath expression that is evaluated and if it returns true,
the body is processed.

The result looks like:
http://gentoo.neysx.org/mystuff/handbook/handbook-x86.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-sparc.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-amd64.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-ppc.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-ppc64.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-alpha.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-hppa.xml?part=1&chap=8
http://gentoo.neysx.org/mystuff/handbook/handbook-mips.xml?part=1&chap=8

The good side is we could deliver less encumbered handbooks and please our users.
The drawback is that it makes writing text that flows properly in all cases
more difficult for us.

If you guys like it, it goes in, but if you think is too complex or too much
work to maintain, I shall not push it down your throat :)

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

Re: GuideXML: define values & use conditional tags [ In reply to ]

wolf31o2 at gentoo

Jun 23, 2006, 7:10 AM

Post #2 of 10 (2858 views)

Permalink

On Thu, 2006-06-22 at 13:11 +0200, Xavier Neys wrote:
> With a new release coming out soon(-ish), we're going to have to hunt and
> update quite a few variable data such as snapshot names/locations, CD sizes,
> kernel versions in all our handbooks.

I think for these, sed is usually all it takes.

> Some time ago, we discussed the possibility of defining values at the
> beginning of the handbooks so that we need only update each value once, always
> at the same place.

That being said, I really like the idea. It might take a little while
to get the wording to look correct and flow properly (as in the first
handbook or so using this might not flow the best), but I think that
overall it will end up giving a better experience for our users.

Of course, I'm also not going to request any such change. I definitely
think that how the Handbook is done (especially at the underlying
levels) is totally up to you guys. I'm just letting you know that I'd
definitely support it.

--
Chris Gianelloni
Release Engineering - Strategic Lead
x86 Architecture Team
Games - Developer
Gentoo Linux

Re: GuideXML: define values & use conditional tags [ In reply to ]

redhatter at gentoo

Jun 23, 2006, 8:41 PM

Post #3 of 10 (2854 views)

Permalink

Xavier Neys wrote:

> Besides, allowing conditional bodies would let us solve bugs like
> http://bugs.gentoo.org/show_bug.cgi?id=52856 or the latest
> http://bugs.gentoo.org/show_bug.cgi?id=132816. Paragraphs like "Sparc users or
> PPC machines blah blah di blah" are getting more and more common and
> inconsistencies such as the partitioning schemes in the the hb-ARCH-disk.xml
> files and the common hb-install-config.xml are inevitable without conditionals.

Well... I had this exact problem with the MIPS handbook. There was
quite a bit of information, not relevant to other architectures, that I
needed to get across, which related to stageball selection.

Thus, MIPS is the only ARCH that has it's own stage selection section
(hb-install-mips-stage.xml), whereas the others all share a common file
(hb-install-stage.xml).

This meant I could go into greater detail, and thus made (IMHO) a higher
quality manual.

> The good side is we could deliver less encumbered handbooks and please our users.
> The drawback is that it makes writing text that flows properly in all cases
> more difficult for us.

Yeah, this is definitely an issue. It'd mean having to write the doc a
few times to get it right with all possible selections. Then again, the
solution I went with (to get around this issue) also involves a lot of
duplication of information, which has its drawbacks too.

--
Stuart Longland (aka Redhatter) .'''.
Gentoo Linux/MIPS Cobalt and Docs Developer '.'` :
. . . . . . . . . . . . . . . . . . . . . . .'.'
http://dev.gentoo.org/~redhatter :.'

International Asperger's Year (1906 ~ 2006)
http://dev.gentoo.org/~redhatter/iay

Re: GuideXML: define values & use conditional tags [ In reply to ]

jkt at gentoo

Jun 26, 2006, 3:32 AM

Post #4 of 10 (2858 views)

Permalink

Chris Gianelloni wrote:
> On Thu, 2006-06-22 at 13:11 +0200, Xavier Neys wrote:
>> With a new release coming out soon(-ish), we're going to have to hunt and
>> update quite a few variable data such as snapshot names/locations, CD sizes,
>> kernel versions in all our handbooks.
>
> I think for these, sed is usually all it takes.

Not for translators. I usually look at the CVS diffs and don't use sed
as I can't be completely sure what else has changed.

Cheers,
-jkt

--
cd /local/pub && more beer > /dev/mouth

Re: GuideXML: define values & use conditional tags [ In reply to ]

jkt at gentoo

Jun 26, 2006, 3:35 AM

Post #5 of 10 (2854 views)

Permalink

Xavier Neys wrote:
> http://gentoo.neysx.org/mystuff/handbook/handbook-mips.xml?part=1&chap=8

"If our default MIPS partitioning example, /boot is usually the
/dev/sda1 partition (or /dev/sda* if you use SCSI or SATA drives)"

Better to combine the tags for inclusion with conditional <body> or
<p|warn|impo|...>, IMHO.

Cheers,
-jkt

--
cd /local/pub && more beer > /dev/mouth

Re: GuideXML: define values & use conditional tags [ In reply to ]

flammie at gentoo

Jun 27, 2006, 5:35 AM

Post #6 of 10 (2859 views)

Permalink

2006-06-22, Xavier Neys sanoi, jotta:

> With a new release coming out soon(-ish), we're going to have to hunt
> and update quite a few variable data such as snapshot
> names/locations, CD sizes, kernel versions in all our handbooks.
> Some time ago, we discussed the possibility of defining values at the
> beginning of the handbooks so that we need only update each value
> once, always at the same place.

> If you guys like it, it goes in, but if you think is too complex or
> too much work to maintain, I shall not push it down your throat :)
>
>
> Feedback welcome,

The change towards variables for version information and such is good
per se, but as translator I should probably remind, that using
variables does make creating good translations a bit harder. As an
example, translation of
"[...] <keyval id="arch"/> systems and <keyval id="arch"/>
clones [...]"
will be "<keyval id="arch"/>-jÃ¤rjestelmÃ¤t ja <keyval
id="arch"/>-kloonit" if and only if <keyval/> doesn't contain spaces,
otherwise hyphens must be preceded by spaces. Variables also
practically prevent use of any affixes, which will reduce the quality of
translations in languages with rich morphology, such as Finnish.

So, what I'm basically suggesting is only to avoid overusing these
variables. While they are mostly fine in version numbers,
file system paths and such codes, they may cause problems in names,
phrases and such.
--
Flammie, Gentoo Linux Documentationâ€™s Finnish head translator
and FlameEyesâ€™ bot <http://dev.gentoo.org/~flammie>.

Re: GuideXML: define values & use conditional tags [ In reply to ]

neysx at gentoo

Jul 15, 2006, 4:59 AM

Post #7 of 10 (2861 views)

Permalink

Jan KundrÃ¡t wrote:
> Xavier Neys wrote:
>> http://gentoo.neysx.org/mystuff/handbook/handbook-mips.xml?part=1&chap=8
>
> "If our default MIPS partitioning example, /boot is usually the
> /dev/sda1 partition (or /dev/sda* if you use SCSI or SATA drives)"
>
> Better to combine the tags for inclusion with conditional <body> or
> <p|warn|impo|...>, IMHO.

I can live with conditional <p>, <note>, <impo> & <warn> tags. No more.
It will make it a bit easier than to have to use separate bodies just for a note.
If more content has to be conditional (pre, lists, tables...), then wrap them
up in a conditional body.

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

Re: GuideXML: define values & use conditional tags [ In reply to ]

neysx at gentoo

Jul 15, 2006, 5:07 AM

Post #8 of 10 (2870 views)

Permalink

Flammie Pirinen wrote:
> 2006-06-22, Xavier Neys sanoi, jotta:
>
>> With a new release coming out soon(-ish), we're going to have to hunt
>> and update quite a few variable data such as snapshot
>> names/locations, CD sizes, kernel versions in all our handbooks.
>> Some time ago, we discussed the possibility of defining values at the
>> beginning of the handbooks so that we need only update each value
>> once, always at the same place.
>
>> If you guys like it, it goes in, but if you think is too complex or
>> too much work to maintain, I shall not push it down your throat :)
>>
>>
>> Feedback welcome,
>
> The change towards variables for version information and such is good
> per se, but as translator I should probably remind, that using
> variables does make creating good translations a bit harder. As an
> example, translation of
> "[...] <keyval id="arch"/> systems and <keyval id="arch"/>
> clones [...]"
> will be "<keyval id="arch"/>-jÃ¤rjestelmÃ¤t ja <keyval
> id="arch"/>-kloonit" if and only if <keyval/> doesn't contain spaces,
> otherwise hyphens must be preceded by spaces. Variables also
> practically prevent use of any affixes, which will reduce the quality of
> translations in languages with rich morphology, such as Finnish.
>
> So, what I'm basically suggesting is only to avoid overusing these
> variables. While they are mostly fine in version numbers,
> file system paths and such codes, they may cause problems in names,
> phrases and such.

I expect no less than translators being able to just cut'n'paste the values.
If it causes trouble to translators, something must be fixed asap and I trust
you'll report any issues :)

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

Re: GuideXML: define values & use conditional tags [ In reply to ]

neysx at gentoo

Jul 28, 2006, 1:22 AM

Post #9 of 10 (2854 views)

Permalink

Re: GuideXML: define values & use conditional tags [ In reply to ]

neysx at gentoo

Aug 3, 2006, 3:20 AM

Post #10 of 10 (2859 views)

Permalink

Xavier Neys wrote:

> I'll try to add it all on www.g.o early next week, or early the week after.
> I receive family this weekend and I'll be away the next one, and I don't
> commit anything like this unless I know I can be available in case anything
> goes wrong :)

Done. I'll amend xml-guide.xml next week though.

x86 & amd64 arch specific files have been merged.
hb-install-config.xml is now clean of foreign arches for all arches.
Other common files still need to be "cleaned up".
Feel free to file patches on bugs if you feel like trying it :)

What this feature is meant for:
1) define values that need to be changed at every release. Use values only,
don't even put units in there.
2) allow tests, usually on arch, to avoid foreign arches from common files.
3) possibly merge arch-specific files that are very similar, like x86 & amd64
which share the same tools, terminology, partition schemes...
4) possibly merge current & xxxx.y files as long as they are very similar
*and* stay similar at least until the next release.
FYI, xxxx.y docs are supposed to keep working as long as xxxx.y is the latest
version, current handbooks keep moving along.

What it is *not* meant for:
Merge everything back into huge files full of conditionals.

Feedback, questions? Use this ML or #gentoo-doc

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

Mailing List Archive

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files: