NAME¶
po4a-build.conf - configuration file for building translated content
Introduction¶
po4a-build.conf describes how "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
po4a-build.conf configuration file and in a single call to
"po4a-build". However, you can also choose to separate the
po/ directories and have one configuration file for each run. (Call
"po4a-build -f FILE" for each one.)
Note that although
po4a-build includes support for adding gettext support
for translation of script output messages,
po4a-build.conf itself has
no bearing on such translations.
po4a-build.conf only relates to
translating static content like manpages.
For
po4a-build support of runtime message translation, see
po4a-runtime(7).
Currently, "po4a-build" supports the following combinations:
- 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 "doclifter"
and "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 po/ directory. "po4a-build"
will then prepare not only the untranslated manpage from the
"doclifter" XML but also use "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 "XSLFILE" setting in the
"po4a-build" configuration file.
- DocBook XML for HTML
- The default stylesheet used to prepare the final HTML can be overridden
using the "HTMLXSL" setting in the "po4a-build"
configuration file.
- POD for sections 1, 3, 5 and 7
- pod2man is used to convert POD content for each of the supported sections.
Use "PODFILE" for section 1, "PODMODULES" for section 3,
"POD5FILES" for section 5 and "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 /usr/share/man/man7/po4a.7.gz:
# POD files for section 7
POD7FILES="doc/po4a.7.pod"
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 -
po4a-build could end up with
nothing to do if required fields are empty.
- CONFIG
- Required.
Name and location of the (temporary) "po4a" configuration file
that "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"
- 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"
- POTFILE
- Required.
Path to the POT file (relative to the location of this configuration file)
that will be generated, maintained and updated by "po4a-build"
for these translations.
# POT file path
POTFILE="po/pod/po4a-pod.pot"
- BASEDIR
- Required.
Base directory for writing out the translated content.
# base directory for generated files, e.g. doc
BASEDIR="_build"
- 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
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"
- KEEP
- Value to be passed directly to "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 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=
- 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"
- 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=""
- XMLDIR
- Location of all the DocBook XML files. Currently, "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/"
- 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"
- 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=""
- 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"
- 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"
- 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"
- 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"
- 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"
- 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"
- HTMLDIR
- Subdirectory of BASEDIR to be used to output the untranslated and
translated HTML output.
# HTML output (subdirectory of BASEDIR)
HTMLDIR=""
- 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=""
- 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"
AUTHORS¶
Neil Williams <linux@codehelp.co.uk>