other versions
- wheezy 0.42-1
Locale::Po4a::TeX(3) | User Contributed Perl Documentation | Locale::Po4a::TeX(3) |
NAME¶
Locale::Po4a::TeX - convert TeX documents and derivates from/to PO filesDESCRIPTION¶
The po4a (PO for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation. Locale::Po4a::TeX is a module to help the translation of TeX documents into other [human] languages. It can also be used as a base to build modules for TeX-based documents. Users should probably use the LaTeX module, which inherite from the TeX module and contains the definitions of common LaTeX commands.TRANSLATING WITH PO4A::TEX¶
This module can be used directly to handle generic TeX documents. This will split your document in smaller blocks (paragraphs, verbatim blocks, or even smaller like titles or indexes). There are some options (described in the next section) that can customize this behavior. If this doesn't fit to your document format you're encouraged to write your own module derived from this, to describe your format's details. See the section WRITING DERIVATE MODULES below, for the process description. This module can also be customized by lines starting with "% po4a:" in the TeX file. These customizations are described in the INLINE CUSTOMIZATION section.OPTIONS ACCEPTED BY THIS MODULE¶
These are this module's particular options:- debug
- Activate debugging for some internal mechanisms of this module. Use the source to see which parts can be debugged.
- no_wrap
- Comma-separated list of environments which should not be
re-wrapped.
- exclude_include
- Colon-separated list of files that should not be included by \input and \include.
- definitions
- The name of a file containing definitions for po4a, as defined in the INLINE CUSTOMIZATION section. You can use this option if it is not possible to put the definitions in the document being translated.
- verbatim
- Comma-separated list of environments which should be taken
as verbatim.
INLINE CUSTOMIZATION¶
The TeX module can be customized with lines starting by % po4a:. These lines are interpreted as commands to the parser. The following commands are recognized:- % po4a: command command1 alias command2
- Indicates that the arguments of the command1 command should be treated as the arguments of the command2 command.
- % po4a: command command1 parameters
- This permit to describe in detail the parameters of the
command1 command. This information will be used to check the number
of arguments and their types.
- an asterisk (*)
- po4a will extract this command from paragraphs (if it is located at the beginning or the end of a paragraph). The translators will then have to translate the parameters that are marked as translatable.
- a plus (+)
- As for an asterisk, the command will be extracted if it
appear at an extremity of a block, but the parameters won't be translated
separately. The translator will have to translate the command concatenated
to all its parameters. This permits to keep more context, and is useful
for commands with small words in parameter, which can have multiple
meanings (and translations).
- a minus (-)
- In this case, the command won't be extracted from any block. But if it appears alone on a block, then only the parameters marked as translatable will be presented to the translator. This is useful for font commands. These commands should generally not be separated from their paragraph (to keep the context), but there is no reason to annoy the translator with them if a whole string is enclosed in such a command.
% po4a: command *chapter [_]{_}
% po4a: command -href {}{_}
- % po4a: environment env parameters
- This permits to define the parameters accepted by the
env environment. This information is latter used to check the
number of arguments of the \begin command, and permit to specify which one
must be translated. The syntax of the parameters argument is the
same as described for the commands. The first parameter of the \begin
command is the name of the environment. This parameter must not be
specified in the list of parameters. Here are some examples:
% po4a: environment multicols {}
% po4a: environment equation
- % po4a: separator env "regex "
- Indicates that an environment should be split according to
the given regular expression.
- % po4a: verbatim environment env
- Indicate that env is a verbatim environment.
Comments and commands will be ignored in this environment.
WRITING DERIVATE MODULES¶
- pre_trans
- post_trans
- translate
- Wrapper around Transtractor's translate, with pre- and
post-processing filters.
- get_leading_command($buffer)
- This function returns:
- A command name
- If no command is found at the beginning of the given buffer, this string will be empty. Only commands that can be separated are considered. The %separated_command hash contains the list of these commands.
- A variant
- This indicates if a variant is used. For example, an asterisk (*) can be added at the end of sections command to specify that they should not be numbered. In this case, this field will contain "*". If there is no variant, the field is an empty string.
- An array of tuples (type of argument, argument)
- The type of argument can be either '{' (for mandatory arguments) or '[' (for optional arguments).
- The remaining buffer
- The rest of the buffer after the removal of this leading command and its arguments. If no command is found, the original buffer is not touched and returned in this field.
- get_trailing_command($buffer)
- The same as get_leading_command, but for commands at the end of a buffer.
- translate_buffer
- Recursively translate a buffer by separating leading and
trailing commands (those which should be translated separately) from the
buffer.
- read
- Overload Transtractor's read
- read_file
- Recursively read a file, appending included files which are
not listed in the @exclude_include array. Included files are searched
using the kpsewhich command from the Kpathsea library.
- parse_definition_file
- Subroutine for parsing a file with po4a directives (definitions for new commands).
- parse_definition_line
- Parse a definition line of the form "% po4a: ".
- is_closed
- parse
- docheader
INTERNAL FUNCTIONS used to write derivated parsers¶
Command and environment functions take the following arguments (in addition to the $self object):- A command name
- A variant
- An array of (type, argument) tuples
- The current environment
% po4a: command command1 parameters generic_environment uses the information specified by register_generic_environment or by adding definition to the TeX file:
% po4a: environment env parameters Both functions will only translate the parameters that were specified as translatable (with a '_'). generic_environment will append the name of the environment to the environment stack and generic_command will append the name of the command followed by an identifier of the parameter (like {#7} or [#2]).
STATUS OF THIS MODULE¶
This module needs more tests. It was tested on a book and with the Python documentation.TODO LIST¶
- Automatic detection of new commands
- The TeX module could parse the newcommand arguments and try to guess the number of arguments, their type and whether or not they should be translated.
- Translation of the environment separator
- When \item is used as an environment separator, the item argument is attached to the following string.
- Some commands should be added to the environment stack
- These commands should be specified by couples. This could allow to specify commands beginning or ending a verbatim environment.
- Others
- Various other points are tagged TODO in the source.
KNOWN BUGS¶
Various points are tagged FIXME in the source.SEE ALSO¶
Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)AUTHORS¶
Nicolas Francois <nicolas.francois@centraliens.net>
COPYRIGHT AND LICENSE¶
Copyright 2004, 2005 by Nicolas FRANCOIS <nicolas.francois@centraliens.net>. This program is free software; you may redistribute it and/or modify it under the terms of GPL (see the COPYING file).2012-05-17 | perl v5.14.2 |