Re: Different menu layouts in different distros / default desktop configurations

[Shaun McCance <shaunm gnome org>]

On Tue, 2010-05-11 at 13:06 -0500, Jim Campbell wrote:
> Hi All,
> 
> Recently I've been thinking of how we'll direct users to perform
> certain menu actions in the desktop help, and how these instructions
> may be a bit less consistent across various distros and configurations
> in the future.
> 
> For example, until recently, if a distro was shipping Gnome it could
> be safely assumed that users would open an app in (at least
> relatively) the same way in one distro as they would in another
> (Applications / Places / System, etc.).  Now we're looking at a
> situation where some distros will (maybe) be shipping Gnome 3 as
> default, some will be shipping the Gnome 2 layout as default, and
> others will be putting together their own combination of special menus
> (ala Ubuntu).  
> 
> I was wondering what approaches we could take to mitigate this issue
> for downstream projects.  We could have some instructions specific to
> Gnome 2 / Gnome 3, but I'd want to avoid duplication of effort.  We
> could revisit conditional text in Mallard, but I'm not sure what state
> that is in for now.  I think perhaps the most promising approach would
> be to use entities, which would make it relatively easy for
> downstreams to patch the click-paths to suit their own needs.  (After
> all, we aren't sure what Ubuntu's menus are going to end up like, nor
> do we know exactly how Gnome Shell is going to turn out.)  Moreover,
> using entities gives us (or downstream) the chance to have something
> fixed once (in the entities) and then it is fixed throughout the help
> files.
> 
> I got this to work when writing help for the Xfce Screenshooter
> application.  Here's a sample of what I did, starting with line 1 of
> the page:
> 
> <!DOCTYPE page [
> <!ENTITY % entities-xfce SYSTEM "help-libs/entities-xfce.ent">
> %entities-xfce;
> <!ENTITY % entities-xfce-app SYSTEM "help-libs/entities-xfce-app.ent">
> %entities-xfce-app;
> ]>
> 
> <page xmlns="http://projectmallard.org/1.0/";
>       xmlns:e="http://projectmallard.org/experimental/";
>       type="topic" style="task"
>       id="take-save-screenshots">
> 
> As you can see, I had two entity files... one for the Xfce release,
> and another entity file for that specific application.

I'm worried about how this interacts with translations. Would
we have an entities file shipped with each document that wants
to use them, or would we have some sort of global file?

When we create PO files, we deliberately substitute entities.
People will often use entities like this: "&app; is awesome!",
"You should use &app;.", "You can do that with &app;." That's
a subject, a direct object, and an object of a preposition.
Many languages have to translate those differently, so we
always substitute the entities before translation.

Any downstream modifications need to be translated downstream,
no matter what strategy we use. I guess we just need to make
sure that translators can translate well.

Another option is XInclude/XPointer, but because we don't
substitute XInclude before translation, I don't really like
using it for sentence fragments.

Tangentially, how big of a problem is this, really? The DH
probably needs to be completely redone for different shells
anyway. Are you thinking of plugin content? As in, Banshee
puts a page into the DH to advertise itself?

--
Shaun