Re: Automatic Menu Substitution In Gnome Help Documentation

From: Matt Keenan <Matt Keenan Sun COM>
To: Danilo Šegan <danilo gnome org>
Cc: gnome-doc-devel-list gnome org
Subject: Re: Automatic Menu Substitution In Gnome Help Documentation
Date: Mon, 20 Feb 2006 15:36:43 +0000


Danilo,

Progress so far and issues....

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

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


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.- Process these at build time before xml2po is run to generate *.xml.how to do thisis the issue, should I just convert them directly using somethinglike xml2po or can an xsltstylesheet be used to just replace the one tag with a menu structureand output the restas xml, I don't think I can use xsltproc for this as it outputs html,or am I wrong.. ?- Once converted at this point xml2po converts the newly generated .xmlfile to translate

  it into the various language specific files.


What needs to be done to achieve above :

- Amend gnome-doc-utils.make, that is included in all help/Makefile.amfiles, so that the conversionis performed in a standard manner for all components. I've attached aquich hack/patch for this.- Amend utility gnome-menu-spec-test, delivered by gnome-menus to outputcomplete menu line.At the moment it only outputs the lower level menu structure, a veryquick change wouldoutput the complete menu structure (patch attached). This utility useslibmenu in the exact same manner

 as gnome-panel does to determine menu location for applications.

- Add to help/Makefile.am for all components the following new variableDOC_DESKTOP_LOCATION.

  e.g. for gedit :

      DOC_DESKTOP_LOCATION=../data/gedit.desktop

Write a new little script e.g. get-menu-location (see attached...very quickly hacked together :) ). Thisscript takes above variable and determines the menu location. It usesthe new gnome-menu-spec-test

  to determine this.

- Actual conversion from xml.in -> xml. This is the part I have yet todecide upon. I could- Simply write a script similar to xml2po that would just substitutethe 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>

- Or write a new xslt stylesheet component, can can do this for me ?how would I invoke this ?e..g I have the menu location in a file called menu-location.in, Iknow xslt can read data from other filesusing unparsed-text() and tokenize(). But how is the xsltdone, can I use the likes of xsltproc ?

The cool thing about this solution is there is no requirement for somemaster data file containing menu locations for applications.Each package just needs to ensure the gnome-menus and gnome-doc-utilsare installed, and then the menu locationcan be determined directly from the .desktop file about to be installedfrom this component.



Am I going down the right path here ?

Thanks

Matt

Danilo Šegan wrote:

Hi Matt,

Yesterday at 14:43, Matt Keenan wrote:

So let me try and scope out the work required, let me know if I am incorrect... ?

   1 - Define what xml to be placed into help dtd's  e.g. gcalctool.xml

   2 - Write new xslt stylesheet for processing the new xml, place into
       g-d-u xslt/docbook/utils ?, this could also then be used for static
       conversion aswell.

   3 - Would xml2po need changing aswell ?

I know what I've stated is very simplistic, but does it make sense ?


Yeah, that's exactly what I had in mind.  Note that we'd still have to
have some command-line stuff to update a mapping of menus->XSLT, since
I think we can't look through .desktop files in XSL.

I'd also like to hear Shaun's opinion on this, since he's still the
primary author of g-d-u stylesheets and Yelp ;)

xml2po would need no changing so far (I am bad, less work for me! :)

Cheers,
Danilo

--- gnome-doc-utils.make	2006-02-16 16:09:00.206996000 +0000
+++ gnome-doc-utils.make.new	2006-02-20 14:39:43.607047000 +0000
@@ -128,6 +128,7 @@
 _chunks  ?= `$(PKG_CONFIG) --variable xmldir gnome-doc-utils`/gnome/xslt/docbook/utils/chunks.xsl
 _credits ?= `$(PKG_CONFIG) --variable xmldir gnome-doc-utils`/gnome/xslt/docbook/utils/credits.xsl
 _ids ?= `$(PKG_CONFIG) --variable xmldir gnome-doc-utils`/gnome/xslt/docbook/utils/ids.xsl
