Re: [gentoo-dev] A few questions to our nominees

[Ciaran McCreesh]

On Mon, 09 Jun 2008 12:56:33 +0200
Luca Barbato <lu_zero@g.o> wrote:
> Ciaran McCreesh wrote:
> > On Mon, 09 Jun 2008 03:28:03 -0700
> > Josh Saddler <nightmorph@g.o> wrote:
> >> <p>
> >> Global variables must only contain invariant values (see <uri
> >> link="#metadata-invariance">link</uri>). If a global variable's
> >> value is invariant, it may have the value that would be generated
> >> at any given point in the build sequence.
> >> </p>
> >
> > First, your link is incorrect. metadata-invariance is in a different
> > file.
>
> Pointless nit.

No, extremely important point. With PMS we can have things split over
lots of files, and not have to care what file something's in when we
link to it. This means we can move things around between files, not
have to worry about breaking links, and be told automatically if we do
screw up a link. How do we get this using GuideXML?

> > Second, the link's text should be the section name or chapter
> > number. Rendered as "(see link)" is horribly ugly.
>
> your opinion, just yours.

It's really not. Please point me to professional style guides that do
reference links using "link" as the text.

Also see http://www.w3.org/QA/Tips/noClickHere .

> > Third, you should have a non-breaking space between 'see' and the
> > reference.
>
> Pointless nit.

You're the one that wants good, readable output.

> > How does "bunch o'neat code" deal with our code file containing
> > things that XML considers to be reserved characters? That code
> > probably has ampersands and angle brackets in it.
>
> As usual for xml markups.

Which is what? You have to manually copy the source content into the
XML document, fixing the code yourself? Or come up with some convoluted
build scripts to do it?

-- 
Ciaran McCreesh