Merge lp:~dpm/ubuntu-docs/html-multiple-locale-output into lp:ubuntu-docs/precise

[David Planella]

Background
----------

The current tree provides a makefile to create localized HTML documentation for a given language.

While this is extremely useful to provide online documentation, only one locale can be specified at a time.

To provide output to help the translations and multilingual user communities, it would be useful to create HTML documentation for all languages in which there is a translation available, in a centralized manner.

Note that the HTML build is not part of the binary output of the ubuntu-docs package, and my understanding is that it is provided as a helper to create HTML documentation for help.ubuntu.com.

Proposed change
---------------

This branch modifies the HTML makefile to enable building HTML documentation for all available locales. The list of localized docs to build can be specified as a list of language codes in the HELP_LINGUAS variable (following the main documentation makefile), either in the Makefile itself or on the command line when executing make.

It has been tested to produce a proof-of-concept multilingual site to help localizers test their translations on:

http://91.189.93.101/

The site serves the pages in the right locale according to the browser's language settings and falls back to English if no language preference is provided.

[lp:~dpm/ubuntu-docs/html-multiple-locale-output]

99. By David Planella on 2012-03-27

Added a rule to the html Makefile to install HTML files on a multilingual server

100. By David Planella on 2012-03-28

Finished the install rule in the HTML makefile

101. By David Planella on 2012-03-28

Merged from trunk

[Matthew East (mdke)]

Just a query - I may be looking at this too quickly but I can't see why the fix-urls.sh script has been removed?

review: Needs Information

[David Planella (dpm)]

I included the ## Icons part of the fix-urls.sh script in the ubuntu-help rule, in:

-e 's|/usr/share/icons/.*/\(.*\.svg\)|img/\1|'\

As per the ## ghelp part of the script, I had done a quick search for ghelp: links in the HTML output at the time I wrote the rule and I couldn't find any, so I thought it wouldn't be needed and discarded it.

Double-checking it now makes me think I was perhaps a bit too quick, as the output seems to contain ghelp links for the following:

orca
synaptic
cheese
baobab
brasero
gucharmap

I guess I should re-add the fix-urls.sh script to cater for those. Does it look like the final list? It strikes me that e.g. the software-center, language-selector and empathy links from the original are gone.

[Matthew East (mdke)]

On 28 March 2012 19:04, David Planella <email address hidden> wrote:
> Double-checking it now makes me think I was perhaps a bit too quick, as the output seems to contain ghelp links for the following:
>
> orca
> synaptic
> cheese
> baobab
> brasero
> gucharmap
>
> I guess I should re-add the fix-urls.sh script to cater for those. Does it look like the final list? It strikes me that e.g. the software-center, language-selector and empathy links from the original are gone.

Yes please. I don't know whether this is the final list - we tend to
update the script once per release cycle, prior to html generation.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

[David Planella (dpm)]

Submitted now as https://code.launchpad.net/~dpm/ubuntu-docs/html-fix-urls/+merge/99844

=== modified file 'html/Makefile'
--- html/Makefile	2011-08-26 10:41:59 +0000
+++ html/Makefile	2012-03-28 06:39:18 +0000
@@ -20,34 +20,77 @@
 ####################################################################################
 
 MAKECMD=make
-
-# Language code for documents
-# Ex. LN=ja for japanese
-LN=C
+HTMLDESTDIR=build
+SRCDIR=../ubuntu-help
+SED=/bin/sed
+INSTALLDIR=/var/www/
+
+# Space-separated list of language codes for documents. HTML will only be
+# built for those codes in the list
+# Ex. HELP_LINGUAS=ja it for Japanese and Italian
+# Note that the corresponding .page files for the locales must have been built
+# for the HTML to be built in turn. This means all the locales for which
+# HTML output is needed will have to have been specified in the main
+# HELP_LINGUAS variable in the ubuntu-help Makefile
+HELP_LINGUAS=
+
+index_file_exists = $(wildcard $(SRCDIR)/$(lingua)/index.page)
+linguas := $(HELP_LINGUAS)
+help_linguas := \
+    $(foreach lingua, $(linguas), \
+        $(if $(index_file_exists), \
+            $(lingua), \
+            $(warning Cannot find source index page for locale: $(lingua), \
+                skipping. You will probably have to build it adding it to \
+                the HELP_LINGUAS variable in the Makefile at $(SRCDIR) \
+                and rebuild)))
 
 # Ubuntu Mallard Customization Layer
