Re: Automatic Menu Substitution In Gnome Help Documentation

[danilo gnome org (Danilo Šegan)]

Hi Matt,

On Monday at 16:36, Matt Keenan wrote:

> I did some more trawling around to see how the likes of
> gnome-doc-utils is used by gnome components at build
> time. I have to say it's way cool how xml2po is used to generate the
> various language xml files at build time.

Mostly due to Shaun's auto-foo skills :)

> So got me thinking that maybe this is really where I should be doing
> the menu substitution instead of attempting
> to do it on the fly with yelp at run time (won't affect performance
> this way).

Sure, but the result would have a lower score on the über-cool scale
(i.e. imagine reading an untranslated manual, yet having the menu
items listed as you see them on your screen :).

> Steps would be :
>
>  - Determine menu location : using something like gnome-menu-spec-test
>  - Rename all help/C/*.xml files to help/C/*.xml.in, and add in new
>    "menupath" tags.

Actually, it might be simpler to do the replacing in xml2po docbook
mode (basically, that's where there is currently a crude hack to try
to add translators credits and to get messages for images and such).
Basically, you have entire XML tree there on your disposal (look how I
try to find articleinfo section to add <copyright> for translators).

postProcessXmlTranslation() is what you need to extend for this.  If
you need help, feel free to let me know :)

OTOH, if we do it this way, it might be even easier to extend xml2po
to have <guimenu>s, <guibutton>s etc. automatically translated using a
PO or MO file with their app translation (which would have the same
effect, but it still wouldn't be that cool :), or at least put those
translations as comments for translators.

Any other approach (the one you are suggesting) is much more
complicated:  instead of dealing only with simple XML, xml2po would
have to handle semi-translated XML as well where some snippets would
stay as they are and some would need to be extracted.  And xml2po
already has quite some knowledge about what's it doing regarding
languages, so it's probably best to put such handling there.

> - Amend utility gnome-menu-spec-test, delivered by gnome-menus to
>   output complete menu line.
>   At the moment it only outputs the lower level menu structure, a very
>   quick change would
>   output the complete menu structure (patch attached). This utility
>   uses libmenu in the exact same manner
>   as gnome-panel does to determine menu location for applications.

We might still want to make use of this part in xml2po: simply having
menupath's replaced in postProcessXmlTranslation() is by far the
simplest thing to do (at least IMHO).

What do you think of this approach instead?

Basically, the only difference is that I'd replace your:

> - Actual conversion from xml.in -> xml. This is the part I have yet to
>   decide upon. I could
>   - Simply write a script similar to xml2po that would just substitute
>     the menu in the menu locations
>    e.g. Changing :
>
>         <gnome:menupath for="gedit">
>          To
>         <term> <guimenu>Applications</guimenu></term>
>          <listitem>
>          <para>Choose <menuchoice>
>                  <guisubmenu>Accessories</guisubmenu>
>                  <guimenuitem>Text
>                  Editor. </guimenuitem></menuchoice></para>
>          </listitem>

with "let xml2po DocBook mode do that for us" (or create
docbook-extended mode extending on docbook mode :).

> The cool thing about this solution is there is no requirement for some
> master data file containing menu locations for applications.
> Each package just needs to ensure the gnome-menus and gnome-doc-utils
> are installed, and then the menu location
> can be determined directly from the .desktop file about to be
> installed from this component.

Sure, it's probably the better way ahead.  The only thing that bothers
me is handling of translated menu paths: gnome-menu-spec-test doesn't
seem to set the locale correctly, since it outputs "????" instead of
Cyrillic translations for me. ;)

Cheers,
Danilo