chiark / gitweb /
i18n: po4a: Introduce machinery
[dgit.git] / po4a / Makefile
1 # dgit document translation machinery
2 #
3 # Translators: there is no need to look at this file.  It contains
4 # complicated machinery which you do not need to understand :-).
5 # See po/README instead.
6
7 # Copyright (C)2018 Ian Jackson
8 #
9 # This program is free software: you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
13 #
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 # GNU General Public License for more details.
18 #
19 # You should have received a copy of the GNU General Public License
20 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
21
22 # ----- devel docs (translators, pleaee ignore all this) -----
23 #
24 # We use po4a for everything.
25 #
26 # po4a is nicely automatic for all the po handling, and the config
27 # file makes nice documentation, but it really really likes to dirty
28 # the tree.  And we want to automatically list the documents and the
29 # translation languages which it doesn't make easy.
30 #
31 # The approach I have chosen is as follows:
32 #
33 # po4a.cfg
34 #
35 #   This is autogenerated.  But also, we invite translators to add
36 #   their own language to it.  The resulting merge
37 #   conflict/discrepancy will be just an alphabetical ordering
38 #   discrepancy, since our generation script scans the available po
39 #   files.
40 #
41 #   Generation is done by a shell script, ./list-documents.
42 #
43 #   make targets:  po4a.cfg           # many others imply this
44 #                  po4a.cfg.check     # fails if out of date
45 #
46 # *.pot, *.po
47 #
48 #   As far as translators are concerned, generated and maintained by
49 #   po4a and committed to git.  As for the developers, we update this
50 #   occasionally just by running po4a.
51 #
52 #   make targets:  default           } mean
53 #                  pofiles           }  the same
54 #
55 # Translations for translators:
56 #
57 #   make targets:  preview.LANG
58 #                  translated
59 #
60 # Translated document source-language files (eg, translated pod):
61 #
62 #   Like with normal po things, the tools don't like to generate
63 #   output without updating (dirtying) the .po files.  But with po4a
64 #   this is really hard to avoid.  So we use a linkfarming technique.
65 #
66 #   make targets:  translated-only
67 #
68 # Translated output files (roff format, from pod2man):
69 #
70 #   We have sort of lost the usual make rule information by now
71 #   about targets and what to build.  Only po4a knows which
72 #   translated files are supposed to exist.  So we have a shell
73 #   script which reuses the top-level Makefile to run pod2man
74 #   where appropriate, and generate a further even-more-output-ish
75 #   tree.
76 #
77 #   make targets:  install
78
79
80 default: pofiles
81
82 all: translated-always
83
84 pofiles: po4a.cfg
85         po4a --no-translations $<
86
87 e=set -e; exec >$@.tmp
88 f=mv -f $@.tmp $@
89 o= >$@.tmp && $f
90
91 S=@
92 # Set S='' to see commands being run
93
94 translated: po4a.cfg
95         po4a $<
96
97 po4a.cfg: list-documents
98         ./$< $o
99
100 po4a.cfg.check: list-documents
101         ./$< >$@.tmp
102         diff po4a.cfg $@.tmp
103
104 t = ../.po4a.translated-only
105 p = ../po4a
106
107 translated-only: po4a.cfg
108         rm -rf $t && mkdir $t
109         cd $t && ln -s $p/*.po $p/*.pot $p/po4a.cfg .
110         cd $t && po4a po4a.cfg
111         ! test -d $t/translated || \
112         cp -al --remove-destination $t/translated .
113
114 .po4a.%.cfg: po4a.cfg Makefile
115         $S perl -p -e 's{^(\[po4a_langs\]).*}{$$1 $*};' \
116                 -e 's{:translated/man}{:.$*.translated/man}' \
117                 $< $o
118
119 .PRECIOUS: .po4a.%.cfg
120
121 preview.%: .po4a.%.cfg
122         $S po4a $<
123         $S ./install-documents >/dev/null .$*.translated $@
124         @ echo '# runes to preview the various final tranlated manpages:'
125         $S find $@ -type f -printf 'man -l %p\n'
126
127 # We can't really use timestamps to drive po4a
128 .PHONY: preview.% translated
129
130 install: translated-only
131         ./install-documents translated $(DESTDIR)