[Po4a-commits] "po4a/doc po4a-build.conf.5.pod, NONE, 1.1 po4a-runtime.7.pod, NONE, 1.1 po4a.7.pod, 1.48, 1.49"
Neil Williams
codehelp at alioth.debian.org
Fri Nov 13 10:46:43 UTC 2009
- Previous message: [Po4a-commits] "po4a changelog, 1.522, 1.523 MANIFEST, 1.57, 1.58 Makefile, 1.10, 1.11 po4a-build.conf, 1.1, 1.2"
- Next message: [Po4a-commits] "po4a/share/doc po4a-build.xml,1.1,1.2"
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvsroot/po4a/po4a/doc
In directory alioth:/tmp/cvs-serv29202/doc
Modified Files:
po4a.7.pod
Added Files:
po4a-build.conf.5.pod po4a-runtime.7.pod
Log Message:
* MANIFEST: Add build and runtime documentation.
* Makefile: Remove empty directories after install.
* doc/po4a-build.conf.5.pod: Documentation for the
po4a-build.conf file.
* doc/po4a-runtime.7.pod: Documentation for using example
files from po4a for runtime script translation.
* doc/po4a.7.pod: Typo.
* po4a-build.conf: Add section 5 and 7 POD content.
* share/doc/po4a-build.xml: Document section 5 support.
* share/po4a-build: Support section 5 for POD.
* share/po4a-build.conf.example: Section 5 support.
--- NEW FILE: po4a-runtime.7.pod ---
=pod
=head1 NAME
po4a-runtime - po4a and runtime gettext translation without autotools.
=head1 Introduction
With F<po4a-build>, F<po4a> also includes support for adding translation
of runtime script output messages using gettext but without requiring
the package to adopt autotools and the typical F<./configure> process.
Using example F<Makefile> snippets, packages can harness F<intltool>
with minimal effort.
=head1 Layout
Documentation translation should NOT use the same F<po/> directory
as the runtime translation. Whilst runtime translation can use
directories other than F<po/>, it is usually easiest to go with
the convention.
=head1 Multiple languages
Just a word on packages that use scripts in multiple programming
languages. A common mix is perl and shell. Note bene: gettext WILL
get confused and omit strings from one or other language unless file
extensions are used for whichever is the least problematic language.
When using multiple languages, experiment with various settings in
F<po/Makevars> until you get all the strings you need in the POT file.
In particular, specifying two languages in F<po/Makevars> can be
problematic. Instead of:
# Don't do this:
XGETTEXT_OPTIONS = -L Perl -L Shell --from-code=iso-8859-1
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 F<po/POTFILES.in>
is being processed.
The --keywords option can also be useful - see the xgettext
documentation.
=head1 Populating po/
So, create your top level F<po/> directory and then use the example
files in F</usr/share/po4a/examples/> to populate it.
=over
=item LINGUAS
Must exist, even if empty. Consists of a list of translations -
each line not starting with a '#' must match an existing PO file.
e.g. if LINGUAS contains a single line, 'fr', an F<fr.po> file
must exist alongside the LINGUAS file.
$ cat po/LINGUAS
cs
de
fr
$
By convention, the LINGUAS file is sorted alphabetically but that
is a manual process.
=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 F<po/>
directory, the paths should be relative to the top level directory,
not the F<po/> directory itself.
$ ls -l
myscript.pl
another.pl
foo/support.pl
po/
po/POTFILES.in
$ cat po/POTFILES.in
myscript.pl
another.pl
foo/support.pl
$
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 POD content for
documentation. So it is not a problem to have the same file listed
in F<po/POTFILES.in> and F<doc/po4a-build.conf>
=item Makevars-perl.example
If your scripts are perl, copy this example file as
F<po/Makevars> and edit it to suit.
=item Makevars-shell.example
If your scripts are shell, copy this example file as
F<po/Makevars> and edit it to suit.
=item po4a-build.make
Copy this example file as F<po/Makefile> - it shouldn't need editing
but you may prefer to symlink it to
F</usr/share/doc/po4a/examples/po4a-build.make> 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.)
=back
=head1 Building
These snippets need to be added to your top level Makefile or whatever
other method you use to prepare your sources for distribution.
clean:
$(MAKE) -C po/ clean
install:
$(MAKE) -C po/ install DESTDIR=$(DESTDIR)
dist:
$(MAKE) -C po/ pot
(In an autotools project, this would happen automatically by simply
adding F<po> to the C<SUBDIRS> value in F<Makefile.am>.)
=head1 Maintenance
Runtime translation isn't quite as easy as F<po4a-build> in that adding
a new translation does require editing F<po/LINGUAS>, but apart from
that, updating translations is merely a case of replacing the relevant
PO file with the new version.
Depending on how you prepare your source tarball, you may also need
to list new PO files in the MANIFEST file or add to the script(s) that
prepare the tarball. (That also applies to F<po4a-build>.)
Any F<*.mo> or F<*.gmo> files in po can be deleted / cleaned up.
=head1 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.
=cut
Index: po4a.7.pod
===================================================================
RCS file: /cvsroot/po4a/po4a/doc/po4a.7.pod,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- po4a.7.pod 15 Mar 2009 23:48:29 -0000 1.48
+++ po4a.7.pod 13 Nov 2009 10:46:41 -0000 1.49
@@ -8,8 +8,6 @@
interestingly, the maintenance of translations) using gettext tools on areas
where they were not expected like documentation.
-=cut
-
In po4a each documentation format is handled by a module. For now, we have
a module for the pod format (in which the Perl documentation is written),
the good old man pages, the documentation of the kernel compilation
--- NEW FILE: po4a-build.conf.5.pod ---
=pod
=head1 NAME
po4a-build.conf - configuration file for building translated content
=head1 Introduction
F<po4a-build.conf> describes how C<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 F<po4a-build.conf> configuration file and in a
single call to C<po4a-build>. However, you can also choose to
separate the F<po/> directories and have one configuration file for
each run. (Call C<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 C<po4a-build> run.
Note that although F<po4a-build> includes support for adding gettext
support for translation of script output messages, F<po4a-build.conf>
itself has no bearing on such translations. F<po4a-build.conf> only
relates to translating static content like manpages.
For F<po4a-build> support of runtime message translation, see
F<po4a-runtime (7)>.
=head1 Supported formats
Currently, C<po4a-build> supports the following combinations:
=over
=item 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 C<doclifter> and
C<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 F<po/> directory. C<po4a-build> will then prepare not only
the untranslated manpage from the C<doclifter> XML but also use
C<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 C<XSLFILE> setting in
the C<po4a-build> configuration file.
=item DocBook XML for HTML
The stylesheet used to prepare the final HTML can be left as the default
(or overridden using the C<HTMLXSL> setting in the C<po4a-build>
configuration file.
=item POD for Sections 1, 3, 5 and 7.
pod2man is used to convert POD content for each of the supported sections.
Use C<PODFILE> for section 1, C<PODMODULES> for section 3,
C<POD5FILES> for section 5 and C<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 F</usr/share/man/man7/po4a.7.gz> :
# POD files for section 7
POD7FILES="doc/po4a.7.pod"
=back
=head1 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 - F<po4a-build> could end up
with nothing to do if required fields are empty.
=over
=item CONFIG
Required.
# name and location of the config file
CONFIG="_build/po4a.config"
Name and location of the (temporary) C<po4a> configuration file that
C<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.
=item 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'.
=item POTFILE
Required.
Path to the POTFILE (relative to the location of this configuration
file) that will be generated, maintained and updated by C<po4a-build>
for these translations.
# POTFILE path
POTFILE="po/pod/po4a-pod.pot"
=item BASEDIR
Required.
Base directory for writing out the translated content.
# base directory for generated files, e.g. doc
BASEDIR="_build"
=item 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
F<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"
=item KEEP
A value to be passed directly to C<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 F<po4a-build.conf> configuration file.
Every file listed in any one F<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=
=item 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"
=item 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=""
=item XMLDIR
Location of all the Docbook XML files. Currently, C<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/"
=item 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"
=item 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=""
=item 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"
=item 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"
=item 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"
=item 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"
=item 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"
=item 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"
=item HTMLDIR
A subdirectory of BASEDIR to be used to output the untranslated and
translated HTML output.
# html output (subdirectory of BASEDIR)
HTMLDIR=""
=item 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=""
=item 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"
=back
=cut
- Previous message: [Po4a-commits] "po4a changelog, 1.522, 1.523 MANIFEST, 1.57, 1.58 Makefile, 1.10, 1.11 po4a-build.conf, 1.1, 1.2"
- Next message: [Po4a-commits] "po4a/share/doc po4a-build.xml,1.1,1.2"
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Po4a-commits
mailing list