1Locale::Po4a::TeX(3) User Contributed Perl Documentation Locale::Po4a::TeX(3)
2
6 Locale::Po4a::TeX - Convert TeX documents and derivates from/to PO
7 files
8
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 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 Users should probably use the LaTeX module, which inherite from the TeX
19 module and contains the definitions of common LaTeX commands.
20
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 There are some options (described in the next section) that can custom‐
27 ize this behavior. If this doesn't fit to your document format you're
28 encouraged to write your own module derived from this, to describe your
29 format's details. See the section "Writing derivate modules" below,
30 for the process description.
31 This module can also be customized by lines starting with "% po4a:" in
33 the TeX file. These customizations are described in the INLINE CUS‐
34 TOMIZATION section.
35
37 These are this module's particular options:
38 debug
40 Activate debugging for some internal mechanisms of this module.
41 Use the source to see which parts can be debugged.
42 no_wrap
44 Coma-separated list of environments which should not be re-wrapped.
45 Note that there is a difference between verbatim and no_wrap envi‐
47 ronments. There is no command and comments analysis in verbatim
48 blocks.
49 If this environment was not already registered, po4a will consider
51 that this environment does not take any parameters.
52 exclude_include
54 Colon-separated list of files that should not be included by \input
55 and \include.
56 definitions
58 The name of a file containing definitions for po4a, as defined in
59 the INLINE CUSTOMIZATION section. You can use this option if it is
60 not possible to put the definitions in the document being trans‐
61 lated.
62 verbatim
64 Coma-separated list of environments which should be taken as verba‐
65 tim.
66 If this environment was not already registered, po4a will consider
68 that this environment does not take any parameters.
69 Using these options permits to override the behaviour of the commands
71 defined in the default lists.
72
74 The TeX module can be customized with lines starting by "% po4a:".
75 These lines are interpreted as commands to the parser. The following
76 commands are recognized:
77 % po4a: command command1 alias command2
79 Indicates that the arguments of the command1 command should be
80 treated as the arguments of the command2 command.
81 % po4a: command command1 parameters
83 This permit to describe in detail the parameters of the command1
84 command. This information will be used to check the number of
85 arguments and their types.
86 You can precede the command1 command by
88 an asterisk (*)
90 po4a will extract this command from paragraphs (if it is
91 located at the beginning or the end of a paragraph). The
92 translators will then have to translate the parameters that are
93 marked as translatable.
94 a plus (+)
96 As for an asterisk, the command will be extracted if it appear
97 at an extremity of a block, but the parameters won't be trans‐
98 lated separately. The translator will have to translate the
99 command concatenated to all its parameters. This permits to
100 keep more context, and is usefull for commands with small words
101 in parameter, which can have multiple meanings (and transla‐
102 tions).
103 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 a minus (-)
109 In this case, the command won't be extracted from any block.
110 But if it appear alone on a bloc, then only the parameters
111 marked as translatable will be presented to the translator.
112 This is usefull for font command. These commands should gener‐
113 ally not be separated from their paragraph (to keep the con‐
114 text), but there is no reason to annoy the translator with them
115 if a whole string is enclosed in such a command.
116 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 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 sepa‐
128 rated from its paragraph (which allow the translator to move the
129 link in the sentence), you can use:
130 % po4a: command -href {}{_}
131 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 % po4a: environment env parameters
137 This permits to define the parameters accepted by the env environ‐
138 ment. This information is latter used to check the number of argu‐
139 ments of the \begin command, and permit to specify which one must
140 be translated. The syntax of the parameters argument is the same
141 as described for the commands. The first parameter of the \begin
142 command is the name of the environment. This parameter must not be
143 specified in the list of parameters. Here are some examples:
144 % po4a: environment multicols {}
145 % po4a: environment equation
146 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 % po4a: separator env "regex"
151 Indicates that an environment should be split according to the
152 given regular expression.
153 The regular expression is delimited by quotes. It should not cre‐
155 ate any backreference. You should use (?:) if you need a group.
156 It may also need some escapes.
157 For example, the LaTeX module uses the "(?:&⎪\\\\)" regular expres‐
159 sion to translate separately each cell of a table (lines are sepa‐
160 rated by '\\' and cells by '&').
161 The notion of environment is expended to the type displayed in the
163 PO file. This can be used to split on "\\\\" in the first manda‐
164 tory argument of the title command. In this case, the environment
165 is title{#1}.
166 % po4a: verbatim environment env
168 Indicate that env is a verbatim environment. Comments and commands
169 will be ignored in this environment.
170 If this environment was not already registered, po4a will consider
172 that this environment does not take any parameters.
173
175 pre_trans
176 post_trans
177 translate
178 Wrapper around Transtractor's translate, with pre- and post-pro‐
179 cessing filters.
180 Comments of a paragraph are inserted as a PO comment for the first
182 translated string of this paragraph.
183 get_leading_command($buffer)
185 This function returns:
186 A command name
188 If no command is found at the beginning of the given buffer,
189 this string will be empty. Only commands that can be separated
190 are considered. The %separated_command hash contains the list
191 of these commands.
192 A variant
194 This indicate if a variant is used. For example, an asterisk
195 (*) can be added at the end of sections command to specify that
196 they should not be numbered. In this case, this field will
197 contain "*". If there is no variant, the field is an empty
198 string.
199 An array of tuples (type of argument, argument)
201 The type of argument can be either '{' (for mandatory argu‐
202 ments) or '[' (for optional arguments).
203 The remaining buffer
205 The rest of the buffer after the removal of this leading com‐
206 mand and its arguments. If no command is found, the original
207 buffer is not touched and returned in this field.
208 get_trailing_command($buffer)
210 The same as get_leading_command, but for commands at the end of a
211 buffer.
212 translate_buffer
214 Recursively translate a buffer by separating leading and trailing
215 commands (those which should be translated separately) from the
216 buffer.
217 read
219 Overload Transtractor's read
220 read_file
222 Recursively read a file, appending included files which are not
223 listed in the @exclude_include array. Included files are searched
224 in the directory of the input document or in a directory listed in
225 the TEXINPUTS environment variable.
226 Except from the file inclusion part, it is a cut and paste from
228 Transtractor's read.
229 parse_definition_file
231 Subroutine for parsing a file with po4a directive (definitions for
232 newcommands).
233 parse_definition_line
235 Parse a definition line of the form "% po4a: ".
236 See the INLINE CUSTOMIZATION section for more details.
238 is_closed
240 docheader
241
243 Command and environment functions take the following arguments (in
244 addition to the $self object):
245 A command name
247 A variant
248 An array of (type, argument) tuples
249 The current environment
250 The first 3 arguments are extracted by get_leading_command or
252 get_trailing_command.
253 Command and environment functions return the translation of the command
255 with its arguments and a new environment.
256 Environment functions are called when a \begin command is found. They
258 are called with the \begin command and its arguments.
259 The TeX module only proposes one command function and one environment
261 function: generic_command and generic_environment.
262 generic_command uses the information specified by register_generic_com‐
264 mand or by adding definition to the TeX file:
265 % po4a: command command1 parameters
266 generic_environment uses the information specified by regis‐
268 ter_generic_environment or by adding definition to the TeX file:
269 % po4a: environment env parameters
270 Both functions will only translate the parameters that were specified
272 as translatable (with a '_'). generic_environment will append the name
273 of the environment to the environment stack and generic_command will
274 append the name of the command followed by an identifier of the parame‐
275 ter (like {#7} or [#2]).
276
278 This module needs more tests.
279 It was tested on a book and with the Python documentation.
281
283 Automatic detection of new commands
284 The TeX module could parse the newcommand arguments and try to
285 guess the number of arguments, their type and whether or not they
286 should be translated.
287 Tranlation of the environment separator
289 When \item is used as an environment separator, the item argument
290 is attached to the following string.
291 Some commands should be added to the environment stack
293 These commands should be specified by couples. This could allow to
294 specify commands beginning or ending a verbatim environment.
295 Others
297 Various other points are tagged TODO in the source.
298
300 Various points are tagged FIXME in the source.
301
303 po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::LaTeX(3pm).
304
306 Nicolas François <nicolas.francois@centraliens.net>
307
309 Copyright 2004, 2005 by Nicolas FRANÇOIS <nicolas.francois@cen‐
310 traliens.net>.
311 This program is free software; you may redistribute it and/or modify it
313 under the terms of GPL (see the COPYING file).
314perl v5.8.8 2008-06-01 Locale::Po4a::TeX(3)