1PO4A-BUILD.CONF.5(5) User Contributed Perl Documentation PO4A-BUILD.CONF.5(5)
2
3
4
6 po4a-build.conf - configuration file for building translated content
7
9 po4a-build.conf describes how "po4a-build" should build translated and
10 untranslated documentation from a set of untranslated source documents
11 and corresponding PO files.
12
13 All supported formats, in all supported combinations, can be handled in
14 a single po4a-build.conf configuration file and in a single call to
15 "po4a-build". However, you can also choose to separate the po/
16 directories and have one configuration file for each run. (Call
17 "po4a-build -f FILE" for each one.)
18
19 Note that although po4a-build includes support for adding gettext
20 support for translation of script output messages, po4a-build.conf
21 itself has no bearing on such translations. po4a-build.conf only
22 relates to translating static content like manpages.
23
24 For po4a-build support of runtime message translation, see
25 po4a-runtime(7).
26
28 Currently, "po4a-build" supports the following combinations:
29
30 DocBook XML for sections 1 and 3
31 Typically used for manpages for shell scripts or other interpreters
32 that do not have their own documentation format like POD. Suitable
33 XML can be generated directly from an existing manpage using
34 "doclifter" and "po4a-build" will then generate a POT file with no
35 extra workload. The POT file can then be offered for translation
36 and the PO files added to the relevant po/ directory. "po4a-build"
37 will then prepare not only the untranslated manpage from the
38 "doclifter" XML but also use "po4a" to prepare translated XML from
39 the PO files and then build translated manpages from the XML.
40
41 Manpages are generated using default support in docbook-xsl - the
42 stylesheet used can be overridden using the "XSLFILE" setting in
43 the "po4a-build" configuration file.
44
45 DocBook XML for HTML
46 The default stylesheet used to prepare the final HTML can be
47 overridden using the "HTMLXSL" setting in the "po4a-build"
48 configuration file.
49
50 POD for sections 1, 3, 5 and 7
51 pod2man is used to convert POD content for each of the supported
52 sections.
53
54 Use "PODFILE" for section 1, "PODMODULES" for section 3,
55 "POD5FILES" for section 5 and "POD7FILES" for section 7.
56
57 For content in sections 5 or 7 (which tends to need a filename
58 which is also used for section 1 content), if the filename includes
59 the 5 or 7 as part of the filename, this (and any filename
60 extension) will be automatically stripped.
61
62 e.g. to prepare /usr/share/man/man7/po4a.7.gz:
63
64 # POD files for section 7
65 POD7FILES="doc/po4a.7.pod"
66
68 Configuration values can appear in any order in the configuration file.
69
70 Any content after a '#' is ignored.
71
72 Any value that would always be empty can be dropped from the file.
73
74 Some configuration fields are required - po4a-build could end up with
75 nothing to do if required fields are empty.
76
77 CONFIG
78 Required.
79
80 Name and location of the (temporary) "po4a" configuration file that
81 "po4a-build" will generate and maintain. This file does not need to
82 live in your version control system and can be safely cleaned up
83 during the package build.
84
85 # name and location of the config file
86 CONFIG="_build/po4a.config"
87
88 PODIR
89 Required.
90
91 Directory containing the PO files for ALL translations handled by
92 this configuration file. All strings will be merged into a POT file
93 in this directory and all PO files merged with that POT file. Any
94 KEEP threshold (see below) will be applied across all strings from
95 all input files specified in this file and all PO files in this
96 directory. The directory does not need to be called 'po'.
97
98 # po directory for manpages/docs
99 PODIR="po/pod"
100
101 POTFILE
102 Required.
103
104 Path to the POT file (relative to the location of this
105 configuration file) that will be generated, maintained and updated
106 by "po4a-build" for these translations.
107
108 # POT file path
109 POTFILE="po/pod/po4a-pod.pot"
110
111 BASEDIR
112 Required.
113
114 Base directory for writing out the translated content.
115
116 # base directory for generated files, e.g. doc
117 BASEDIR="_build"
118
119 BINARIES
120 Required.
121
122 Even if only one package is built, at least one value is required
123 here.
124
125 The string itself is arbitrary but typically consists of the
126 package name. Generated content will then appear in subdirectories
127 of BASEDIR/BINARIES:
128
129 _build/po4a/man/man1/foo.1
130
131 If the package builds more than one binary package (i.e. one source
132 package and multiple .deb or .rpm files), this field can help
133 isolate content intended for each target, making it easier to
134 automate the build process.
135
136 Separate strings with a space.
137
138 # binary packages that will contain generated manpages
139 BINARIES="po4a"
140
141 KEEP
142 Value to be passed directly to "po4a -k" to specify the threshold
143 for correctly translated content before a particular translation is
144 omitted from the build. Leave empty or remove to use the default
145 (80%) or specify zero to force the inclusion of all content, even
146 if completely untranslated.
147
148 For full control over such behaviour, consider carefully which
149 files are assigned to which po4a-build.conf configuration file.
150
151 Note that having lots of files in one POT file can be more
152 convenient for translators, especially if files have strings in
153 common. Conversely, POT files with thousands of long strings are
154 daunting for translators, leading to long string freezes.
155
156 # minimal threshold for translation percentage to keep
157 KEEP=
158
159 XMLMAN1
160 DocBook XML files to generate manpages in section 1. Separate
161 filenames with spaces. All files need to be in the XMLDIR
162 directory.
163
164 It is common practice to fold multiple XML files into one book, in
165 order to provide a table of contents etc. If the book contains
166 files also specified in XMLMAN3, only specify the XML files for
167 section 1 here, not the book itself. If the book only contains
168 content for this section, only specify the book file.
169
170 # DocBook XML files for section 1
171 XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"
172
173 XMLMAN3
174 DocBook XML files to generate manpages in section 3. Separate
175 filenames with spaces. All files need to be in the XMLDIR
176 directory.
177
178 It is common practice to fold multiple XML files into one book, in
179 order to provide a table of contents etc. If the book contains
180 files also specified in XMLMAN1, only specify the XML files for
181 section 3 here, not the book itself. If the book only contains
182 content for this section, only specify the book file.
183
184 # DocBook XML files for section 3
185 XMLMAN3=""
186
187 XMLDIR
188 Location of all the DocBook XML files. Currently, "po4a-build"
189 expects to be able to find all files listed in XMLMAN1 and XMLMAN3
190 by looking for *.xml files in this directory.
191
192 Must be specified if XMLMAN1 or XMLMAN3 are used. Paths are
193 relative to the location of the configuration file.
194
195 # location of the XML files
196 XMLDIR="share/doc/"
197
198 XMLPACKAGES
199 Which packages, out of the list in BINARIES, use XML source
200 content.
201
202 If any values are given in XMLMAN1 or XMLMAN3, a value must be
203 given here as well.
204
205 # binary packages using DocBook XML & xsltproc
206 XMLPACKAGES="po4a"
207
208 DOCBOOKDIR
209 Similar to XMLDIR but only used to prepare the translated DocBook
210 files. If your package wants to use .sgml files, please discuss how
211 these should be built on the po4a-devel mailing list.
212
213 # pattern to find the .docbook files
214 DOCBOOKDIR=""
215
216 XSLFILE
217 XSL stylesheet used to prepare the translated and untranslated
218 content from the DocBook XML files.
219
220 # XSL file to use for DocBook XML
221 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
222
223 PODFILE
224 POD files for generating manpage content in section 1. Separate POD
225 files with spaces. Paths, if used, need to be relative to the
226 location of the specified configuration file.
227
228 # POD files for section 1
229 PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"
230
231 PODMODULES
232 Specialised support for Perl modules containing POD content - the
233 module name will be reconstructed from the path (so this should be
234 the typical Perl layout) and manpages are automatically put into
235 section 3.
236
237 # POD files for section 3 - module names regenerated from the path
238 PODMODULES="lib/Locale/Po4a/*.pm"
239
240 POD5FILES
241 Arbitrary POD content for use generating manpages for section 5.
242 Paths, if used, need to be relative to the location of the
243 specified configuration file.
244
245 For content in sections 5 or 7 (which tends to need a filename
246 which is also used for section 1 content), if the filename includes
247 the 5 or 7 as part of the filename, this (and any filename
248 extension) will be automatically stripped.
249
250 # POD files for section 5
251 POD5FILES="doc/po4a-build.conf.5.pod"
252
253 POD7FILES
254 Arbitrary POD content for use generating manpages for section 7.
255 Paths, if used, need to be relative to the location of the
256 specified configuration file.
257
258 For content in sections 5 or 7 (which tends to need a filename
259 which is also used for section 1 content), if the filename includes
260 the 5 or 7 as part of the filename, this (and any filename
261 extension) will be automatically stripped.
262
263 # POD files for section 7
264 POD7FILES="doc/po4a.7.pod"
265
266 PODPACKAGES
267 Similar to XMLPACKAGES - any package expecting content to be built
268 from POD files needs to include a value in PODPACKAGES. Required if
269 any values are specified for PODFILE, PODMODULES, POD5FILES or
270 POD7FILES.
271
272 # binary packages using POD
273 PODPACKAGES="po4a"
274
275 HTMLDIR
276 Subdirectory of BASEDIR to be used to output the untranslated and
277 translated HTML output.
278
279 # HTML output (subdirectory of BASEDIR)
280 HTMLDIR=""
281
282 HTMLFILE
283 DocBook file to be converted to HTML (may be the same as one of the
284 files in XMLMAN1 or XMLMAN3). Sections are not relevant to HTML
285 output, so feel free to use the single book file here so that the
286 HTML has a table of contents etc.
287
288 # HTML DocBook file
289 HTMLFILE=""
290
291 HTMLXSL
292 The default is to use a chunked XSL stylesheet. It is not currently
293 supported to use more than one stylesheet per HTML run.
294
295 # XSL file to use for HTML
296 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
297
299 Neil Williams <linux@codehelp.co.uk>
300
301
302
303perl v5.12.2 2010-12-01 PO4A-BUILD.CONF.5(5)