Merge lp:~krytarik/xubuntu-docs/patches into lp:xubuntu-docs/vivid

[Krytarik Raido]

- Normalize appearance of cross references both throughout the various languages, and towards other links
- Move startpage from 'about' directory to document root, and rename it to 'index.html'
- Add option to include revision on startpage, by passing the REVNO parameter
- Change main docs' directory from 'desktop-guide' to 'C', to be consistent with the translations
- Change main docs' link on startpage to a relative one
- Reduce duplication of 'documentation' on startpage as well, and fix a couple of other things too
- Improve reliability and efficiency of creating the translator credits
- Overhaul translation script as well
- Improve efficiency and modularity of the Makefiles
- Adapt appearance of translators reference in the main docs to both the other credits, and the translations
- Use different clauses heading the translator credits for the main docs and the translations

[Pasi Lallinaho (knome)]

See inline comment on code. Other than that, looks good to me.

review: Needs Information

[David Pires (slickymaster)]

review: Needs Information

[David Pires (slickymaster)]

Thanks for this krytarik.

Approved and merged.

review: Approve

=== modified file 'Makefile'
--- Makefile	2015-03-11 18:12:57 +0000
+++ Makefile	2015-03-28 16:37:06 +0000
@@ -1,16 +1,36 @@
 # Makefile for the Xubuntu Documentation
 # Ubuntu Documentation Project <[e-mail]>
 
