1PO4A-BUILD(1)                        PO4A                        PO4A-BUILD(1)
2
3
4

NAME

6       po4a-build - build translated documentation
7

SYNOPSIS

9       po4a-build [-f | --file FILE] [--pot-only]
10
11       po4a-build [-? | -h | --help | --version]
12

DESCRIPTION

14       po4a-build is intended to make it as easy to produce translated
15       documentation as it can be to produce the current untranslated content.
16
17       When po4a prepares the translated content as POD or DocBook XML, the
18       final documentation can then be built using po4a-build. Both the
19       untranslated and translated content is built as a single process,
20       updating the POT files at the same time.
21
22       Existing build instructions are replaced by a single call to po4a-build
23       and a simple configuration file is used to tell po4a-build how to build
24       each element and which binary packages will include the translated and
25       untranslated content.
26
27       Once built, the content will be in package-specific directories beneath
28       the BASEDIR specified in the configuration file. For a binary package
29       foo, with translations into German and French, this would result in:
30
31           BASEDIR/foo/man/man1/foo.1
32           BASEDIR/foo/man/de/man1/foo.1
33           BASEDIR/foo/man/fr/man1/foo.1
34
35
36       This makes it easy to include all the generated content into the binary
37       package with a single install location:
38
39           doc/foo/man/* ./usr/share/man/
40           doc/foo/html/* ./usr/share/doc/foo/
41
42
43       This rule will not need to be updated when new translations are added
44       and adding a second binary package (bar) allows the content for that
45       package to kept separate.
46
47   Supported formats
48       Currently, po4a-build supports the following combinations:
49
50        1. DocBook XML for section 1.
51
52        2. DocBook XML for section 3.
53
54        3. DocBook XML for HTML.
55
56        4. POD for section 1.
57
58        5. POD for section 3.
59
60        6. POD for section 5.
61
62        7. POD for section 7.
63
64       All supported formats, in all supported combinations, can be handled in
65       a single po4a-build.conf configuration file and in a single call to
66       po4a-build. See po4a-build.conf(5).
67

CONFIGURATION

69       po4a-build uses a default configuration file, po4a-build.conf which
70       should be in the top level directory of your package VCS. (Use the -f
71       option to specify a different file.) See po4a-build.conf(5).
72
73       Example 1. example configuration file
74
75       An example configuration file is available at:
76
77           /usr/share/doc/po4a/examples/po4a-build.conf.example
78
79
80   configuration file layout
81       The configuration file consists of several sections, general, XML/XSL
82       support, POD support and HTML support.
83
84       General includes the name and location of the po4a config file
85       (probably best to leave this as po4a.config), the po directory
86       containing the documentation PO files (often doc/po), the full name of
87       the POT file used to create the translations, the BASEDIR for the
88       generated output, whether the package contains manpages in section 3
89       rather than just section 1 and the names of the binary packages which
90       are to contain the generated output.
91
92       XML/XSL support includes specifying which of the binary packages use
93       XSL support in the XMLPACKAGES variable, the top level DocBook file to
94       pass to xsltproc and the location of the XML or DocBook files. The
95       XSLFILE can be overridden, if necessary.
96
97       POD support includes specifying which of the binary packages use POD
98       support in the PODPACKAGES variable and the full name of the POD file.
99
100       HTML support specifies the subdirectory to create below BASEDIR for the
101       untranslated and translated HTML content and the DocBook file to
102       generate the HTML. The HTMLXSL file can be overridden, if necessary.
103

COMMANDS

105       --pot-only
106           Only updates the POT file(s).  --pot-only is intended to support
107           packages including all POT files in the package source. Packages
108           using Autotools can easily add the POT file via EXTRA_DIST but
109           packages just using a Makefile or certain VCS build helpers can
110           find it awkward to add the POT file (which is a generated file)
111           without putting the POT file into the VCS. To avoid this ugly and
112           unnecessary work, po4a-build can update the POT file(s) at the
113           start of the build, so that dpkg-source includes them into the
114           source tarball.
115
116           Example 2. svn-buildpackage example
117
118           svn-buildpackage has explicit support for this kind of addition,
119           using the useNativeDist SVN property and the native-dist Make
120           target.
121
122               # adds the POT file to the source tarball
123               native-dist: Makefile
124                    po4a-build --pot-only
125
126
127               $ svn propset useNativeDist 1 debian
128
129
130       -h|--help
131           print the usage message and exit.
132
133       --version
134           print the usage message and exit.
135

OPTIONS

137       -f|--file FILE
138           Override the po4a-build default configuration file
139           (po4a-build.conf) and supply your own.
140

AUTHOR

142       po4a-build was written by Neil Williams <codehelp@debian.org>.
143
144       This manual page was written by Neil Williams <codehelp@debian.org>
145
146
147
148PO4A                              06/10/2014                     PO4A-BUILD(1)