Configuration file for building translated content
po4a-build.conf describes how \*(C`po4a-build\*(C' should build translated and untranslated documentation from a set of untranslated source documents and corresponding \s-1PO\s0 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 \*(C`po4a-build\*(C'. However, you can also choose to separate the po/ directories and have one configuration file for each run. (Call \*(C`po4a-build -f FILE\*(C' 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, \*(C`po4a-build\*(C' supports the following combinations:
Typically used for manpages for shell scripts or other interpreters that do not have their own documentation format like \s-1POD\s0. Suitable \s-1XML\s0 can be generated directly from an existing manpage using \*(C`doclifter\*(C' and \*(C`po4a-build\*(C' will then generate a \s-1POT\s0 file with no extra workload. The \s-1POT\s0 file can then be offered for translation and the \s-1PO\s0 files added to the relevant po/ directory. \*(C`po4a-build\*(C' will then prepare not only the untranslated manpage from the \*(C`doclifter\*(C' \s-1XML\s0 but also use \*(C`po4a\*(C' to prepare translated \s-1XML\s0 from the \s-1PO\s0 files and then build translated manpages from the \s-1XML\s0. Manpages are generated using default support in docbook-xsl - the stylesheet used can be overridden using the \*(C`XSLFILE\*(C' setting in the \*(C`po4a-build\*(C' configuration file.
The default stylesheet used to prepare the final \s-1HTML\s0 can be overridden using the \*(C`HTMLXSL\*(C' setting in the \*(C`po4a-build\*(C' configuration file.
pod2man is used to convert \s-1POD\s0 content for each of the supported sections. Use \*(C`PODFILE\*(C' for section 1, \*(C`PODMODULES\*(C' for section 3, \*(C`POD5FILES\*(C' for section 5 and \*(C`POD7FILES\*(C' 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"
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.
Required. Name and location of the (temporary) \*(C`po4a\*(C' configuration file that \*(C`po4a-build\*(C' 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"
Required. Directory containing the \s-1PO\s0 files for \s-1ALL\s0 translations handled by this configuration file. All strings will be merged into a \s-1POT\s0 file in this directory and all \s-1PO\s0 files merged with that \s-1POT\s0 file. Any \s-1KEEP\s0 threshold (see below) will be applied across all strings from all input files specified in this file and all \s-1PO\s0 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"
Required. Path to the \s-1POT\s0 file (relative to the location of this configuration file) that will be generated, maintained and updated by \*(C`po4a-build\*(C' for these translations. # POT file path POTFILE="po/pod/po4a-pod.pot"
Required. Base directory for writing out the translated content. # base directory for generated files, e.g. doc BASEDIR="_build"
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 \s-1BASEDIR/BINARIES\s0: _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"
Value to be passed directly to \*(C`po4a -k\*(C' 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 \s-1POT\s0 file can be more convenient for translators, especially if files have strings in common. Conversely, \s-1POT\s0 files with thousands of long strings are daunting for translators, leading to long string freezes. # minimal threshold for translation percentage to keep KEEP=
DocBook \s-1XML\s0 files to generate manpages in section 1. Separate filenames with spaces. All files need to be in the \s-1XMLDIR\s0 directory. It is common practice to fold multiple \s-1XML\s0 files into one book, in order to provide a table of contents etc. If the book contains files also specified in \s-1XMLMAN3\s0, only specify the \s-1XML\s0 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"
DocBook \s-1XML\s0 files to generate manpages in section 3. Separate filenames with spaces. All files need to be in the \s-1XMLDIR\s0 directory. It is common practice to fold multiple \s-1XML\s0 files into one book, in order to provide a table of contents etc. If the book contains files also specified in \s-1XMLMAN1\s0, only specify the \s-1XML\s0 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=""
Location of all the DocBook \s-1XML\s0 files. Currently, \*(C`po4a-build\*(C' expects to be able to find all files listed in \s-1XMLMAN1\s0 and \s-1XMLMAN3\s0 by looking for *.xml files in this directory. Must be specified if \s-1XMLMAN1\s0 or \s-1XMLMAN3\s0 are used. Paths are relative to the location of the configuration file. # location of the XML files XMLDIR="share/doc/"
Which packages, out of the list in \s-1BINARIES\s0, use \s-1XML\s0 source content. If any values are given in \s-1XMLMAN1\s0 or \s-1XMLMAN3\s0, a value must be given here as well. # binary packages using DocBook XML & xsltproc XMLPACKAGES="po4a"
Similar to \s-1XMLDIR\s0 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=""
\s-1XSL\s0 stylesheet used to prepare the translated and untranslated content from the DocBook \s-1XML\s0 files. # XSL file to use for DocBook XML XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
\s-1POD\s0 files for generating manpage content in section 1. Separate \s-1POD\s0 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"
Specialised support for Perl modules containing \s-1POD\s0 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"
Arbitrary \s-1POD\s0 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"
Arbitrary \s-1POD\s0 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"
Similar to \s-1XMLPACKAGES\s0 - any package expecting content to be built from \s-1POD\s0 files needs to include a value in \s-1PODPACKAGES\s0. Required if any values are specified for \s-1PODFILE\s0, \s-1PODMODULES\s0, \s-1POD5FILES\s0 or \s-1POD7FILES\s0. # binary packages using POD PODPACKAGES="po4a"
Subdirectory of \s-1BASEDIR\s0 to be used to output the untranslated and translated \s-1HTML\s0 output. # HTML output (subdirectory of BASEDIR) HTMLDIR=""
DocBook file to be converted to \s-1HTML\s0 (may be the same as one of the files in \s-1XMLMAN1\s0 or \s-1XMLMAN3\s0). Sections are not relevant to \s-1HTML\s0 output, so feel free to use the single book file here so that the \s-1HTML\s0 has a table of contents etc. # HTML DocBook file HTMLFILE=""
The default is to use a chunked \s-1XSL\s0 stylesheet. It is not currently supported to use more than one stylesheet per \s-1HTML\s0 run. # XSL file to use for HTML HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
Neil Williams <[email protected]>