.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "PO4A-RUNTIME 7"
.TH PO4A-RUNTIME 7 "2018-06-07" "Po4a Tools" "Po4a Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
po4a\-runtime \- po4a and runtime gettext translation without Autotools
.SH "Introduction"
.IX Header "Introduction"
With \fIpo4a\-build\fR, \fIpo4a\fR also includes support for adding translation
of runtime script output messages using gettext but without requiring
the package to adopt Autotools and the typical \fI./configure\fR process.
.PP
Using example \fIMakefile\fR snippets, packages can harness \fIintltool\fR
with minimal effort.
.SH "Layout"
.IX Header "Layout"
Documentation translation should \s-1NOT\s0 use the same \fIpo/\fR directory
as the runtime translation. Whilst runtime translation can use
directories other than \fIpo/\fR, it is usually easiest to go with
the convention.
.SH "Multiple languages"
.IX Header "Multiple languages"
Just a word on packages that use scripts in multiple programming
languages. A common mix is Perl and shell. Note bene: gettext \s-1WILL\s0
get confused and omit strings from one or other language unless file
extensions are used for whichever is the least problematic language.
.PP
When using multiple languages, experiment with various settings in
\&\fIpo/Makevars\fR until you get all the strings you need in the \s-1POT\s0 file.
.PP
In particular, specifying two languages in \fIpo/Makevars\fR can be
problematic. Instead of:
.PP
.Vb 2
\& # Don\*(Aqt do this:
\& XGETTEXT_OPTIONS = \-L Perl \-L Shell \-\-from\-code=iso\-8859\-1
.Ve
.PP
Consider renaming (or providing symlink(s) for) all files for one of
the languages involved and omitting the explicit \-L options. The file
extension only needs to exist during the time that \fIpo/POTFILES.in\fR
is being processed.
.PP
The \-\-keywords option can also be useful \- see the \fBxgettext\fR(1)
documentation.
.SH "Populating po/"
.IX Header "Populating po/"
So, create your top level \fIpo/\fR directory and then use the example
files in \fI/usr/share/doc/po4a/examples/\fR to populate it.
.IP "\s-1LINGUAS\s0" 4
.IX Item "LINGUAS"
Must exist, even if empty. Consists of a list of translations \-
each line not starting with a '#' must match an existing \s-1PO\s0 file.
E.g. if \fI\s-1LINGUAS\s0\fR contains a single line, 'fr', an \fIfr.po\fR file
must exist alongside the \fI\s-1LINGUAS\s0\fR file.
.Sp
.Vb 5
\& $ cat po/LINGUAS
\& cs
\& de
\& fr
\& $
.Ve
.Sp
By convention, the \fI\s-1LINGUAS\s0\fR file is sorted alphabetically but that
is a manual process.
.IP "\s-1POTFILES\s0.in" 4
.IX Item "POTFILES.in"
The list of files containing the messages that need to be translated
at runtime \- i.e. your scripts. If you've used the top level \fIpo/\fR
directory, the paths should be relative to the top level directory,
not the \fIpo/\fR directory itself.
.Sp
.Vb 11
\& $ ls \-l
\& myscript.pl
\& another.pl
\& foo/support.pl
\& po/
\& po/POTFILES.in
\& $ cat po/POTFILES.in
\& myscript.pl
\& another.pl
\& foo/support.pl
\& $
.Ve
.Sp
Note that it is explicitly supported that the scripts themselves can
contain strings for both runtime and documentation translation, e.g.
using gettext functions for runtime and embedded \s-1POD\s0 content for
documentation. So it is not a problem to have the same file listed
in \fIpo/POTFILES.in\fR and \fIdoc/po4a\-build.conf\fR.
.IP "Makevars\-perl.example" 4
.IX Item "Makevars-perl.example"
If your scripts are in Perl, copy this example file as
\&\fIpo/Makevars\fR and edit it to suit.
.IP "Makevars\-shell.example" 4
.IX Item "Makevars-shell.example"
If your scripts are in shell, copy this example file as
\&\fIpo/Makevars\fR and edit it to suit.
.IP "po4a\-build.make" 4
.IX Item "po4a-build.make"
Copy this example file as \fIpo/Makefile\fR \- it shouldn't need editing
but you may want to keep it updated against
\&\fI/usr/share/doc/po4a/examples/po4a\-build.make\fR as it may need to
be updated within po4a releases as the underlying intltool support
changes (the file itself was generated from another project
using Autotools and intltool).
.SH "Building"
.IX Header "Building"
These snippets need to be added to your top level Makefile or whatever
other method you use to prepare your sources for distribution.
.PP
.Vb 2
\& clean:
\&        $(MAKE) \-C po/ clean
\&
\& install:
\&        $(MAKE) \-C po/ install DESTDIR=$(DESTDIR)
\&
\& dist:
\&        $(MAKE) \-C po/ pot
.Ve
.PP
(In an Autotools project, this would happen automatically by simply
adding \fIpo\fR to the \f(CW\*(C`SUBDIRS\*(C'\fR value in \fIMakefile.am\fR.)
.SH "Maintenance"
.IX Header "Maintenance"
Runtime translation isn't quite as easy as \fIpo4a\-build\fR in that adding
a new translation does require editing \fIpo/LINGUAS\fR, but apart from
that, updating translations is merely a case of replacing the relevant
\&\s-1PO\s0 file with the new version.
.PP
Depending on how you prepare your source tarball, you may also need
to list new \s-1PO\s0 files in the \fI\s-1MANIFEST\s0\fR file or add to the script(s) that
prepare the tarball (this also applies to \fIpo4a\-build\fR).
.PP
Any \fI*.mo\fR or \fI*.gmo\fR files in \fIpo/\fR can be deleted / cleaned up.
.SH "Copyright"
.IX Header "Copyright"
Whilst the example files are part of the po4a project, you are free
to use, modify and distribute them in your own projects without needing
to refer back to po4a or list the po4a team in your own copyright
notices, in the same manner as other build tools like Automake itself.
If you want to mention po4a, that is fine too.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 1
\& Neil Williams <linux@codehelp.co.uk>
.Ve