1LOCALE::PO4A::TEX.3PM(1U)ser Contributed Perl DocumentatiLoOnCALE::PO4A::TEX.3PM(1)
2
3
4

NAME

6       Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO
7       files
8

DESCRIPTION

10       The po4a (PO for anything) project goal is to ease translations (and
11       more interestingly, the maintenance of translations) using gettext
12       tools on areas where they were not expected like documentation.
13
14       Locale::Po4a::TeX is a module to help the translation of TeX documents
15       into other [human] languages. It can also be used as a base to build
16       modules for TeX-based documents.
17
18       Users should probably use the LaTeX module, which inherits from the TeX
19       module and contains the definitions of common LaTeX commands.
20

TRANSLATING WITH PO4A::TEX

22       This module can be used directly to handle generic TeX documents.  This
23       will split your document in smaller blocks (paragraphs, verbatim
24       blocks, or even smaller like titles or indexes).
25
26       There are some options (described in the next section) that can
27       customize this behavior.  If this doesn't fit to your document format
28       you're encouraged to write your own derivative module from this, to
29       describe your format's details.  See the section WRITING DERIVATIVE
30       MODULES below, for the process description.
31
32       This module can also be customized by lines starting with "% po4a:" in
33       the TeX file. This process is described in the INLINE CUSTOMIZATION
34       section.
35

OPTIONS ACCEPTED BY THIS MODULE

37       These are this module's particular options:
38
39       debug
40           Activate debugging for some internal mechanisms of this module.
41           Use the source to see which parts can be debugged.
42
43       no_wrap
44           Comma-separated list of environments which should not be re-
45           wrapped.
46
47           Note that there is a difference between verbatim and no_wrap
48           environments.  There is no command and comments analysis in
49           verbatim blocks.
50
51           If this environment was not already registered, po4a will consider
52           that this environment does not take any parameters.
53
54       exclude_include
55           Colon-separated list of files that should not be included by \input
56           and \include.
57
58       definitions
59           The name of a file containing definitions for po4a, as defined in
60           the INLINE CUSTOMIZATION section.  You can use this option if it is
61           not possible to put the definitions in the document being
62           translated.
63
64       verbatim
65           Comma-separated list of environments which should be taken as
66           verbatim.
67
68           If this environment was not already registered, po4a will consider
69           that this environment does not take any parameters.
70
71       Use these options to override the default behavior of the defined
72       commands.
73

INLINE CUSTOMIZATION

