Different menu layouts in different distros / default desktop configurations

[Jim Campbell <jwcampbell gmail com>]

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.

Please note that I'm primarily considering this with regards to the desktop help, but I do see it as being valuable to application-specific help, too.

What do you all think?  

Jim