+_menusub ?= `$(PKG_CONFIG) --variable menusub gnome-doc-utils`
 
 _sklocalstatedir ?= `scrollkeeper-config --pkglocalstatedir`
 
@@ -342,10 +343,18 @@
 ## The top-level documentation file in the C locale
 _DOC_C_MODULE = $(if $(DOC_MODULE),C/$(DOC_MODULE).xml)
 
+## @ _DOC_C_MODULE_IN
+## The top-level input documentation file in the C locale
+_DOC_C_MODULE_IN = $(if $(DOC_MODULE),C/$(DOC_MODULE).xml.in)
+
 ## @ _DOC_C_ENTITIES
 ## Files included with a SYSTEM entity in the C locale
 _DOC_C_ENTITIES = $(foreach ent,$(DOC_ENTITIES),C/$(ent))
 
+## @ _DOC_C_ENTITIES_IN
+## Input Files included with a SYSTEM entity in the C locale
+_DOC_C_ENTITIES_IN = $(foreach ent,$(DOC_ENTITIES),C/$(ent).in)
+
 ## @ _DOC_C_XINCLUDES
 ## Files included with XInclude in the C locale
 _DOC_C_INCLUDES = $(foreach inc,$(DOC_INCLUDES),C/$(inc))
@@ -357,6 +366,16 @@
 	$(_RNGDOC_C_DOCS)	$(_XSLDOC_C_DOCS)			\
 	$(_DOC_C_MODULE)
 
+## @ _DOC_C_DOCS_IN
+## All documentation files in the C locale
+_DOC_C_DOCS_IN =								\
+	$(_DOC_C_ENTITIES_IN)	$(_DOC_C_MODULE_IN)
+
+## @ _DOC_C_DOCS_XML
+## All xml documentation files in the C locale
+_DOC_C_DOCS_XML =								\
+	$(_DOC_C_ENTITIES)	$(_DOC_C_MODULE)
+
 ## @ _DOC_C_DOCS_NOENT
 ## All documentation files in the C locale,
 ## except files included with a SYSTEM entity
@@ -434,7 +453,7 @@
 	$(foreach fig,$(_DOC_C_FIGURES), $(foreach lc,C $(DOC_LINGUAS),	\
 		$(wildcard $(srcdir)/$(lc)/$(patsubst C/%,%,$(fig))) ))
 
-$(_DOC_POFILES):
+$(_DOC_POFILES): $(_DOC_C_DOCS)
 	@if ! test -d $(dir $@); then \
 	  echo "mkdir $(dir $@)"; \
 	  mkdir "$(dir $@)"; \
@@ -465,9 +484,22 @@
 	    $(_xml2po) -e -u $(notdir $@) $$docs); \
 	fi
 
+# Conversion of C/*.xml.in to C/*.xml Shouuld I be usig DOC_C_DOCS_XML
+# here instead of DOC_C_DOCS
+$(_DOC_C_DOCS) : $(_DOC_C_DOCS_IN)
+	if ! test -f C/menu-location.in; then \
+		get-menu-location $(DOC_DESKTOP_FILE) > C/menu-location.in
+	fi
+	# Process *.xml.in, converting to .xml, possibly using some new xslt stylesheet :
+	# e.g. xsltproc -o C/$(notdir $@) $(_menusub) C/$($notdir $@).in
+   	# OR just amend/rename get-menu-location script so that it does everything.
+	# Only cp'ing for now.. 
+	cp C/$(notdir $@).in C/$(notdir $@)
+	
 # FIXME: fix the dependancy
 # FIXME: hook xml2po up
 $(_DOC_LC_DOCS) : $(_DOC_POFILES)