+ifneq ($(REVNO),)
+    VERSION = 
+    VERSION += (Rev. $(REVNO))
+endif
+
+all: clean startpage html translate
+
+startpage: get-translations
+	mkdir -p build
+	cp      startpage/*.css \
+		startpage/*.png \
+		build/
+	sed "s@\(<a href=\"\).*\([^/]\+/index\.html\">Official Documentation</a>\)@\1\2$(VERSION)@" startpage/xubuntu-index-start.htx > build/index.html
+	for lang in $(TRANSLATIONS); do \
+	    	awk -v lang="$$lang" '$$1 == lang {print "\t\t\t<li><a href=\"" lang "/index.html\">" $$2 "</a></li>"; f=1; exit} END {exit !f}' desktop-guide/po/LINGUANAMES || \
+		awk -v lang="$$lang" '$$1 == "\"Language-Team:" {print "\t\t\t<li><a href=\"" lang "/index.html\">" $$2 "</a></li>"; exit}' desktop-guide/po/$$lang.po; \
+	done >> build/index.html
+	cat startpage/xubuntu-index-end.htx >> build/index.html
+
+get-translations:
 ifneq ($(wildcard desktop-guide/po/LINGUAS),)
-   $(shell cd desktop-guide && ../scripts/translate.sh -u >/dev/null)
-   TRANSLATIONS=$(shell cat desktop-guide/po/LINGUAS)
+	cd desktop-guide; \
+	../scripts/translate.sh -u
+    export TRANSLATIONS := $(shell cat desktop-guide/po/LINGUAS)
+    export TRANSOPTS = -g
 else
-   TRANSLATIONS=$(shell basename -s .po -a desktop-guide/po/*.po)
+    export TRANSLATIONS := $(shell basename -s .po -a desktop-guide/po/*.po)
 endif
 
-all: clean desktop-guide startpage translate
-
-desktop-guide:
+html:
 	make -C desktop-guide html
 
 epub:
@@ -19,17 +39,6 @@
 translate:
 	make -C desktop-guide translate
 
-startpage:
-	mkdir -p build/about/
-	cp startpage/*.css build/about/
-	cp startpage/*.png build/about/
-	cp startpage/xubuntu-index-start.htx build/about/xubuntu-index.html
-	for lang in $(TRANSLATIONS); do \
-	    	awk -v lang="$$lang" '$$1 == lang {print "\t\t\t<li><a href=\"../" lang "/index.html\">" $$2 "</a></li>"; f=1; exit} END {exit !f}' desktop-guide/po/LINGUANAMES || \
-		awk -v lang="$$lang" '$$1 == "\"Language-Team:" {print "\t\t\t<li><a href=\"../" lang "/index.html\">" $$2 "</a></li>"; exit}' desktop-guide/po/$$lang.po; \
-	done >> build/about/xubuntu-index.html
-	cat startpage/xubuntu-index-end.htx >> build/about/xubuntu-index.html
-
 test:
 	make -C desktop-guide test
 
@@ -41,4 +50,4 @@
 	make -C desktop-guide clean
 	rm -rf build
 
-.PHONY: desktop-guide startpage translate
+.PHONY: startpage

=== modified file 'desktop-guide/Makefile'
--- desktop-guide/Makefile	2015-02-14 23:34:03 +0000
+++ desktop-guide/Makefile	2015-03-28 16:37:06 +0000
@@ -3,60 +3,68 @@
 # Public domain
 
 # Xubuntu Docbook Customization Layer
-XUBUNTUXSL=libs/xubuntu-docbook-conf.xsl
-
-ifneq ($(wildcard po/LINGUAS),)
-   $(shell ../scripts/translate.sh -u >/dev/null)
-   OPTS=-g
-   TRANSLATIONS=$(shell cat po/LINGUAS)
-else
-   OPTS=
-   TRANSLATIONS=$(shell basename -s .po -a po/*po)
-endif
+XUBUNTUXSL = libs/xubuntu-docbook-conf.xsl
+
+# All available translations
+TRANSALL = $(shell basename -s .po -a po/*.po)
+
+all: clean html translate
 
 html: style
-	@echo "<para>Attributed on each language's page.</para>" > C/translators.xml
-	xsltproc --xinclude -o ../build/desktop-guide/index.html $(XUBUNTUXSL) C/index.xml
+	printf "<itemizedlist>\n\t<listitem><para>Attributed on each translation's page.</para></listitem>\n</itemizedlist>\n" > C/translators.xml
+	xsltproc --xinclude -o ../build/C/index.html $(XUBUNTUXSL) C/index.xml
+	sed -i 's@\(<p>The contributors to\) this translation of the \(documentation are:</p>\)@\1 the various translations of this \2@' ../build/C/credits-license.html
 
 epub: epubstyle
-	@echo "<para>Attributed on each language's page.</para>" > C/translators.xml
-	xsltproc --xinclude -o ../build/desktop-guide/ /usr/share/xml/docbook/stylesheet/nwalsh/epub3/chunk.xsl C/index.xml
-	cd ../build/desktop-guide/; \
-	zip -0Xq xubuntu-docs.epub mimetype;\
+	printf "<itemizedlist>\n\t<listitem><para>Attributed on each translation's page.</para></listitem>\n</itemizedlist>\n" > C/translators.xml
+	xsltproc --xinclude -o ../build/C/ /usr/share/xml/docbook/stylesheet/nwalsh/epub3/chunk.xsl C/index.xml
+	sed -i 's@\(<p>The contributors to\) this translation of the \(documentation are:</p>\)@\1 the various translations of this \2@' ../build/C/credits-license.html
+	cd ../build/C; \
+	zip -0Xq xubuntu-docs.epub mimetype; \
 	zip -Xr9Dq xubuntu-docs.epub *
 
 style:
 	mkdir -p ../build/libs
-	cp -r libs/*css ../build/libs
-	cp -r libs/images ../build/libs
-	cp -r libs/admon ../build/libs
-	cp -r libs/navig ../build/libs
+	cp -r   libs/*.css \
+		libs/images \
+		libs/admon \
+		libs/navig \
+		../build/libs/
 
 epubstyle:
-	mkdir -p ../build/desktop-guide/libs/images
-	cp -r   libs/images/preferences-desktop.png \
+	mkdir -p ../build/C/libs/images
+	cp      libs/images/preferences-desktop.png \
 		libs/images/system-lock-screen.png \
 		libs/images/system-log-out.png \
 		libs/images/location_icon.png \
 		libs/images/package_icon.png \
 		libs/images/menu_icon.png \
 		libs/images/key_icon.png \
-		../build/desktop-guide/libs/images/
+		../build/C/libs/images/
 
-translate:
-	../scripts/translate.sh $(OPTS); \
+translate: get-translations
+	../scripts/translate.sh $(TRANSOPTS)
+	../scripts/translators.sh $(TRANSOPTS)
 	for dir in $(TRANSLATIONS); do \
-		../scripts/translators.sh -l $$dir > $$dir/translators.xml ;\
-		xsltproc --xinclude -o ../build/$$dir/index.html $(XUBUNTUXSL) $$dir/index.xml ;\
+		xsltproc --xinclude -o ../build/$$dir/index.html $(XUBUNTUXSL) $$dir/index.xml; \
 	done
 
-test:
+test: get-translations
 	set -e; \
 	for dir in C $(TRANSLATIONS); do \
-		../scripts/validate.sh $$dir/index.xml ;\
+		../scripts/validate.sh $$dir/index.xml; \
 	done
 
+get-translations:
+ifeq ($(TRANSLATIONS),)
+    ifneq ($(wildcard po/LINGUAS),)
+	../scripts/translate.sh -u
+        TRANSLATIONS := $(shell cat po/LINGUAS)
+        TRANSOPTS = -g
+    else
+        TRANSLATIONS := $(TRANSALL)
+    endif
+endif
+
 clean:
-	${RM} -r $(TRANSLATIONS) C/translators.xml
-
-.PHONY: html translate
+	${RM} -r $(TRANSALL) C/translators.xml

=== modified file 'desktop-guide/libs/xubuntu-docbook-conf.xsl'
--- desktop-guide/libs/xubuntu-docbook-conf.xsl	2015-02-11 19:52:57 +0000
+++ desktop-guide/libs/xubuntu-docbook-conf.xsl	2015-03-28 16:37:06 +0000
@@ -89,4 +89,13 @@
 		<xsl:value-of select="'inline-icon-submenu'"/>
 	</xsl:template>
 
+	<!-- Normalize appearance of cross references -->
+	<xsl:template match="bridgehead|refsection|refsect1|refsect2|refsect3|sect1|sect2
+		|sect3|sect4|sect5|section|simplesect" mode="object.xref.template">
+		<xsl:text>%t</xsl:text>
+	</xsl:template>
+
+	<!-- Disable tooltips on links -->
+	<xsl:template match="*" mode="html.title.attribute"/>
+
 </xsl:stylesheet>

=== modified file 'scripts/translate.sh'
--- scripts/translate.sh	2015-02-15 02:42:56 +0000
+++ scripts/translate.sh	2015-03-28 16:37:06 +0000
@@ -26,62 +26,51 @@
 #
 # Optional parameters:
 #	-g Translate for every language listed in po/LINGUAS
-#	-l<language>
-#	-u Update the list of translations in po/LINGUAS
+#	-l <language>
+#	-u Update the list of languages in po/LINGUAS
 #
 
-translate() {
-	lang=$(basename ${1} .po)
-	echo " --Translating ${lang}"
-	mkdir -p ${lang}
-	for i in C/*xml; do
-		xml=$(basename ${i} C/)
-		xml2po --expand-all-entities --po-file po/${lang}.po C/${xml} >${lang}/${xml}
+translate () {
+    for lang in $@; do
+	echo "Translating $lang ..."
+	mkdir -p $lang
+	for xml in C/*.xml; do
+	    xml=$(basename $xml)
+	    xml2po --expand-all-entities --po-file po/$lang.po C/$xml > $lang/$xml
 	done
-	if [ -e C/${document}-C.omf ]; then
-		xml2po --expand-all-entities --po-file ${1} C/${document}-C.omf >${lang}/${document}-${lang}.omf
-		sed -i -e s@\"C\"@\"${lang}\"@g -e s@C/@${lang}/@g ${lang}/${document}-${lang}.omf
-	fi
-}
-
-choose_language() {
-	if [ ${1} ]; then
-		translate "po/${1}.po"
-	else
-		for x in po/*.po; do
-			translate ${x}
-		done
-	fi
-}
-
-shipped_languages() {
-percent=70
-for po in po/*.po
-do
-	if [ `msgfmt -o /dev/null --statistics $po 2>&1|awk '{printf("%.0f\n",$1 / ($1 + $4 + $7) * 100)}'` -ge "${percent}" ];then
-		basename $po .po
-	fi
-done | tee po/LINGUAS
-exit
-}
-
-while getopts ":gl:u" Option
-do
-	case ${Option} in
-		g) generated=yes;;
-		l) language=${OPTARG};;
-		u) shipped_languages;;
-		*) echo "Please specify an argument.";;
-	esac
+    done
+}
+
+shipped_languages () {
+    percreq="70"
+    echo "Updating LINGUAS ..."
+    for po in po/*.po; do
+	percdone=$(msgfmt -o /dev/null --statistics $po 2>&1 | awk '{printf "%.0f\n", $1 / ($1 + $4 + $7) * 100}')
+	if [ "$percdone" -ge "$percreq" ]; then
+	    basename $po .po
+	fi
+    done | tee po/LINGUAS
+}
+
+while getopts ":gl:u" opt; do
+    case $opt in
+	g)
+	    generated="yes";;
+	l)
+	    language=$OPTARG;;
+	u)
+	    shipped_languages
+	    exit;;
+    esac
 done
 
-if [ ${language} ]; then
-	choose_language ${language}
-elif [ ${generated} ] && [ -f po/LINGUAS ];then
-	for language in `cat po/LINGUAS`
-	do
-		choose_language ${language}
-	done
+if [ "$generated" = "yes" ]; then
+    if [ ! -f po/LINGUAS ]; then
+    	shipped_languages
+    fi
+    translate $(cat po/LINGUAS)
+elif [ -n "$language" ]; then
+    translate $language
 else
-		choose_language
+    translate $(basename -s .po -a po/*.po)
 fi

=== modified file 'scripts/translators.sh'
--- scripts/translators.sh	2015-02-14 23:09:26 +0000
+++ scripts/translators.sh	2015-03-28 16:37:06 +0000
@@ -1,52 +1,46 @@
 #!/bin/sh
 
-CURDIR=$(pwd)/po/
-
-get_languages() {
-if [ "$generated" = yes ];then
-	languages=$(cat po/LINGUAS)
-elif [ -n $language ];then
-	languages=$language
-else
-	languages=$(basename -s.po $CURDIR/*.po)
-fi
-}
-
-build_creds() {
-#for lang in `basename -s.po *.po`;do  ## Good for testing, uses all translations it can find.
-echo "<itemizedlist>"
-for lang in $languages;do
-	mkdir -p $CURDIR/mo/$lang/LC_MESSAGES/
-	msgfmt -o $CURDIR/mo/$lang/LC_MESSAGES/xubuntu-docs.mo $CURDIR/$lang.po
-	translators=$(TEXTDOMAINDIR=$CURDIR/mo/ LANGUAGE=$lang gettext -d xubuntu-docs -s 'translator-credits' | \
-		sed -e 's@^  @\t<listitem><para>@' -e '/launchpad.net/s@$@)</para></listitem>@' \
-		-e 's@https://launchpad.net/~@(@' -e /Launchpad\ Contributions/d -e /^translator-credits$/d | sort -u)
-done
-if [ "$translators" = "" ];then
-	echo "<listitem><para>Unable to parse translator data or data unavailable, see <ulink url=\"https://translations.launchpad.net/xubuntu-docs/\">Launchpad</ulink></para></listitem>"
-else
-	echo "$translators"
-fi
-echo "</itemizedlist>"
-rm -rf $CURDIR/mo/
-}
-
-grep_creds() {
-## Don't build, just grep.
-## This is incomplete and unused, potentially helpful later.
-for lang in $languages;do
-	echo  msggrep --msgid -F -e 'translator-credits' $lang.po
-done
-}
-
-while getopts ":gl:" Option
-do
-	case ${Option} in
-		g) generated=yes;;
-		l) language=${OPTARG};;
-		*) echo "Please specify an argument.";;
-	esac
-done
-
-get_languages
-build_creds
+build_creds () {
+    for lang in $@; do
+	translators=$(sed -n '/^msgid "translator-credits"/,/^$/ {s@^"[ ]*\(.\+\)[ ]\+https://launchpad.net/~\([^ \\"]\+\).*$@\t<listitem><para>\1 (\2)</para></listitem>@p;/^$/Q}' po/$lang.po | sort -u)
+	if [ -z "$translators" ]; then
+	    translators='\t<listitem><para>Translator data could not be acquired, please see <ulink url="https://translations.launchpad.net/xubuntu-docs">Launchpad</ulink>.</para></listitem>'
+	fi
+	printf "<itemizedlist>\n%b\n</itemizedlist>\n" "$translators" > $lang/translators.xml
+    done
+}
+
+build_creds_alt () {
+    for lang in $@; do
+	mkdir -p po/mo/$lang/LC_MESSAGES
+	msgfmt -o po/mo/$lang/LC_MESSAGES/xubuntu-docs.mo po/$lang.po
+	translators=$(TEXTDOMAINDIR=po/mo LANGUAGE=$lang gettext -d xubuntu-docs -s 'translator-credits' | \
+	    sed -n 's@^[ ]*\(.\+\)[ ]\+https://launchpad.net/~\([^ ]\+\).*$@\t<listitem><para>\1 (\2)</para></listitem>@p' | sort -u)
+	if [ -z "$translators" ]; then
+	    translators='\t<listitem><para>Translator data could not be acquired, please see <ulink url="https://translations.launchpad.net/xubuntu-docs">Launchpad</ulink>.</para></listitem>'
+	fi
+	printf "<itemizedlist>\n%b\n</itemizedlist>\n" "$translators" > $lang/translators.xml
+    done
+    rm -rf po/mo
+}
+
+while getopts ":gl:" opt; do
+    case $opt in
+	g)
+	    generated="yes";;
+	l)
+	    language=$OPTARG;;
+    esac
+done
+
+if [ "$generated" = "yes" ]; then
+    if [ ! -f po/LINGUAS ]; then
+    	../scripts/translate.sh -u
+    fi
+    build_creds $(cat po/LINGUAS)
+elif [ -n "$language" ]; then
+    build_creds $language
+else
+    build_creds $(basename -s .po -a po/*.po)
+fi
+

=== modified file 'startpage/xubuntu-index-end.htx'
--- startpage/xubuntu-index-end.htx	2014-09-13 14:18:06 +0000
+++ startpage/xubuntu-index-end.htx	2015-03-28 16:37:06 +0000
@@ -1,8 +1,8 @@
 			</ul>
 
-		<h2>Other support methods</h2>
-			<p>If you can't find the answer to your question in the Official Documentation, there are other ways to get help and support for Xubuntu. The complete list of support methods can be found on the <a href="http://xubuntu.org/help">Help & Support</a> section of our website.</p>
-			<p>To get live help, join the <a href="http://webchat.freenode.net/?channels=xubuntu&nick=xubuntu..d&prompt=1">#xubuntu</a> channel on the Freenode IRC Network.</p>
+		<h2>Other Support Methods</h2>
+			<p>If you can't find the answer to your question in the Official Documentation, there are other ways to get help and support for Xubuntu. The complete list of support methods can be found in the <a href="http://xubuntu.org/help/">Help & Support</a> section of our website.</p>
+			<p>To get live help, join the <a href="http://webchat.freenode.net/?channels=xubuntu&nick=xubuntu..d&prompt=1">#xubuntu</a> channel on the Freenode IRC network.</p>
 
 		<p>When you are seeking for help, please note that most of the general Ubuntu help also applies to Xubuntu.</p>
 

=== modified file 'startpage/xubuntu-index-start.htx'
--- startpage/xubuntu-index-start.htx	2015-01-11 21:50:34 +0000
+++ startpage/xubuntu-index-start.htx	2015-03-28 16:37:06 +0000
@@ -19,8 +19,8 @@
 	<div id="content">
 		<h1>Welcome to Xubuntu 15.04 Documentation!</h1>
 
-		<h2>Official documentation</h2>
-			<p>The <a href="file:///usr/share/xubuntu-docs/desktop-guide/index.html">Official Documentation</a> provides documentation to the most common issues with Xubuntu.</p>
+		<h2>Official Documentation</h2>
+			<p>The <a href="C/index.html">Official Documentation</a> provides information to the most common issues with Xubuntu.</p>
 
-		<h3>Official documentation in other languages</h3>
+		<h3>In other languages</h3>
 			<ul class="inline">