Libguestfs - Sep 2010 - [PATCH] Allow manual pages and POD files to be translated.

You need to install po4a (in Fedora) to test this.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://et.redhat.com/~rjones/virt-df/
-------------- next part --------------
>From 7ca0058ecf24b6963771d0c39fd5e2f36874eb38 Mon Sep 17 00:00:00 2001
From: Richard Jones <rjones at redhat.com>
Date: Thu, 2 Sep 2010 14:54:44 +0100
Subject: [PATCH] Allow manual pages and POD files to be translated.

This uses the optional po4a package to split these files into
PO files for translation, and reassemble afterwards.

Note this creates an extra pot file (po-docs/libguestfs-docs.pot).
We don't (yet) combine this with the main po/libguestfs.pot file.
The 'libguestfs-docs.pot' file included in this commit is not the
real thing, just a short cut down snippet for testing.  The real
thing is created if you update one of the dependent files and
rebuild.

Note also the dummy ja.po, for testing the principles.
---
 .gitignore                  |    5 ++
 HACKING                     |    8 +++-
 Makefile.am                 |    3 +-
 README                      |    2 +
 configure.ac                |    6 +++
 po-docs/Makefile.am         |   80 ++++++++++++++++++++++++++++++++++++
 po-docs/ja.po               |   28 +++++++++++++
 po-docs/ja/Makefile.am      |   94 +++++++++++++++++++++++++++++++++++++++++++
 po-docs/libguestfs-docs.pot |   21 ++++++++++
 9 files changed, 245 insertions(+), 2 deletions(-)
 create mode 100644 po-docs/Makefile.am
 create mode 100644 po-docs/ja.po
 create mode 100644 po-docs/ja/Makefile.am
 create mode 100644 po-docs/libguestfs-docs.pot

diff --git a/.gitignore b/.gitignore
index 266fb74..56ad9bd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -197,6 +197,11 @@ po/en at quot.header
 po/insert-header.sin
 po/quot.sed
 po/remove-potcdate.sin
+po-docs/po4a.conf
+po-docs/*/*.pl
+po-docs/*/*.pod
+po-docs/*/*.1
+po-docs/*/*.3
 python/bindtests.py
 python/guestfs.py
 python/guestfs-py.c
diff --git a/HACKING b/HACKING
index 900980a..3d60737 100644
--- a/HACKING
+++ b/HACKING
@@ -116,7 +116,13 @@ ocaml/
         OCaml bindings.
 
 po/
-        Translations.
+        Translations of simple gettext strings.  For translations of
+        longer documents, see po-docs/.
+
+po-docs/
+        The build infrastructure and PO files for translations of
+        manpages and POD files.  Eventually this will be combined
+        with the po/ directory, but that is rather complicated.
 
 perl/
         Perl bindings.
diff --git a/Makefile.am b/Makefile.am
index a33c91c..085202b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -20,7 +20,7 @@ include $(top_srcdir)/subdir-rules.mk
 ACLOCAL_AMFLAGS = -I m4
 
 # Basic source for the library.
-SUBDIRS = gnulib/lib images src examples po
+SUBDIRS = gnulib/lib images src examples po po-docs
 
 if ENABLE_DAEMON
 SUBDIRS += daemon
@@ -181,6 +181,7 @@ all-local:
 	grep -v '/guestfs_protocol.c' | \
 	grep -v '/rc_protocol.c' | \
 	grep -v 'appliance/debian/root' | \
+	grep -v '^po-docs/' | \
 	LC_ALL=C sort | \
 	sed 's,^\./,,' > po/POTFILES.in
 
diff --git a/README b/README
index 2b8fdac..199f595 100644
--- a/README
+++ b/README
@@ -94,6 +94,8 @@ in virt-inspector).
 
 - (Optional, but highly recommended) perl-libintl for translating perl code.
 
+- (Optional) po4a for translating manpages and POD files.
+
 Running ./configure will check you have all the requirements installed
 on your machine.
 
