=pod

=head1 NAME

po4a-build.conf - configuration file for building translated content

=head1 Introduction

F<po4a-build.conf> describes how C<po4a-build> should build translated
and untranslated documentation from a set of untranslated source
documents and corresponding PO files.

All supported formats, in all supported combinations, can be
handled in a single F<po4a-build.conf> configuration file and in a
single call to C<po4a-build>. However, you can also choose to
separate the F<po/> directories and have one configuration file for
each run. (Call C<po4a-build -f FILE> for each one.)

Note that although F<po4a-build> includes support for adding gettext
support for translation of script output messages, F<po4a-build.conf>
itself has no bearing on such translations. F<po4a-build.conf> only
relates to translating static content like manpages.

For F<po4a-build> support of runtime message translation, see
L<po4a-runtime(7)>.

=head1 Supported formats

Currently, C<po4a-build> supports the following combinations:

=over

=item DocBook XML for sections 1 and 3

Typically used for manpages for shell scripts or other interpreters that
do not have their own documentation format like POD. Suitable XML can
be generated directly from an existing manpage using C<doclifter>(1) and
C<po4a-build> will then generate a POT file with no extra workload. The
POT file can then be offered for translation and the PO files added to
the relevant F<po/> directory. C<po4a-build> will then prepare not only
the untranslated manpage from the C<doclifter> XML but also use
C<po4a> to prepare translated XML from the PO files and then build
translated manpages from the XML.

Manpages are generated using default support in docbook-xsl - the
stylesheet used can be overridden using the C<XSLFILE> setting in
the C<po4a-build> configuration file.

=item DocBook XML for HTML

The default stylesheet used to prepare the final HTML can be
overridden using the C<HTMLXSL> setting in the C<po4a-build>
configuration file.

=item POD for sections 1, 3, 5 and 7

pod2man is used to convert POD content for each of the supported sections.

Use C<PODFILE> for section 1, C<PODMODULES> for section 3,
C<POD5FILES> for section 5 and C<POD7FILES> for section 7.

For content in sections 5 or 7 (which tends to need a filename which is
also used for section 1 content), if the filename includes the 5 or 7 as
part of the filename, this (and any filename extension) will be
automatically stripped.

e.g. to prepare F</usr/share/man/man7/po4a.7.gz>:

 # POD files for section 7
 POD7FILES="doc/po4a.7.pod"

=back

=head1 File contents

Configuration values can appear in any order in the configuration file.

Any content after a '#' is ignored.

Any value that would always be empty can be dropped from the file.

Some configuration fields are required - F<po4a-build> could end up
with nothing to do if required fields are empty.

=over

=item CONFIG

Required.

Name and location of the (temporary) C<po4a> configuration file that
C<po4a-build> will generate and maintain. This file does not need to
live in your version control system and can be safely cleaned up
during the package build.

 # name and location of the config file
 CONFIG="_build/po4a.config"

=item PODIR

Required.

Directory containing the PO files for ALL translations handled by
this configuration file. All strings will be merged into a POT file
in this directory and all PO files merged with that POT file. Any
KEEP threshold (see below) will be applied across all strings from
all input files specified in this file and all PO files in this
directory. The directory does not need to be called 'po'. Please
note, however, that some statistic tools expect the name to be
'po', therefor it is recommended to keep this name.

 # po directory for manpages/docs
 PODIR="po/pod"

=item POTFILE

Required.

Path to the POT file (relative to the location of this configuration
file) that will be generated, maintained and updated by C<po4a-build>
for these translations.

 # POT file path
 POTFILE="po/pod/po4a-pod.pot"

=item BASEDIR

Required.

Base directory for writing out the translated content.

 # base directory for generated files, e.g. doc
 BASEDIR="_build"

=item BINARIES

Required.

Even if only one package is built, at least one value is required here.

The string itself is arbitrary but typically consists of the package
name. Generated content will then appear in subdirectories of
F<BASEDIR/BINARIES>:

 _build/po4a/man/man1/foo.1

If the package builds more than one binary package (i.e. one source
package and multiple .deb or .rpm files), this field can help isolate
content intended for each target, making it easier to automate the
build process.

Separate strings with a space.

 # binary packages that will contain generated manpages
 BINARIES="po4a"

=item KEEP

Value to be passed directly to C<po4a -k> to specify the
threshold for correctly translated content before a particular
translation is omitted from the build. Leave empty or remove
to use the default (80%) or specify zero to force the inclusion
of all content, even if completely untranslated.

For full control over such behaviour, consider carefully which
files are assigned to which F<po4a-build.conf> configuration file.

