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

[Jim Meyering]

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.