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

[Jim Campbell <jwcampbell gmail com>]

On Wed, May 12, 2010 at 9:41 AM, Shaun McCance <shaunm gnome org> wrote:

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?

I was thinking of a global entity file for the desktop help (i.e. the Gnome system docs), not for application help (i.e., Banshee docs). 
The reason for this is the discrepancy between instructions for the legacy Gnome panel layout the the Gnome Shell layout.
 

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.

I would think that the translators would need to translate the text located in the entity files, but I would still think that this approach provides greater flexibility to downstream teams.  For example, Ubuntu places the Gnome-Terminal under Accessories.  With Fedora, it's with the system tools.  There may be other ways that they place things in different spots (particularly with Ubuntu's Me Menu work).  Using entities gives them the power to update these click-paths in one spot and have them correctly reflected throughout the documentation.
 

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.

I don't think it's a huge problem, but I also don't think it would be difficult to implement this approach.  As for completely redoing the DH for the different shells, I am not sure that is necessary.  I think the Gnome tools are the same regardless of the shell/panel layout... it's just that the gnome tools in different spots (and you access them differently) using the different shell/panel features.
 

Are you thinking of plugin content? As in, Banshee
puts a page into the DH to advertise itself?

I was primarily thinking of using them in the context of something like this:

"To modify keyboard settings, access the keyboard settings manager by selecting System > Keyboard Preferences, > Keyboard Layout."  (Yes, I made that up - that actual click-path most likely 
doesn't exist.)

In this fictional example, though, the entity would be used in place of the "System > Keyboard Preferences > Keyboard Layout," text.  Thus, the actual doc-text (pre-translation and pre-processing) would look like, ". . . access the keyboard settings manager by selecting &keyboard-prefs;."  (or &keyboard-prefs-menu;)

Without the entity, downstreams would either have to ship a different set of DH for either Gnome-shell or the legacy panel layout, or they would have to modify the click-paths throughout the documentation by hand (or via script).

Using the entity, if a distro shipped the legacy panel layout by default, they would only need to modify the click paths contained in the one global entity file to reflect the legacy click-paths.

Jim