Re: Using conditional expressions in Gnome documentations

[Shaun McCance <shaunm gnome org>]

On Wed, 2012-12-05 at 21:32 +0100, Gabor Kelemen wrote:
> Hi
> 
> I have just filed a bug[1] that can be solved by using conditional 
> expressions in the xml. I saw several places in the 3.6 branch where 
> these were used to include Ubuntu-specific changes, so I thought it is a 
> good idea to add one more.
> 
> But now I see that the number of such conditional expressions was 
> recently reduced[2], so I started to wonder why did this happen?
> 
> Was this reduction intentional for some technical reason, or was this 
> just an oversight and I should file a bug about it?

We stripped the Unity conditionals out of gnome-help because it
doesn't get used under Unity. If you're running Unity, you'll
see ubuntu-help instead.

It makes sense for standalone application help.

Two notes:

1) You can actually use help: links inside xref. That leaves
href available to provide an http: link.

<link xref="help:gnome-help/a11y"
href="http://library.gnome.org/users/gnome-help/stable/a11y.html";>
Universal Access Help</link>

The href will be used by straight HTML builds, such as on
library.gnome.org.

2) We're really making translators lives unpleasant by having
nearly identical duplicate strings, where the only difference
is a URL they shouldn't change anyway. We could do something
like this:

<p><p>For a complete listing of GNOME's caret navigation commands,
see the <link href="..." xmlns:its="http://www.w3.org/2005/11/its";
its:withinText="yes">Universal Access Help</link>.</p>

Then we'd no longer get the duplicate string, but we'd instead
get a placeholder string like this:

msgid ""
"For a complete listing of GNOME's caret navigation commands, "
"see the <_:link/>."

msgid "Universal Access Help"

I'm not sure what sucks more for translators.

It might be worth investigating adding some sort of key-based
linking to Mallard 1.1, like DITA's keyref, but less crazy.

--
Shaun