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.