-
 UBUNTUXSL=ubuntu.xsl
 
+# Builds the HTML files for all specified language codes, specifiying the
+# language in the final documents and performing some other necessary
+# text replacements not handled by yelp-build.
+# Language codes are normalized to IETF format, as opposed to glibc format
 ubuntu-help: clean style
-
-	yelp-build html -o build -x $(UBUNTUXSL) ../ubuntu-help/$(LN)/
-# add html5 doctype header to html files
-# this can be removed once yelp-build does this for us
-	./add-html5-doctype.sh
-	./fix-urls.sh
-	# Workaround for a bug in yelp-build
-	rm -rf build/usr
+	for lc in C $(help_linguas); do \
+		lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
+		if test "$$lang" = "C"; then lang=en-US; fi; \
+		yelp-build html -o "$(HTMLDESTDIR)/$$lang/" -x $(UBUNTUXSL) \
+			"$(SRCDIR)/$$lc/"; \
+		$(SED) -i \
+			-e '1s/^/<!DOCTYPE html\>\n/' \
+			-e "s/<html>/<html lang="$$lang">/" \
+			-e 's|/usr/share/icons/.*/\(.*\.svg\)|img/\1|'\
+			"$(HTMLDESTDIR)/$$lang/"*.html; \
+		rm -rf "$(HTMLDESTDIR)/$$lang/usr"; \
+	done
 
 clean:
 	rm -rf build
 
+# Copy style sheet and common images to build directory
+# TODO: copy C/figures to destination only for those cases where there are
+# no localized figures
 style:
