Locale::Po4a::TeX man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo logo
[printable version]

Locale::Po4a::TeX(3)  User Contributed Perl Documentation Locale::Po4a::TeX(3)

NAME
       Locale::Po4a::TeX - convert TeX documents and derivates from/to PO
       files

DESCRIPTION
       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.

	   Note that there is a difference between verbatim and no_wrap
	   environments.  There is no command and comments analysis in
	   verbatim blocks.

	   If this environment was not already registered, po4a will consider
	   that this environment does not take any parameters.

       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.

	   If this environment was not already registered, po4a will consider
	   that this environment does not take any parameters.

       Using these options permits to override the behaviour of the commands
       defined in the default lists.

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.

	   You can precede the command1 command by

	   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).

	       Note: In this case you don't have to specify which parameters
	       are translatable, but po4a must know the type and number of
	       parameters.

	   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.

	   The parameters argument is a set of [] (to indicate an optional
	   argument) or {} (to indicate a mandatory argument).	You can place
	   an underscore (_) between these brackets to indicate that the
	   parameter must be translated. For example:
	    % po4a: command *chapter [_]{_}

	   This indicates that the chapter command has two parameters: an
	   optional (short title) and a mandatory one, which must both be
	   translated.	If you want to specify that the href command has two
	   mandatory parameters, that you don't want to translate the URL
	   (first parameter), and that you don't want this command to be
	   separated from its paragraph (which allow the translator to move
	   the link in the sentence), you can use:
	    % po4a: command -href {}{_}

	   In this case, the information indicating which arguments must be
	   translated is only used if a paragraph is only composed of this
	   href command.

       % 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

	   As for the commands, env can be preceded by a plus (+) to indicate
	   that the \begin command must be translated with all its arguments.

       % po4a: separator env "regex"
	   Indicates that an environment should be split according to the
	   given regular expression.

	   The regular expression is delimited by quotes.  It should not
	   create any backreference.  You should use (?:) if you need a group.
	   It may also need some escapes.

	   For example, the LaTeX module uses the "(?:&|\\\\)" regular
	   expression to translate separately each cell of a table (lines are
	   separated by '\\' and cells by '&').

	   The notion of environment is expended to the type displayed in the
	   PO file.  This can be used to split on "\\\\" in the first
	   mandatory argument of the title command.  In this case, the
	   environment is title{#1}.

       % po4a: verbatim environment env
	   Indicate that env is a verbatim environment.	 Comments and commands
	   will be ignored in this environment.

	   If this environment was not already registered, po4a will consider
	   that this environment does not take any parameters.

WRITING DERIVATE MODULES
       pre_trans
       post_trans
       translate
	   Wrapper around Transtractor's translate, with pre- and post-
	   processing filters.

	   Comments of a paragraph are inserted as a PO comment for the first
	   translated string of this paragraph.

       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.

	   If a function is defined in %translate_buffer_env for the current
	   environment, this function will be used to translate the buffer
	   instead of translate_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.

	   Except from the file inclusion part, it is a cut and paste from
	   Transtractor's read.

       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: ".

	   See the INLINE CUSTOMIZATION section for more details.

       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

       The first 3 arguments are extracted by get_leading_command or
       get_trailing_command.

       Command and environment functions return the translation of the command
       with its arguments and a new environment.

       Environment functions are called when a \begin command is found. They
       are called with the \begin command and its arguments.

       The TeX module only proposes one command function and one environment
       function: generic_command and generic_environment.

       generic_command uses the information specified by
       register_generic_command or by adding definition to the TeX file:
	% 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).

perl v5.16.3			  2012-05-17		  Locale::Po4a::TeX(3)
[top]

List of man pages available for Gentoo

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net