'\" t
.\"     Title: po4a-build
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 06/02/2018
.\"    Manual: PO4A
.\"    Source: PO4A
.\"  Language: English
.\"
.TH "PO4A\-BUILD" "1" "06/02/2018" "PO4A" "PO4A"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
po4a-build \- build translated documentation
.SH "SYNOPSIS"
.HP \w'\fBpo4a\-build\fR\ 'u
\fBpo4a\-build\fR [\fB\-f\fR | \fB\-\-file\fR\fI FILE\fR] [\fB\-\-pot\-only\fR]
.HP \w'\fBpo4a\-build\fR\ 'u
\fBpo4a\-build\fR [\fB\-?\fR | \fB\-h\fR | \fB\-\-help\fR | \fB\-\-version\fR]
.SH "DESCRIPTION"
.PP
\fBpo4a\-build\fR
is intended to make it as easy to produce translated documentation as it can be to produce the current untranslated content\&.
.PP
When
\fBpo4a\fR
prepares the translated content as POD or DocBook XML, the final documentation can then be built using
\fBpo4a\-build\fR\&. Both the untranslated and translated content is built as a single process, updating the POT files at the same time\&.
.PP
Existing build instructions are replaced by a single call to
\fBpo4a\-build\fR
and a simple configuration file is used to tell
\fBpo4a\-build\fR
how to build each element and which binary packages will include the translated and untranslated content\&.
.PP
Once built, the content will be in package\-specific directories beneath the
\fBBASEDIR\fR
specified in the configuration file\&. For a binary package foo, with translations into German and French, this would result in:
.sp
.if n \{\
.RS 4
.\}
.nf
BASEDIR/foo/man/man1/foo\&.1
BASEDIR/foo/man/de/man1/foo\&.1
BASEDIR/foo/man/fr/man1/foo\&.1
    
.fi
.if n \{\
.RE
.\}
.PP
This makes it easy to include all the generated content into the binary package with a single install location:
.sp
.if n \{\
.RS 4
.\}
.nf
doc/foo/man/* \&./usr/share/man/
doc/foo/html/* \&./usr/share/doc/foo/
    
.fi
.if n \{\
.RE
.\}
.PP
This rule will not need to be updated when new translations are added and adding a second binary package (bar) allows the content for that package to kept separate\&.
.SS "Supported formats"
.PP
Currently,
\fBpo4a\-build\fR
supports the following combinations:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
DocBook XML for section 1\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
DocBook XML for section 3\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
DocBook XML for HTML\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
POD for section 1\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
POD for section 3\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
POD for section 5\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
POD for section 7\&.
.RE
.PP
All supported formats, in all supported combinations, can be handled in a single
po4a\-build\&.conf
configuration file and in a single call to
\fBpo4a\-build\fR\&. See
\fBpo4a-build.conf\fR(5)\&.
.SH "CONFIGURATION"
.PP
\fBpo4a\-build\fR
uses a default configuration file,
po4a\-build\&.conf
which should be in the top level directory of your package VCS\&. (Use the
\fB\-f\fR
option to specify a different file\&.) See
\fBpo4a-build.conf\fR(5)\&.
.PP
\fBExample\ \&1.\ \&example configuration file\fR
.PP
An example configuration file is available at:
.sp
.if n \{\
.RS 4
.\}
.nf
/usr/share/doc/po4a/examples/po4a\-build\&.conf\&.example
    
.fi
.if n \{\
.RE
.\}
.SS "configuration file layout"
.PP
The configuration file consists of several sections, general, XML/XSL support, POD support and HTML support\&.
.PP
General includes the name and location of the po4a config file (probably best to leave this as
po4a\&.config), the
po
directory containing the documentation PO files (often
doc/po), the full name of the POT file used to create the translations, the BASEDIR for the generated output, whether the package contains manpages in section 3 rather than just section 1 and the names of the binary packages which are to contain the generated output\&.
.PP
XML/XSL support includes specifying which of the binary packages use XSL support in the
\fBXMLPACKAGES\fR
variable, the top level DocBook file to pass to
\fBxsltproc\fR
and the location of the XML or DocBook files\&. The
\fBXSLFILE\fR
can be overridden, if necessary\&.
.PP
POD support includes specifying which of the binary packages use POD support in the PODPACKAGES variable and the full name of the POD file\&.
.PP
HTML support specifies the subdirectory to create below BASEDIR for the untranslated and translated HTML content and the DocBook file to generate the HTML\&. The HTMLXSL file can be overridden, if necessary\&.
.SH "COMMANDS"
.PP
\fB\-\-pot\-only\fR
.RS 4
Only updates the POT file(s)\&.
\fB\-\-pot\-only\fR
is intended to support packages including all POT files in the package source\&. Packages using Autotools can easily add the POT file via
\fBEXTRA_DIST\fR
but packages just using a Makefile or certain VCS build helpers can find it awkward to add the POT file (which is a generated file) without putting the POT file into the VCS\&. To avoid this ugly and unnecessary work,
\fBpo4a\-build\fR
can update the POT file(s) at the start of the build, so that
\fBdpkg\-source\fR
includes them into the source tarball\&.
.PP
\fBExample\ \&2.\ \&svn\-buildpackage example\fR
.PP
\fBsvn\-buildpackage\fR
has explicit support for this kind of addition, using the
\fBuseNativeDist\fR
SVN property and the
\fBnative\-dist\fR
Make target\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# adds the POT file to the source tarball
native\-dist: Makefile
	po4a\-build \-\-pot\-only
            
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ svn propset useNativeDist 1 debian
            
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-h\fR|\fB\-\-help\fR
.RS 4
print the usage message and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
print the script version and exit\&.
.RE
.SH "OPTIONS"
.PP
\fB\-f\fR|\fB\-\-file\fR\fI FILE\fR
.RS 4
Override the
\fBpo4a\-build\fR
default configuration file (po4a\-build\&.conf) and supply your own\&.
.RE
.SH "AUTHOR"
.PP
\fBpo4a\-build\fR
was written by Neil Williams
<codehelp@debian\&.org>\&.
.PP
This manual page was written by Neil Williams
<codehelp@debian\&.org>