-
-	# copy style sheet and common images to build directory
-	mkdir -p build/img
-	mkdir -p build/figures
-	cp img/* build/img/
-# figures are always in /C/ at this time
-	cp ../ubuntu-help/C/figures/* build/figures/
-
+	for lc in C $(help_linguas); do \
+		lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
+		if test "$$lang" = "C"; then lang=en-US; fi; \
+		mkdir -p "$(HTMLDESTDIR)/$$lang/img"; \
+		mkdir -p "$(HTMLDESTDIR)/$$lang/figures"; \
+		cp img/* "$(HTMLDESTDIR)/$$lang/img"; \
+		cp "$(SRCDIR)/C/figures/"* "$(HTMLDESTDIR)/$$lang/figures"; \
+	done
+
+# Installs all HTML files to a multilingual site (e.g. run with Apache and
+# MultiViews enabled)
+install:
+	rm -Rf "$(INSTALLDIR)"/*; \
+	cp -R "$(HTMLDESTDIR)/"* "$(INSTALLDIR)"; \
+	for lc in C $(help_linguas); do \
+		lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
+		if test "$$lang" = "C"; then lang=en-US; fi; \
+		find "$(INSTALLDIR)/$$lang" -type f -exec mv {} {}.$$lang \; ; \
+		cp -af "$(INSTALLDIR)/$$lang"/* "$(INSTALLDIR)"; \
+		rm -Rf "$(INSTALLDIR)/$$lang" ; \
+	done

=== removed file 'html/add-html5-doctype.sh'
--- html/add-html5-doctype.sh	2011-05-11 01:00:39 +0000
+++ html/add-html5-doctype.sh	1970-01-01 00:00:00 +0000
@@ -1,24 +0,0 @@
-####################################################################################           
-# Copyright (C) 2005-2011 Ubuntu Documentation Project ([e-mail])
-#    This program is free software; you can redistribute it and/or modify
-#    it under the terms of the GNU General Public License as published by
-#    the Free Software Foundation; either version 2 of the License, or
-#    (at your option) any later version. 
-#
-#    This program is distributed in the hope that it will be useful,
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#    GNU General Public License for more details.
-#
-#    You should have received a copy of the GNU General Public License
-#    along with this program; if not, write to the Free Software
-#    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#    On Debian based systems a copy of the GPL can be found 
-#    at /usr/share/common-licenses/GPL
-####################################################################################
-
-# This script will add the HTML5 doctype header to all html files in build/
-
-sed -i build/*.html -e '1i\
-\<!DOCTYPE html\>'
-

=== removed file 'html/fix-urls.sh'
--- html/fix-urls.sh	2012-03-18 02:51:06 +0000
+++ html/fix-urls.sh	1970-01-01 00:00:00 +0000
@@ -1,54 +0,0 @@
-####################################################################################           
-# Copyright (C) 2005-2006 Ubuntu Documentation Project ([e-mail])
-#    This program is free software; you can redistribute it and/or modify
-#    it under the terms of the GNU General Public License as published by
-#    the Free Software Foundation; either version 2 of the License, or
-#    (at your option) any later version. 
-#
-#    This program is distributed in the hope that it will be useful,
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#    GNU General Public License for more details.
-#
-#    You should have received a copy of the GNU General Public License
-#    along with this program; if not, write to the Free Software
-#    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#    On Debian based systems a copy of the GPL can be found 
-#    at /usr/share/common-licenses/GPL
-####################################################################################
-
-## ghelp links
-
- 	sed -i build/*.html -e "s#ghelp:brasero#http://library\.gnome\.org/users/brasero/2\.32/#g"
- 	sed -i build/*.html -e "s#ghelp:cheese#http://library\.gnome\.org/users/cheese/2\.32/#g"
- 	sed -i build/*.html -e "s#ghelp:empathy#http://library\.gnome\.org/users/empathy/2\.32/#g"
- 	sed -i build/*.html -e "s#ghelp:evolution?usage-calendar#http://library\.gnome\.org/users/evolution/stable/usage-calendar\.html#g"
- 	sed -i build/*.html -e "s#ghelp:gucharmap#http://library\.gnome\.org/users/gucharmap/2\.32/#g"
- 	sed -i build/*.html -e "s#ghelp:orca#http://library\.gnome\.org/users/orca/3\.0/#g"
- 	sed -i build/*.html -e "s#ghelp:synaptic#https://help\.ubuntu\.com/community/SynapticHowto#g"
- 	sed -i build/*.html -e "s#ghelp:software-center#https://help\.ubuntu\.com/11\.04/software-center/C/index\.html#g"
- 	sed -i build/*.html -e "s#ghelp:gnome-classic-index#https://help\.ubuntu\.com/11\.04/ubuntu-classic/gnome-classic-index/C/index\.html#g"
- 	sed -i build/*.html -e "s#ghelp:language-selector#https://help\.ubuntu\.com/11\.04/language-selector/C/index\.html#g"
-
-## Icons
-
- 	sed -i build/*.html -e "s#/usr/share/icons/gnome/apps/22/preferences-desktop-accessibility\.svg#img/preferences-desktop-accessibility\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/bluetooth-active\.svg#img/bluetooth-active\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/bluetooth-active\.svg#img/bluetooth-active\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/battery-100\.svg#img/battery-100\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/network-offline\.svg#img/network-offline\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/audio-volume-high-panel\.svg#img/audio-volume-high-panel\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/indicator-messages\.svg#img/indicator-messages\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/user-offline-panel\.svg#img/user-offline-panel\.svg#g"
- 	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/actions/24/system-shutdown-panel\.svg#img/system-shutdown-panel\.svg#g"
-	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/stock/22/stock_person-panel\.svg#img/stock_person-panel\.svg#g"
-	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/22/system-devices-panel\.svg#img/system-devices-panel\.svg#g"
-	sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/22/input-keyboard-symbolic\.svg#img/input-keyboard-symbolic\.svg#g"
-
-/usr/share/icons/ubuntu-mono-light/status/22/input-keyboard.svg
-
-## Search for unfixed ghelp links
-echo "\nSearching for unfixed ghelp links:"
-grep -r "href=\"ghelp:" build/
-
-exit 0