Note that having lots of files in one POT file can be
more convenient for translators, especially if files have strings in
common. Conversely, POT files with thousands of long strings are
daunting for translators, leading to long string freezes.

 # minimal threshold for translation percentage to keep
 KEEP=

=item XMLMAN1

DocBook XML files to generate manpages in section 1. Separate filenames
with spaces. All files need to be in the XMLDIR directory.

It is common practice to fold multiple XML files into one book, in
order to provide a table of contents etc. If the book contains files
also specified in XMLMAN3, only specify the XML files for section 1
here, not the book itself. If the book only contains content for this
section, only specify the book file.

 # DocBook XML files for section 1
 XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"

=item XMLMAN3

DocBook XML files to generate manpages in section 3. Separate filenames
with spaces. All files need to be in the XMLDIR directory.

It is common practice to fold multiple XML files into one book, in
order to provide a table of contents etc. If the book contains files
also specified in XMLMAN1, only specify the XML files for section 3
here, not the book itself. If the book only contains content for this
section, only specify the book file.

 # DocBook XML files for section 3
 XMLMAN3=""

=item XMLDIR

Location of all the DocBook XML files. Currently, C<po4a-build> expects
to be able to find all files listed in XMLMAN1 and XMLMAN3 by looking
for *.xml files in this directory.

Must be specified if XMLMAN1 or XMLMAN3 are used. Paths are relative to
the location of the configuration file.

 # location of the XML files
 XMLDIR="share/doc/"

=item XMLPACKAGES

Which packages, out of the list in BINARIES, use XML source content.

If any values are given in XMLMAN1 or XMLMAN3, a value must be given
here as well.

 # binary packages using DocBook XML & xsltproc
 XMLPACKAGES="po4a"

=item DOCBOOKDIR

Similar to XMLDIR but only used to prepare the translated DocBook
files. If your package wants to use .sgml files, please discuss
how these should be built on the po4a-devel mailing list.

 # pattern to find the .docbook files
 DOCBOOKDIR=""

=item XSLFILE

XSL stylesheet used to prepare the translated and untranslated
content from the DocBook XML files.

 # XSL file to use for DocBook XML
 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

=item PODFILE

POD files for generating manpage content in section 1. Separate
POD files with spaces. Paths, if used, need to be relative to the
location of the specified configuration file.

 # POD files for section 1
 PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"

=item PODMODULES

Specialised support for Perl modules containing POD content - the
module name will be reconstructed from the path (so this should
be the typical Perl layout) and manpages are automatically put into
section 3.

 # POD files for section 3 - module names regenerated from the path
 PODMODULES="lib/Locale/Po4a/*.pm"

=item POD5FILES

Arbitrary POD content for use generating manpages for section 5. Paths,
if used, need to be relative to the location of the specified
configuration file.

For content in sections 5 or 7 (which tends to need a filename which is
also used for section 1 content), if the filename includes the 5 or 7 as
part of the filename, this (and any filename extension) will be
automatically stripped.

 # POD files for section 5
 POD5FILES="doc/po4a-build.conf.5.pod"

=item POD7FILES

Arbitrary POD content for use generating manpages for section 7. Paths,
if used, need to be relative to the location of the specified
configuration file.

For content in sections 5 or 7 (which tends to need a filename which is
also used for section 1 content), if the filename includes the 5 or 7 as
part of the filename, this (and any filename extension) will be
automatically stripped.

 # POD files for section 7
 POD7FILES="doc/po4a.7.pod"

=item PODPACKAGES

Similar to XMLPACKAGES - any package expecting content to be built from
POD files needs to include a value in PODPACKAGES. Required if any
values are specified for PODFILE, PODMODULES, POD5FILES or POD7FILES.

 # binary packages using POD
 PODPACKAGES="po4a"

=item HTMLDIR

Subdirectory of BASEDIR to be used to output the untranslated and
translated HTML output.

 # HTML output (subdirectory of BASEDIR)
 HTMLDIR=""

=item HTMLFILE

DocBook file to be converted to HTML (may be the same as
one of the files in XMLMAN1 or XMLMAN3). Sections are not relevant to HTML
output, so feel free to use the single book file here so that the
HTML has a table of contents etc.

 # HTML DocBook file
 HTMLFILE=""

=item HTMLXSL

The default is to use a chunked XSL stylesheet. It is not currently
supported to use more than one stylesheet per HTML run.

 # XSL file to use for HTML
 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

=back

=head1 AUTHORS

 Neil Williams <linux@codehelp.co.uk>

=cut
