Provided by: po4a_0.40-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.)

       (See also KEEP below for some limitations of combining lots of files
       into one POT file and one "po4a-build" run.

       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 stylesheet used to prepare the final HTML can be left as the
           default (or 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 config file
            CONFIG="_build/po4a.config"

           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.

       PODIR
           Required.

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

           The 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'.

       POTFILE
           Required.

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

            # POTFILE 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 sub-directories
           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.

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

       KEEP
           A 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.
           Every file listed in any one po4a-build.conf file will be included
           in the calculation for the percentage of strings correctly
           translated. If there is one large file that is poorly translated,
           this will prevent other, smaller, files from being included in the
           build even if those individual files are 100% translated.

           On the other hand, 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.

            # the 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.

            # the Docbook XML manpages 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.

            # the 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.

            # the 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.

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

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

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

       PODFILE
           The POD file(s) 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.

            # the POD files for man1
            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.

            # the POD files for man3/ - 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.

            # the binary packages using POD
            PODPACKAGES="po4a"

       HTMLDIR
           A subdirectory of BASEDIR to be used to output the untranslated and
           translated HTML output.

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

       HTMLFILE
           The DocBook file to be converted to HTML (may be the same as one of
           the files in XMLFILE). 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.

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

AUTHORS

        Neil Williams <linux@codehelp.co.uk>