Ubuntu Documentation

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

  1. html-multiple-locale-output
  2. Merge into precise
Proposed by David Planella
Status: Merged
Merged at revision: 109
Proposed branch: lp:~dpm/ubuntu-docs/html-multiple-locale-output
Merge into: lp:ubuntu-docs/precise
Diff against target: 190 lines (+64/-99)
3 files modified
html/Makefile (+64/-21)
html/add-html5-doctype.sh (+0/-24)
html/fix-urls.sh (+0/-54)
To merge this branch: bzr merge lp:~dpm/ubuntu-docs/html-multiple-locale-output
Reviewer Review Type Date Requested Status
Matthew East (community) Needs Information
Review via email: mp+99495@code.launchpad.net

Description of the change

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.

To post a comment you must log in.
lp:~dpm/ubuntu-docs/html-multiple-locale-output updated
99. By David Planella

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

100. By David Planella

Finished the install rule in the HTML makefile

101. By David Planella

Merged from trunk

Revision history for this message
Matthew East (mdke) wrote :

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
Revision history for this message
David Planella (dpm) wrote :

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.

Revision history for this message
Matthew East (mdke) wrote :

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

Revision history for this message
David Planella (dpm) wrote :

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

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'html/Makefile'
2--- html/Makefile 2011-08-26 10:41:59 +0000
3+++ html/Makefile 2012-03-28 06:39:18 +0000
4@@ -20,34 +20,77 @@
5 ####################################################################################
6
7 MAKECMD=make
8-
9-# Language code for documents
10-# Ex. LN=ja for japanese
11-LN=C
12+HTMLDESTDIR=build
13+SRCDIR=../ubuntu-help
14+SED=/bin/sed
15+INSTALLDIR=/var/www/
16+
17+# Space-separated list of language codes for documents. HTML will only be
18+# built for those codes in the list
19+# Ex. HELP_LINGUAS=ja it for Japanese and Italian
20+# Note that the corresponding .page files for the locales must have been built
21+# for the HTML to be built in turn. This means all the locales for which
22+# HTML output is needed will have to have been specified in the main
23+# HELP_LINGUAS variable in the ubuntu-help Makefile
24+HELP_LINGUAS=
25+
26+index_file_exists = $(wildcard $(SRCDIR)/$(lingua)/index.page)
27+linguas := $(HELP_LINGUAS)
28+help_linguas := \
29+ $(foreach lingua, $(linguas), \
30+ $(if $(index_file_exists), \
31+ $(lingua), \
32+ $(warning Cannot find source index page for locale: $(lingua), \
33+ skipping. You will probably have to build it adding it to \
34+ the HELP_LINGUAS variable in the Makefile at $(SRCDIR) \
35+ and rebuild)))
36
37 # Ubuntu Mallard Customization Layer
38-
39 UBUNTUXSL=ubuntu.xsl
40
41+# Builds the HTML files for all specified language codes, specifiying the
42+# language in the final documents and performing some other necessary
43+# text replacements not handled by yelp-build.
44+# Language codes are normalized to IETF format, as opposed to glibc format
45 ubuntu-help: clean style
46-
47- yelp-build html -o build -x $(UBUNTUXSL) ../ubuntu-help/$(LN)/
48-# add html5 doctype header to html files
49-# this can be removed once yelp-build does this for us
50- ./add-html5-doctype.sh
51- ./fix-urls.sh
52- # Workaround for a bug in yelp-build
53- rm -rf build/usr
54+ for lc in C $(help_linguas); do \
55+ lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
56+ if test "$$lang" = "C"; then lang=en-US; fi; \
57+ yelp-build html -o "$(HTMLDESTDIR)/$$lang/" -x $(UBUNTUXSL) \
58+ "$(SRCDIR)/$$lc/"; \
59+ $(SED) -i \
60+ -e '1s/^/<!DOCTYPE html\>\n/' \
61+ -e "s/<html>/<html lang="$$lang">/" \
62+ -e 's|/usr/share/icons/.*/\(.*\.svg\)|img/\1|'\
63+ "$(HTMLDESTDIR)/$$lang/"*.html; \
64+ rm -rf "$(HTMLDESTDIR)/$$lang/usr"; \
65+ done
66
67 clean:
68 rm -rf build
69
70+# Copy style sheet and common images to build directory
71+# TODO: copy C/figures to destination only for those cases where there are
72+# no localized figures
73 style:
74-
75- # copy style sheet and common images to build directory
76- mkdir -p build/img
77- mkdir -p build/figures
78- cp img/* build/img/
79-# figures are always in /C/ at this time
80- cp ../ubuntu-help/C/figures/* build/figures/
81-
82+ for lc in C $(help_linguas); do \
83+ lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
84+ if test "$$lang" = "C"; then lang=en-US; fi; \
85+ mkdir -p "$(HTMLDESTDIR)/$$lang/img"; \
86+ mkdir -p "$(HTMLDESTDIR)/$$lang/figures"; \
87+ cp img/* "$(HTMLDESTDIR)/$$lang/img"; \
88+ cp "$(SRCDIR)/C/figures/"* "$(HTMLDESTDIR)/$$lang/figures"; \
89+ done
90+
91+# Installs all HTML files to a multilingual site (e.g. run with Apache and
92+# MultiViews enabled)
93+install:
94+ rm -Rf "$(INSTALLDIR)"/*; \
95+ cp -R "$(HTMLDESTDIR)/"* "$(INSTALLDIR)"; \
96+ for lc in C $(help_linguas); do \
97+ lang=`echo $$lc | $(SED) -e 's/[@_]/-/'`; \
98+ if test "$$lang" = "C"; then lang=en-US; fi; \
99+ find "$(INSTALLDIR)/$$lang" -type f -exec mv {} {}.$$lang \; ; \
100+ cp -af "$(INSTALLDIR)/$$lang"/* "$(INSTALLDIR)"; \
101+ rm -Rf "$(INSTALLDIR)/$$lang" ; \
102+ done
103
104=== removed file 'html/add-html5-doctype.sh'
105--- html/add-html5-doctype.sh 2011-05-11 01:00:39 +0000
106+++ html/add-html5-doctype.sh 1970-01-01 00:00:00 +0000
107@@ -1,24 +0,0 @@
108-####################################################################################
109-# Copyright (C) 2005-2011 Ubuntu Documentation Project (ubuntu-doc@lists.ubuntu.com)
110-# This program is free software; you can redistribute it and/or modify
111-# it under the terms of the GNU General Public License as published by
112-# the Free Software Foundation; either version 2 of the License, or
113-# (at your option) any later version.
114-#
115-# This program is distributed in the hope that it will be useful,
116-# but WITHOUT ANY WARRANTY; without even the implied warranty of
117-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
118-# GNU General Public License for more details.
119-#
120-# You should have received a copy of the GNU General Public License
121-# along with this program; if not, write to the Free Software
122-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
123-# On Debian based systems a copy of the GPL can be found
124-# at /usr/share/common-licenses/GPL
125-####################################################################################
126-
127-# This script will add the HTML5 doctype header to all html files in build/
128-
129-sed -i build/*.html -e '1i\
130-\<!DOCTYPE html\>'
131-
132
133=== removed file 'html/fix-urls.sh'
134--- html/fix-urls.sh 2012-03-18 02:51:06 +0000
135+++ html/fix-urls.sh 1970-01-01 00:00:00 +0000
136@@ -1,54 +0,0 @@
137-####################################################################################
138-# Copyright (C) 2005-2006 Ubuntu Documentation Project (ubuntu-doc@lists.ubuntu.com)
139-# This program is free software; you can redistribute it and/or modify
140-# it under the terms of the GNU General Public License as published by
141-# the Free Software Foundation; either version 2 of the License, or
142-# (at your option) any later version.
143-#
144-# This program is distributed in the hope that it will be useful,
145-# but WITHOUT ANY WARRANTY; without even the implied warranty of
146-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
147-# GNU General Public License for more details.
148-#
149-# You should have received a copy of the GNU General Public License
150-# along with this program; if not, write to the Free Software
151-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
152-# On Debian based systems a copy of the GPL can be found
153-# at /usr/share/common-licenses/GPL
154-####################################################################################
155-
156-## ghelp links
157-
158- sed -i build/*.html -e "s#ghelp:brasero#http://library\.gnome\.org/users/brasero/2\.32/#g"
159- sed -i build/*.html -e "s#ghelp:cheese#http://library\.gnome\.org/users/cheese/2\.32/#g"
160- sed -i build/*.html -e "s#ghelp:empathy#http://library\.gnome\.org/users/empathy/2\.32/#g"
161- sed -i build/*.html -e "s#ghelp:evolution?usage-calendar#http://library\.gnome\.org/users/evolution/stable/usage-calendar\.html#g"
162- sed -i build/*.html -e "s#ghelp:gucharmap#http://library\.gnome\.org/users/gucharmap/2\.32/#g"
163- sed -i build/*.html -e "s#ghelp:orca#http://library\.gnome\.org/users/orca/3\.0/#g"
164- sed -i build/*.html -e "s#ghelp:synaptic#https://help\.ubuntu\.com/community/SynapticHowto#g"
165- sed -i build/*.html -e "s#ghelp:software-center#https://help\.ubuntu\.com/11\.04/software-center/C/index\.html#g"
166- 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"
167- sed -i build/*.html -e "s#ghelp:language-selector#https://help\.ubuntu\.com/11\.04/language-selector/C/index\.html#g"
168-
169-## Icons
170-
171- sed -i build/*.html -e "s#/usr/share/icons/gnome/apps/22/preferences-desktop-accessibility\.svg#img/preferences-desktop-accessibility\.svg#g"
172- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/bluetooth-active\.svg#img/bluetooth-active\.svg#g"
173- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/bluetooth-active\.svg#img/bluetooth-active\.svg#g"
174- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/battery-100\.svg#img/battery-100\.svg#g"
175- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/network-offline\.svg#img/network-offline\.svg#g"
176- 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"
177- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/indicator-messages\.svg#img/indicator-messages\.svg#g"
178- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/24/user-offline-panel\.svg#img/user-offline-panel\.svg#g"
179- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/actions/24/system-shutdown-panel\.svg#img/system-shutdown-panel\.svg#g"
180- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/stock/22/stock_person-panel\.svg#img/stock_person-panel\.svg#g"
181- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/22/system-devices-panel\.svg#img/system-devices-panel\.svg#g"
182- sed -i build/*.html -e "s#/usr/share/icons/ubuntu-mono-light/status/22/input-keyboard-symbolic\.svg#img/input-keyboard-symbolic\.svg#g"
183-
184-/usr/share/icons/ubuntu-mono-light/status/22/input-keyboard.svg
185-
186-## Search for unfixed ghelp links
187-echo "\nSearching for unfixed ghelp links:"
188-grep -r "href=\"ghelp:" build/
189-
190-exit 0

Subscribers

People subscribed via source and target branches