+# Should DOC_C_DOCS_XML be used here instead of DOC_C_DOCS ?
 $(_DOC_LC_DOCS) : $(_DOC_C_DOCS)
 	if ! test -d $(dir $@); then mkdir $(dir $@); fi
 	case "$(srcdir)" in /*) sd="$(srcdir)";; *) sd="../$(srcdir)";;	esac; \
@@ -510,12 +542,13 @@
 endif
 
 all:							\
+	$(_DOC_C_DOCS_IN)	\
 	$(_DOC_C_DOCS)		$(_DOC_LC_DOCS)		\
 	$(_DOC_OMF_ALL)		$(_DOC_DSK_ALL)		\
 	$(_DOC_HTML_ALL)	$(_DOC_POFILES)
 
 
-.PHONY: clean-doc-rngdoc clean-doc-xsldoc clean-doc-omf clean-doc-dsk clean-doc-lc clean-doc-dir
+.PHONY: clean-doc-rngdoc clean-doc-xsldoc clean-doc-omf clean-doc-dsk clean-doc-lc clean-doc-dir clean-doc-xml
 
 clean-doc-rngdoc: ; rm -f $(_RNGDOC_C_DOCS) $(_RNGDOC_LC_DOCS)
 clean-doc-xsldoc: ; rm -f $(_XSLDOC_C_DOCS) $(_XSLDOC_LC_DOCS)
@@ -535,6 +568,8 @@
 	    rm -f "$$lc/.xml2po.mo"; \
 	  fi; \
 	done
+clean-doc-xml:
+	rm -f $(_DOC_C_DOCS_XML)
 clean-doc-dir:
 	@for lc in C $(DOC_LINGUAS); do \
 	  for dir in `find $$lc -depth -type d`; do \
@@ -550,25 +585,29 @@
 _clean_omf = $(if $(_DOC_OMF_IN),clean-doc-omf)
 _clean_dsk = $(if $(_DOC_DSK_IN),clean-doc-dsk)
 _clean_lc  = $(if $(DOC_LINGUAS),clean-doc-lc)
+_clean_xml = $(if $(DOC_MODULE),clean-doc-xml)
 _clean_dir = $(if $(DOC_MODULE),clean-doc-dir)
 
 clean-local:						\
 	$(_clean_rngdoc)	$(_clean_xsldoc)	\
 	$(_clean_omf)		$(_clean_dsk)		\
-	$(_clean_lc)		$(_clean_dir)
+	$(_clean_lc)		$(_clean_xml)		\
+	$(_clean_dir)
 distclean-local:					\
 	$(_clean_rngdoc)	$(_clean_xsldoc)	\
 	$(_clean_omf)		$(_clean_dsk)		\
-	$(_clean_lc)		$(_clean_dir)
+	$(_clean_lc)		$(_clean_xml)		\
+	$(_clean_dir)
 mostlyclean-local:					\
 	$(_clean_rngdoc)	$(_clean_xsldoc)	\
 	$(_clean_omf)		$(_clean_dsk)		\
-	$(_clean_lc)		$(_clean_dir)
+	$(_clean_lc)		$(_clean_xml)		\
+	$(_clean_dir)
 maintainer-clean-local:					\
 	$(_clean_rngdoc)	$(_clean_xsldoc)	\
 	$(_clean_omf)		$(_clean_dsk)		\
-	$(_clean_lc)		$(_clean_dir)
-
+	$(_clean_lc)		$(_clean_xml)		\
+	$(_clean_dir)
 
 .PHONY: dist-doc-docs dist-doc-figs dist-doc-omf dist-doc-dsk
 doc-dist-hook: 					\

--- gnome-doc-utils.pc.in	2006-02-20 14:43:00.186121000 +0000
+++ gnome-doc-utils.pc.in.new	2006-02-20 14:40:21.511167000 +0000
@@ -8,6 +8,7 @@
 db2omf=${xsltdir}/docbook/omf/db2omf.xsl
 rngdoc=${xsltdir}/rngdoc/rngdoc.xsl
 xsldoc=${xsltdir}/xsldoc/xsldoc.xsl
+menusub${xsltdir}/docbook/utils/menusub.xsl
 
 Name: gnome-doc-utils
 Description: GNOME Documentation Utilities

--- test-menu-spec.c	2006-02-20 14:46:26.371990000 +0000
+++ test-menu-spec.c.new	2006-02-16 15:30:31.010203000 +0000
@@ -48,6 +48,7 @@
 
   if (!parent)
     {
+      g_string_append_c (path, '/');
       g_string_append (path, gmenu_tree_directory_get_name(directory));
       g_string_append_c (path, '/');
       return;
@@ -88,8 +89,8 @@
   utf8_file_id = g_filename_to_utf8 (gmenu_tree_entry_get_desktop_file_id (entry),
 				     -1, NULL, NULL, NULL);
 
-  g_print ("%s\t%s\t%s%s\n",
-	   path,
+  g_print ("%s%s\t%s\t%s%s\n",
+	   path, gmenu_tree_entry_get_name(entry),
 	   utf8_file_id ? utf8_file_id : _("Invalid desktop file ID"),
 	   utf8_path ? utf8_path : _("[Invalid Filename]"),
 	   gmenu_tree_entry_get_is_excluded (entry) ? _(" <excluded>") : "");

#! /bin/bash
# Assumes gnome-menu-spec-test is on your PATH

if [ $# != 2 ]; then
	echo "Must supply desktop file to look for and output file."
	echo "e.g.    get-menu-location gedit.desktop C/menu-location.in"
	exit 1
fi

# Place desktop file into redefined XDG_DATA_DIR path so that it
# is picked up first.

export XDG_DATA_DIRS=/tmp

if ! test -d /tmp/applications ; then
	mkdir /tmp/applications
fi

cp -f $1 /tmp/applications

desktop_file=`basename $1` 

# Attempt default applications.menu first so run gnome-menu-spec-test without any
# Paramaters
gnome-menu-spec-test | grep $desktop_file | awk 'BEGIN {FS="	";}{print $1}' > /tmp/$$.menu

if [ -s /tmp/$$.menu ]; then
	# Presuming we found something, make sure we only have one line, use the first occurence
	head -1 /tmp/$$.menu > $2
else
	# Nothing found, so either not on menu or simply not in the default applications menu.
	# Chances attempt to process other menu files in $XDG_CONFIG_DIRS/menus/*
	
	# Check if XDG_CONFIG_DIRS is set, if not set to default of /etc/xdg
	if test "${XDG_CONFIG_DIRS+set}" = "set"; then
		export XDG_CONFIG_DIRS=/etc/xdg
	fi
	
	for i in /etc/xdg/menus/*.menu; do
		# List of menu files to process could be definable somewhere in gnome-menus ?
		# Already tried applications.menu so skip it.
		
		
		if ! test "`basename $i`" = "applications.menu"; then
			# Process this menu
			gnome-menu-spec-test --file $i | grep $desktop_file | awk 'BEGIN {FS="	";}{print $1}' > /tmp/$$.menu

			if [ -s /tmp/$$.menu ]; then
				# Presuming we found something, make sure we only have one line, use the first occurence
				head -1 /tmp/$$.menu > $2
				break
			fi
		fi
	done
fi

# Clean up tmp stuff
rm -rf /tmp/applications /tmp/$$.menu

--- gedit.xml.in	2006-02-20 15:27:36.964122000 +0000
+++ gedit.xml	2006-02-20 13:48:07.143153000 +0000
@@ -204,7 +204,10 @@
 		<para>You can start <application>&app;</application> in the following ways:</para>
 		<variablelist>
     		<varlistentry>
-    		<gnome:menupath for="gedit">
+    		<term><guimenu>Applications</guimenu> menu</term>
+    		<listitem>
+    		<para>Choose <menuchoice><guisubmenu>Accessories</guisubmenu><guimenuitem>Text Editor</guimenuitem></menuchoice>. </para>
+    		</listitem>
     		</varlistentry>
     		<varlistentry>
     		<term>Command line</term>

Follow-Ups:
- Re: Automatic Menu Substitution In Gnome Help Documentation
  - From: Danilo Šegan

References:
- Re: Automatic Menu Substitution In Gnome Help Documentation
  - From: Matt Keenan
- Re: Automatic Menu Substitution In Gnome Help Documentation
  - From: Danilo Šegan

[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]