GNOME Bugzilla – Bug 336185
Docbook mode: Automatic Menu Substitution with xml2po
Last modified: 2020-03-03 18:35:21 UTC
In gnome documentation the menu locations of applications are hard coded into the C locale docbook xml help files. This poses a problem for many distro's who decide to position applications on different menus, in effect they end up having to branch their full documentation set in order for their users to have correct documentation. I would like to suggest a feature within xml2po which will in fact automatically substitute the menu location into the C locale help file, based on the contents of the .desktop file for that application. Menu locations can be determined using the .desktop file and the libmenu api (gnome-menus). There is thankfully a python extension for libmenu that allows access directly to the libmenu API. Using xml2po at build time the entire xml tree is available for manipulation, so by simply adding a new xml element to the xml documentation e.g. <menupath/> Then xml2po once amended and supplied a desktop file, can determine the menu location and substitute the above tag with the correct location. Changes required : 1. Amend help Makefile.am adding a new makefile variable : DOC_DESKTOP_LOCATION This will point to the exact location of the desktop file that is going to be used by this applicaiton e.g. for gedit this would be : DOC_DESKTOP_LOCATION=../data/gedit.desktop 2. Modify gnome-doc-utils/gnome-doc-utils.make so that it uses xml2po supplying it above named desktop file, and re-generates the C locale help files. 3. Modify gnome-doc-utils/xml2po/xmp2po.py to take new paramater "-d|--desktop-file desktop_file". 4. Modify gnome-doc-utils/xml2po/modes/docbook.py to have a new definition which will process the menu locaiton something similar to post process xml that already exists, however this new definition will utilize a new mode files "menulocation.py" which does the actual processing. 5. Write the new menulocaiton.py python source which actually use the libmenu python extension to determine the menu location. 4. Modify
Created attachment 62118 [details] menulocaton.py : menu location xml2po mode
Created attachment 62119 [details] get-menu-location.py : test gnome-menus extension Test python script, uses gnome-menus python extension to query menu locations.
Comment on attachment 62118 [details] menulocaton.py : menu location xml2po mode xml2po mode module to determine the menu location.
Created attachment 62120 [details] [review] xml2po.py.diff Changes to xml2po.py, new paramater --desktop-file and calling new def for menu location substitution.
Created attachment 62121 [details] [review] docbook.py.diff Mods to docbook.py to menu substitution
Created attachment 62122 [details] [review] gnome-doc-utils.make.diff Sample amendment to gnome-doc-utils.make
Created attachment 80609 [details] [review] Uptodate patch for gnome-doc-utils, obsoletes all other patches do date.
To see menu substition in action, as stated in first comment, e.g. for gedit : 1. Build/install gnome-doc-utils with most recent patch applied. 2. mv gedit/help/C/gedit.xml gedit/help/C/gedit.xml.in 3. Edit gedit.xml.in Replace : <varlistentry> <term><guimenu>Applications</guimenu> menu</term> <listitem> <para>Choose <menuchoice><guisubmenu>Accessories</guisubmenu><guimenuitem>Text Editor</guimenuitem></menuchoice>. </para> </listitem> </varlistentry> With: <varlistentry> <menupath/> </varlistentry> 4. Edit gedit/help/Makefile.am, adding the line : DOC_DESKTOP_LOCATION = ../data/gedit.desktop 5. Now build and install gedit, notice how <menupath/> was replaced with menu location that was determined from gedit.desktop. Just about there now. One final thing , Danilo you mentioned that before you would commit this I needed to ensure that tests passed, are these the test docs located under gnome-doc-utils/test/ ? if so what exactly do I need to do, to ensure these tests pass ?
Created attachment 80622 [details] menulocation.py : new xml2po mode Forgot to attach new menulocaiton.py new xml2po python mode module.
Created attachment 80641 [details] [review] auto-menu-subs.diff Update to docboks.py to include " menu" text.
Danilo, Any update on getting this accepted back into HEAD ? :) as gnome 2.19 is active now ? cheers Matt
Ping.. any chance of a patch review...
gnome-doc-utils has been superseded by yelp-xsl, yelp-tools, and itstool. gnome-doc-utils will not see any further development, hence closing as WONTFIX. See https://gitlab.gnome.org/Infrastructure/Infrastructure/issues/255