Provided by: po4a_0.45-1_all bug

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).

Supported formats

       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>