75       The TeX module can be customized with lines starting by % po4a:.  These
76       lines are interpreted as commands to the parser.  The following
77       commands are recognized:
78
79       % po4a: command command1 alias command2
80           Indicates that the arguments of the command1 command should be
81           treated as the arguments of the command2 command.
82
83       % po4a: command command1 parameters
84           This describes in detail the parameters of the command1 command.
85           This information will be used to check the number of arguments and
86           their types.
87
88           You can precede the command1 command by
89
90           an asterisk (*)
91               po4a will extract this command from paragraphs (if it is
92               located at the beginning or the end of a paragraph).  The
93               translators will then have to translate the parameters that are
94               marked as translatable.
95
96           a plus (+)
97               As for an asterisk, the command will be extracted if it appear
98               at an extremity of a block, but the parameters won't be
99               translated separately.  The translator will have to translate
100               the command concatenated to all its parameters.  This keeps
101               more context, and is useful for commands with small words in
102               parameter, which can have multiple meanings (and translations).
103
104               Note: In this case you don't have to specify which parameters
105               are translatable, but po4a must know the type and number of
106               parameters.
107
108           a minus (-)
109               In this case, the command won't be extracted from any block.
110               But if it appears alone on a block, then only the parameters
111               marked as translatable will be presented to the translator.
112               This is useful for font commands.  These commands should
113               generally not be separated from their paragraph (to keep the
114               context), but there is no reason to annoy the translator with
115               them if a whole string is enclosed in such a command.
116
117           The parameters argument is a set of [] (to indicate an optional
118           argument) or {} (to indicate a mandatory argument).  You can place
119           an underscore (_) between these brackets to indicate that the
120           parameter must be translated. For example:
121            % po4a: command *chapter [_]{_}
122
123           This indicates that the chapter command has two parameters: an
124           optional (short title) and a mandatory one, which must both be
125           translated.  If you want to specify that the href command has two
126           mandatory parameters, that you don't want to translate the URL
127           (first parameter), and that you don't want this command to be
128           separated from its paragraph (which allow the translator to move
129           the link in the sentence), you can use:
130            % po4a: command -href {}{_}
131
132           In this case, the information indicating which arguments must be
133           translated is only used if a paragraph is only composed of this
134           href command.
135
136       % po4a: environment env parameters
137           This defines the parameters accepted by the env environment and
138           specifies the ones to be translated.  This information is later
139           used to check the number of arguments of the \begin command.  The
140           syntax of the parameters argument is the same as described for the
141           others commands.  The first parameter of the \begin command is the
142           name of the environment.  This parameter must not be specified in
143           the list of parameters. Here are some examples:
144            % po4a: environment multicols {}
145            % po4a: environment equation
146
147           As for the commands, env can be preceded by a plus (+) to indicate
148           that the \begin command must be translated with all its arguments.
149
150       % po4a: separator env "regex"
151           Indicates that an environment should be split according to the
152           given regular expression.
153
154           The regular expression is delimited by quotes.  It should not
155           create any back-reference.  You should use (?:) if you need a
156           group.  It may also need some escapes.
157
158           For example, the LaTeX module uses the "(?:&|\\\\)" regular
159           expression to translate separately each cell of a table (lines are
160           separated by '\\' and cells by '&').
161
162           The notion of environment is expanded to the type displayed in the
163           PO file.  This can be used to split on "\\\\" in the first
164           mandatory argument of the title command.  In this case, the
165           environment is title{#1}.
166
167       % po4a: verbatim environment env
168           Indicate that env is a verbatim environment.  Comments and commands
169           will be ignored in this environment.
170
171           If this environment was not already registered, po4a will consider
172           that this environment does not take any parameters.
173

WRITING DERIVATE MODULES

175       pre_trans
176       post_trans
177       add_comment
178           Add a string as a comment to be added around the next translated
179           element.  This is mostly useful to the texinfo module, as comments
180           are automatically handled in TeX.
181
182       translate
183           Wrapper around Transtractor's translate, with pre- and post-
184           processing filters.
185
186           Comments of a paragraph are inserted as a PO comment for the first
187           translated string of this paragraph.
188
189       get_leading_command($buffer)
190           This function returns:
191
192           A command name
193               If no command is found at the beginning of the given buffer,
194               this string will be empty.  Only commands that can be separated
195               are considered.  The %separated_command hash contains the list
196               of these commands.
197
198           A variant
199               This indicates if a variant is used.  For example, an asterisk
200               (*) can be added at the end of sections command to specify that
201               they should not be numbered.  In this case, this field will
202               contain "*".  If there is no variant, the field is an empty
203               string.
204
205           An array of tuples (type of argument, argument)
206               The type of argument can be either '{' (for mandatory
207               arguments) or '[' (for optional arguments).
208
209           The remaining buffer
210               The rest of the buffer after the removal of this leading
211               command and its arguments.  If no command is found, the
212               original buffer is not touched and returned in this field.
213
214       get_trailing_command($buffer)
215           The same as get_leading_command, but for commands at the end of a
216           buffer.
217
218       translate_buffer
219           Recursively translate a buffer by separating leading and trailing
220           commands (those which should be translated separately) from the
221           buffer.
222
223           If a function is defined in %translate_buffer_env for the current
224           environment, this function will be used to translate the buffer
225           instead of translate_buffer().
226
227       read
228           Overloads Transtractor's read().
229
230       read_file
231           Recursively read a file, appending included files which are not
232           listed in the @exclude_include array.  Included files are searched
233           using the kpsewhich command from the Kpathsea library.
234
235           Except from the file inclusion part, it is a cut and paste from
236           Transtractor's read.
237
238       parse_definition_file
239           Subroutine for parsing a file with po4a directives (definitions for
240           new commands).
241
242       parse_definition_line
243           Parse a definition line of the form "% po4a: ".
244
245           See the INLINE CUSTOMIZATION section for more details.
246
247       is_closed
248       parse
249       docheader
250

INTERNAL FUNCTIONS used to write derivative parsers

252       Command and environment functions take the following arguments (in
253       addition to the $self object):
254
255       A command name
256       A variant
257       An array of (type, argument) tuples
258       The current environment
259
260       The first 3 arguments are extracted by get_leading_command or
261       get_trailing_command.
262
263       Command and environment functions return the translation of the command
264       with its arguments and a new environment.
265
266       Environment functions are called when a \begin command is found. They
267       are called with the \begin command and its arguments.
268
269       The TeX module only proposes one command function and one environment
270       function: generic_command and generic_environment.
271
272       generic_command uses the information specified by
273       register_generic_command or by adding definition to the TeX file:
274        % po4a: command command1 parameters
275
276       generic_environment uses the information specified by
277       register_generic_environment or by adding definition to the TeX file:
278        % po4a: environment env parameters
279
280       Both functions will only translate the parameters that were specified
281       as translatable (with a '_').  generic_environment will append the name
282       of the environment to the environment stack and generic_command will
283       append the name of the command followed by an identifier of the
284       parameter (like {#7} or [#2]).
285

STATUS OF THIS MODULE

287       This module needs more tests.
288
289       It was tested on a book and with the Python documentation.
290

TODO LIST

292       Automatic detection of new commands
293           The TeX module could parse the newcommand arguments and try to
294           guess the number of arguments, their type and whether or not they
295           should be translated.
296
297       Translation of the environment separator
298           When \item is used as an environment separator, the item argument
299           is attached to the following string.
300
301       Some commands should be added to the environment stack
302           These commands should be specified by couples.  This can be used to
303           specify commands beginning or ending a verbatim environment.
304
305       Others
306           Various other points are tagged TODO in the source.
307

KNOWN BUGS

309       Various points are tagged FIXME in the source.
310

SEE ALSO

312       Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
313

AUTHORS

315        Nicolas François <nicolas.francois@centraliens.net>
316
318       Copyright © 2004, 2005 Nicolas FRANÇOIS
319       <nicolas.francois@centraliens.net>.
320
321       This program is free software; you may redistribute it and/or modify it
322       under the terms of GPL (see the COPYING file).
323
324
325
326perl v5.36.0                      2023-01-23          LOCALE::PO4A::TEX.3PM(1)
Impressum