diff --git a/configure.ac b/configure.ac
index acc1f88..935abdc 100644
--- a/configure.ac
+++ b/configure.ac
@@ -768,6 +768,10 @@ AM_CONDITIONAL([HAVE_INSPECTOR],
 AM_CONDITIONAL([HAVE_TOOLS],
     [test "x$PERL" != "xno" -a
"x$missing_perl_modules" != "xyes"])
 
+dnl po4a for translating man pages and POD files (optional).
+AC_CHECK_PROG([PO4A],[po4a],[po4a],[no])
+AM_CONDITIONAL([HAVE_PO4A], [test "x$PO4A" != "xno"])
+
 dnl Library versioning.
 MAX_PROC_NR=`cat $srcdir/src/MAX_PROC_NR`
 AC_SUBST(MAX_PROC_NR)
@@ -802,6 +806,8 @@ AC_CONFIG_FILES([Makefile
                  gnulib/lib/Makefile
                  gnulib/tests/Makefile
                  fuse/Makefile
+                 po-docs/Makefile
+                 po-docs/ja/Makefile
                  ocaml/META perl/Makefile.PL])
 AC_OUTPUT
 
diff --git a/po-docs/Makefile.am b/po-docs/Makefile.am
new file mode 100644
index 0000000..37a3e94
--- /dev/null
+++ b/po-docs/Makefile.am
@@ -0,0 +1,80 @@
+# libguestfs translations of man pages and POD files
+# Copyright (C) 2010 Red Hat Inc.
+#
+# 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., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+# XXX The use of po4a is naive here.  Also we should integrate this
+# into the po/ directory and the translations into the usual
+# libguestfs.pot file.
+
+# Languages.
+LINGUAS = ja
+
+EXTRA_DIST = \
+	libguestfs-docs.pot \
+	$(LINGUAS:%=%.po)
+
+CLEANFILES = po4a.conf
+
+# Build the final man pages from the translated POD files.  Each
+# language directory contains a Makefile.am that we need to keep up to
+# date (note each $lang/Makefile.am should be identical).
+# XXX Is there a better way?
+SUBDIRS = $(LINGUAS)
+
+# List of english POD sources which can be translated.
+# Perl files count as POD as far as po4a is concerned.
+PODFILES = \
+	../src/guestfs.pod \
+	../src/guestfs-actions.pod \
+	../src/guestfs-availability.pod \
+	../src/guestfs-structs.pod \
+	../fish/guestfish.pod \
+	../fish/guestfish-actions.pod \
+	../test-tool/libguestfs-test-tool.pod \
+	../fuse/guestmount.pod \
+	../inspector/virt-inspector.pl \
+	$(wildcard ../tools/virt-*.pl)
+
+if HAVE_PO4A
+
+# Note: po4a leaves empty '=encoding' lines in POD files.  Also it
+# includes a large warning message which ends up in the output.  We
+# post-process the output to remove both.
+libguestfs-docs.pot: po4a.conf
+	$(PO4A) \
+	  -k 0 \
+	  --package-name $(PACKAGE_NAME) \
+	  --package-version $(PACKAGE_VERSION) \
+	  --msgid-bugs-address libguestfs at redhat.com \
+	  --copyright-holder "Red Hat Inc." \
+	  po4a.conf
+	for f in `find $(LINGUAS) -name '*.pod' -o -name '*.pl'`; do \
+	  awk 'FNR >= 14 { print }' < $$f > $$f.new; \
+	  mv $$f.new $$f; \
+	done
+
+po4a.conf: $(PODFILES)
+	rm -f $@-t
+	echo "[po_directory] ." >> $@-t
+	echo >> $@-t
+	for f in $(PODFILES); do \
+	  b=`basename -- $$f`; \
+	  echo "[type: pod] $$f \$$lang:\$$lang/$$b" >> $@-t; \
+	  echo >> $@-t; \
+	done;
+	mv $@-t $@
+
+endif
diff --git a/po-docs/ja.po b/po-docs/ja.po
new file mode 100644
index 0000000..97542cc
--- /dev/null
+++ b/po-docs/ja.po
@@ -0,0 +1,28 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR Free Software Foundation, Inc.
+# FIRST AUTHOR <EMAIL at ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: libguestfs at redhat.com\n"
+"POT-Creation-Date: 2010-09-02 14:43+0200\n"
+"PO-Revision-Date: 2010-09-02 14:46+0100\n"
+"Last-Translator: FULL NAME <EMAIL at ADDRESS>\n"
+"Language-Team: LANGUAGE <LL at li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=CHARSET\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+# type: =head1
+#: ../src/guestfs.pod:3 ../fish/guestfish.pod:3
+#: ../test-tool/libguestfs-test-tool.pod:3 ../fuse/guestmount.pod:3
+#: ../inspector/virt-inspector.pl:38 ../tools/virt-cat.pl:32
+#: ../tools/virt-df.pl:34 ../tools/virt-edit.pl:33
+#: ../tools/virt-list-filesystems.pl:30 ../tools/virt-list-partitions.pl:30
+#: ../tools/virt-ls.pl:33 ../tools/virt-make-fs.pl:35
+#: ../tools/virt-rescue.pl:31 ../tools/virt-resize.pl:40
+#: ../tools/virt-tar.pl:32 ../tools/virt-win-reg.pl:36
+msgid "NAME"
+msgstr "??"
diff --git a/po-docs/ja/Makefile.am b/po-docs/ja/Makefile.am
new file mode 100644
index 0000000..e088ebb
--- /dev/null
+++ b/po-docs/ja/Makefile.am
@@ -0,0 +1,94 @@
+# libguestfs translations of man pages and POD files
+# Copyright (C) 2010 Red Hat Inc.
+#
+# 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., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+# Note that each Makefile.am in po-docs/$lang/Makefile.am should be
+# identical.  If you create a new $lang.po, create the $lang/
+# subdirectory and copy the Makefile.am from an existing language.
+
+LINGUA = $(shell basename -- `pwd`)
+
+CLEANFILES = *.1 *.3
+
+# Ship the final translated manpages in the tarball.
+MANPAGES = \
+	guestfs.3 \
+	guestfish.1 \
+	libguestfs-test-tool.1 \
+	guestmount.1 \
+	$(patsubst %.pl,%.1,$(wildcard virt-*.pl))
+
+EXTRA_DIST = $(MANPAGES)
+
+all-local: $(MANPAGES)
+
+guestfs.3: guestfs.pod guestfs-actions.pod guestfs-availability.pod
guestfs-structs.pod
+	sed \
+	  -e '/@ACTIONS@/rguestfs-actions.pod' \
+	  -e 's/@ACTIONS@//' \
+	  -e '/@AVAILABILITY@/rguestfs-availability.pod' \
+	  -e 's/@AVAILABILITY@//' \
+	  -e '/@STRUCTS@/rguestfs-structs.pod' \
+	  -e 's/@STRUCTS@//' \
+	< $< | \
+	$(POD2MAN) -u \
+	  --section 3 \
+	  -c "Virtualization Support" \
+	  --name "guestfs" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  > $@-t; mv $@-t $@
+
+guestfish.1: guestfish.pod guestfish-actions.pod
+	sed \
+	  -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \
+	  < $< | \
+	$(POD2MAN) -u \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --name "guestfish" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  > $@-t; mv $@-t $@
+
+guestmount.1: guestmount.pod
+	$(POD2MAN) -u \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --name "guestmount" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  $< > $@-t; mv $@-t $@
+
+libguestfs-test-tool.1: libguestfs-test-tool.pod
+	$(POD2MAN) -u \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  $< > $@-t; mv $@-t $@
+
+virt-%.1: virt-%.pl
+	$(POD2MAN) -u \
+	  --section 1 \
+	  -c "Virtualization Support" \
+	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
+	  $< > $@-t && mv $@-t $@
+
+# XXX Can automake do this properly?
+install-data-hook:
+	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man1
+	$(INSTALL) -m 0644 guestfish.1 $(DESTDIR)$(mandir)/$(LINGUA)/man1
+	$(INSTALL) -m 0644 guestmount.1 $(DESTDIR)$(mandir)/$(LINGUA)/man1
+	$(INSTALL) -m 0644 virt-*.1 $(DESTDIR)$(mandir)/$(LINGUA)/man1
+	$(MKDIR_P) $(DESTDIR)$(mandir)/$(LINGUA)/man3
+	$(INSTALL) -m 0644 guestfs.3 $(DESTDIR)$(mandir)/$(LINGUA)/man3
diff --git a/po-docs/libguestfs-docs.pot b/po-docs/libguestfs-docs.pot
new file mode 100644
index 0000000..04ffac2
--- /dev/null
+++ b/po-docs/libguestfs-docs.pot
@@ -0,0 +1,21 @@
+# SOME DESCRIPTIVE TITLE
+# Copyright (C) YEAR Red Hat Inc.
+# This file is distributed under the same license as the libguestfs package.
+# FIRST AUTHOR <EMAIL at ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: libguestfs 1.5.7\n"
+"Report-Msgid-Bugs-To: libguestfs at redhat.com\n"
+"POT-Creation-Date: 2010-09-02 14:43+0200\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL at ADDRESS>\n"
+"Language-Team: LANGUAGE <LL at li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=CHARSET\n"
+"Content-Transfer-Encoding: ENCODING"
+
+# type: =head1
+msgid "NAME"
+msgstr ""
-- 
1.7.1

See also:
http://lists.fedoraproject.org/pipermail/trans/2010-September/007964.html

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://et.redhat.com/~rjones/libguestfs/
See what it can do: http://et.redhat.com/~rjones/libguestfs/recipes.html

Richard W.M. Jones wrote:
> You need to install po4a (in Fedora) to test this.
>
> Subject: [PATCH] Allow manual pages and POD files to be translated.
>
> This uses the optional po4a package to split these files into
> PO files for translation, and reassemble afterwards.
>
> Note this creates an extra pot file (po-docs/libguestfs-docs.pot).
> We don't (yet) combine this with the main po/libguestfs.pot file.
> The 'libguestfs-docs.pot' file included in this commit is not the
> real thing, just a short cut down snippet for testing.  The real
> thing is created if you update one of the dependent files and
> rebuild.
>
> Note also the dummy ja.po, for testing the principles.
...
...
> diff --git a/po-docs/ja/Makefile.am b/po-docs/ja/Makefile.am
...

Hi Rich,

Nice change.
> +
> +# Note that each Makefile.am in po-docs/$lang/Makefile.am should be
> +# identical.  If you create a new $lang.po, create the $lang/
> +# subdirectory and copy the Makefile.am from an existing language.
> +
> +LINGUA = $(shell basename -- `pwd`)
> +
> +CLEANFILES = *.1 *.3
> +
> +# Ship the final translated manpages in the tarball.
> +MANPAGES = \
> +	guestfs.3 \
> +	guestfish.1 \
> +	libguestfs-test-tool.1 \
> +	guestmount.1 \
> +	$(patsubst %.pl,%.1,$(wildcard virt-*.pl))
> +
> +EXTRA_DIST = $(MANPAGES)
> +
> +all-local: $(MANPAGES)
> +
> +guestfs.3: guestfs.pod guestfs-actions.pod guestfs-availability.pod
guestfs-structs.pod
> +	sed \
> +	  -e '/@ACTIONS@/rguestfs-actions.pod' \
> +	  -e 's/@ACTIONS@//' \
> +	  -e '/@AVAILABILITY@/rguestfs-availability.pod' \
> +	  -e 's/@AVAILABILITY@//' \
> +	  -e '/@STRUCTS@/rguestfs-structs.pod' \
> +	  -e 's/@STRUCTS@//' \
> +	< $< | \
> +	$(POD2MAN) -u \
> +	  --section 3 \
> +	  -c "Virtualization Support" \
> +	  --name "guestfs" \
> +	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
> +	  > $@-t; mv $@-t $@
> +
> +guestfish.1: guestfish.pod guestfish-actions.pod
> +	sed \
> +	  -e '/@ACTIONS@/rguestfish-actions.pod' -e
's/@ACTIONS@//' \
> +	  < $< | \
> +	$(POD2MAN) -u \
> +	  --section 1 \
> +	  -c "Virtualization Support" \
> +	  --name "guestfish" \
> +	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
> +	  > $@-t; mv $@-t $@
> +
> +guestmount.1: guestmount.pod
> +	$(POD2MAN) -u \
> +	  --section 1 \
> +	  -c "Virtualization Support" \
> +	  --name "guestmount" \
> +	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
> +	  $< > $@-t; mv $@-t $@
> +
> +libguestfs-test-tool.1: libguestfs-test-tool.pod
> +	$(POD2MAN) -u \
> +	  --section 1 \
> +	  -c "Virtualization Support" \
> +	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
> +	  $< > $@-t; mv $@-t $@
> +
> +virt-%.1: virt-%.pl
> +	$(POD2MAN) -u \
> +	  --section 1 \
> +	  -c "Virtualization Support" \
> +	  --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \
> +	  $< > $@-t && mv $@-t $@
Most of the duplicated pod2man options above can be factored out.
It'd be cleaner still if we could depend on GNU Make,
but in the mean time, you can do something like this:
[untested]

section_number = $$(echo $@|sed 's/.*\.//')
man_name = $$(echo $@|sed 's/\..*//')

pod_to_man =							\
	$(POD2MAN) -u						\
	  --section $(section_number)				\
	  -c 'Virtualization Support'				\
	  --name $(man_name)					\
	  --release '$(PACKAGE_NAME)-$(PACKAGE_VERSION)'

guestfs.3: guestfs.pod guestfs-actions.pod guestfs-availability.pod
guestfs-structs.pod
	sed \
	  -e '/@ACTIONS@/rguestfs-actions.pod' \
	  -e 's/@ACTIONS@//' \
	  -e '/@AVAILABILITY@/rguestfs-availability.pod' \
	  -e 's/@AVAILABILITY@//' \
	  -e '/@STRUCTS@/rguestfs-structs.pod' \
	  -e 's/@STRUCTS@//' \
	< $< | \
	$(pod_to_man) < $< > $@-t; mv $@-t $@

guestfish.1: guestfish.pod guestfish-actions.pod
	sed \
	  -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \
	  < $< | \
	$(pod_to_man) < $< > $@-t; mv $@-t $@

guestmount.1: guestmount.pod
	$(pod_to_man) < $< > $@-t; mv $@-t $@

libguestfs-test-tool.1: libguestfs-test-tool.pod
	$(pod_to_man) < $< > $@-t; mv $@-t $@

virt-%.1: virt-%.pl
...

> +# XXX Can automake do this properly?
I don't know off hand.
Ask on the list?
> # Note that each Makefile.am in po-docs/$lang/Makefile.am should be
> # identical.  If you create a new $lang.po, create the $lang/
> # subdirectory and copy the Makefile.am from an existing language.
The following is obviously not a problem right now, but something to
think about before we get up to 20 or 40 different translations:

Once there are more translations, all of this duplication may become
cumbersome.  Duplicate Makefile.am files, all identical, each in its own
XX/ directory with nothing else...  Eventually it'd be nice to avoid that.
I can imagine using a single Makefile.am, and then a separate shell-code
loop over 2-byte country codes, copying each Makefile into a temporary
directory and then invoking make.  [TL;DR] it'd be nice not to require
a whole new directory-containing-only-dup'd-Makefile.am for each added
language.