1Locale::Po4a::TeX(3pm) Po4a Tools Locale::Po4a::TeX(3pm)
2
6 Locale::Po4a::TeX - convert TeX documents and derivatives 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 inherits 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
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 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
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 Comma-separated list of environments which should not be re-
45 wrapped.
46 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 If this environment was not already registered, po4a will consider
52 that this environment does not take any parameters.
53 exclude_include
55 Colon-separated list of files that should not be included by \input
56 and \include.
57 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 verbatim
65 Comma-separated list of environments which should be taken as
66 verbatim.
67 If this environment was not already registered, po4a will consider
69 that this environment does not take any parameters.
70 Using these options permits to override the behaviour of the commands
72 defined in the default lists.
73
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 % 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 % po4a: command command1 parameters
84 This permit to describe in detail the parameters of the command1
85 command. This information will be used to check the number of
86 arguments and their types.
87 You can precede the command1 command by
89 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 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 permits
101 to keep more context, and is useful for commands with small
102 words in parameter, which can have multiple meanings (and
103 translations).
104 Note: In this case you don't have to specify which parameters
106 are translatable, but po4a must know the type and number of
107 parameters.
108 a minus (-)
110 In this case, the command won't be extracted from any block.
111 But if it appears alone on a block, then only the parameters
112 marked as translatable will be presented to the translator.
113 This is useful for font commands. These commands should
114 generally not be separated from their paragraph (to keep the
115 context), but there is no reason to annoy the translator with
116 them if a whole string is enclosed in such a command.
117 The parameters argument is a set of [] (to indicate an optional
119 argument) or {} (to indicate a mandatory argument). You can place
120 an underscore (_) between these brackets to indicate that the
121 parameter must be translated. For example:
122 % po4a: command *chapter [_]{_}
123 This indicates that the chapter command has two parameters: an
125 optional (short title) and a mandatory one, which must both be
126 translated. If you want to specify that the href command has two
127 mandatory parameters, that you don't want to translate the URL
128 (first parameter), and that you don't want this command to be
129 separated from its paragraph (which allow the translator to move
130 the link in the sentence), you can use:
131 % po4a: command -href {}{_}
132 In this case, the information indicating which arguments must be
134 translated is only used if a paragraph is only composed of this
135 href command.
136 % po4a: environment env parameters
138 This permits to define the parameters accepted by the env
139 environment. This information is later used to check the number of
140 arguments of the \begin command, and permit to specify which one
141 must be translated. The syntax of the parameters argument is the
142 same as described for the others commands. The first parameter of
143 the \begin command is the name of the environment. This parameter
144 must not be specified in the list of parameters. Here are some
145 examples:
146 % po4a: environment multicols {}
147 % po4a: environment equation
148 As for the commands, env can be preceded by a plus (+) to indicate
150 that the \begin command must be translated with all its arguments.
151 % po4a: separator env "regex"
153 Indicates that an environment should be split according to the
154 given regular expression.
155 The regular expression is delimited by quotes. It should not
157 create any backreference. You should use (?:) if you need a group.
158 It may also need some escapes.
159 For example, the LaTeX module uses the "(?:&|\\\\)" regular
161 expression to translate separately each cell of a table (lines are
162 separated by '\\' and cells by '&').
163 The notion of environment is expanded to the type displayed in the
165 PO file. This can be used to split on "\\\\" in the first
166 mandatory argument of the title command. In this case, the
167 environment is title{#1}.
168 % po4a: verbatim environment env
170 Indicate that env is a verbatim environment. Comments and commands
171 will be ignored in this environment.
172 If this environment was not already registered, po4a will consider
174 that this environment does not take any parameters.
175
177 pre_trans
178 post_trans
179 add_comment
180 Add a string as a comment to be added around the next translated
181 element. This is mostly useful to the texinfo module, as comments
182 are automatically handled in TeX.
183 translate
185 Wrapper around Transtractor's translate, with pre- and post-
186 processing filters.
187 Comments of a paragraph are inserted as a PO comment for the first
189 translated string of this paragraph.
190 get_leading_command($buffer)
192 This function returns:
193 A command name
195 If no command is found at the beginning of the given buffer,
196 this string will be empty. Only commands that can be separated
197 are considered. The %separated_command hash contains the list
198 of these commands.
199 A variant
201 This indicates if a variant is used. For example, an asterisk
202 (*) can be added at the end of sections command to specify that
203 they should not be numbered. In this case, this field will
204 contain "*". If there is no variant, the field is an empty
205 string.
206 An array of tuples (type of argument, argument)
208 The type of argument can be either '{' (for mandatory
209 arguments) or '[' (for optional arguments).
210 The remaining buffer
212 The rest of the buffer after the removal of this leading
213 command and its arguments. If no command is found, the
214 original buffer is not touched and returned in this field.
215 get_trailing_command($buffer)
217 The same as get_leading_command, but for commands at the end of a
218 buffer.
219 translate_buffer
221 Recursively translate a buffer by separating leading and trailing
222 commands (those which should be translated separately) from the
223 buffer.
224 If a function is defined in %translate_buffer_env for the current
226 environment, this function will be used to translate the buffer
227 instead of translate_buffer().
228 read
230 Overloads Transtractor's read().
231 read_file
233 Recursively read a file, appending included files which are not
234 listed in the @exclude_include array. Included files are searched
235 using the kpsewhich command from the Kpathsea library.
236 Except from the file inclusion part, it is a cut and paste from
238 Transtractor's read.
239 parse_definition_file
241 Subroutine for parsing a file with po4a directives (definitions for
242 new commands).
243 parse_definition_line
245 Parse a definition line of the form "% po4a: ".
246 See the INLINE CUSTOMIZATION section for more details.
248 is_closed
250 parse
251 docheader
252
254 Command and environment functions take the following arguments (in
255 addition to the $self object):
256 A command name
258 A variant
259 An array of (type, argument) tuples
260 The current environment
261 The first 3 arguments are extracted by get_leading_command or
263 get_trailing_command.
264 Command and environment functions return the translation of the command
266 with its arguments and a new environment.
267 Environment functions are called when a \begin command is found. They
269 are called with the \begin command and its arguments.
270 The TeX module only proposes one command function and one environment
272 function: generic_command and generic_environment.
273 generic_command uses the information specified by
275 register_generic_command or by adding definition to the TeX file:
276 % po4a: command command1 parameters
277 generic_environment uses the information specified by
279 register_generic_environment or by adding definition to the TeX file:
280 % po4a: environment env parameters
281 Both functions will only translate the parameters that were specified
283 as translatable (with a '_'). generic_environment will append the name
284 of the environment to the environment stack and generic_command will
285 append the name of the command followed by an identifier of the
286 parameter (like {#7} or [#2]).
287
289 This module needs more tests.
290 It was tested on a book and with the Python documentation.
292
294 Automatic detection of new commands
295 The TeX module could parse the newcommand arguments and try to
296 guess the number of arguments, their type and whether or not they
297 should be translated.
298 Translation of the environment separator
300 When \item is used as an environment separator, the item argument
301 is attached to the following string.
302 Some commands should be added to the environment stack
304 These commands should be specified by couples. This could allow to
305 specify commands beginning or ending a verbatim environment.
306 Others
308 Various other points are tagged TODO in the source.
309
311 Various points are tagged FIXME in the source.
312
314 Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
315
317 Nicolas François <nicolas.francois@centraliens.net>
318
320 Copyright © 2004, 2005 Nicolas FRANÇOIS
321 <nicolas.francois@centraliens.net>.
322 This program is free software; you may redistribute it and/or modify it
324 under the terms of GPL (see the COPYING file).
325Po4a Tools 2022-01-21 Locale::Po4a::TeX(3pm)