Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PO4A-BUILD.CONF(5)		  Po4a Tools		    PO4A-BUILD.CONF(5)

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"(1) 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>

Po4a Tools			  2020-08-27		    PO4A-BUILD.CONF(5)

NAME | Introduction | Supported formats | File contents | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=po4a-build.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help