1Locale::Po4a::TeX(3pm)            Po4a Tools            Locale::Po4a::TeX(3pm)
2
3
4

NAME

6       Locale::Po4a::TeX - convert TeX documents and derivates 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 module derived from this, to
29       describe your format's details.  See the section WRITING DERIVATE
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.  These customizations are described in the INLINE
34       CUSTOMIZATION 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       Using these options permits to override the behaviour of the commands
72       defined in the default lists.
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 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
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 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
105               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
109           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
118           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
124           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
133           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
137       % 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
149           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
152       % po4a: separator env "regex"
153           Indicates that an environment should be split according to the
154           given regular expression.
155
156           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
160           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
164           The notion of environment is expended 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
169       % po4a: verbatim environment env
170           Indicate that env is a verbatim environment.  Comments and commands
171           will be ignored in this environment.
172
173           If this environment was not already registered, po4a will consider
174           that this environment does not take any parameters.
175

WRITING DERIVATE MODULES

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
184       translate
185           Wrapper around Transtractor's translate, with pre- and post-
186           processing filters.
187
188           Comments of a paragraph are inserted as a PO comment for the first
189           translated string of this paragraph.
190
191       get_leading_command($buffer)
192           This function returns:
193
194           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
200           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
207           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
211           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
216       get_trailing_command($buffer)
217           The same as get_leading_command, but for commands at the end of a
218           buffer.
219
220       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
225           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
229       read
230           Overloads Transtractor's read().
231
232       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
237           Except from the file inclusion part, it is a cut and paste from
238           Transtractor's read.
239
240       parse_definition_file
241           Subroutine for parsing a file with po4a directives (definitions for
242           new commands).
243
244       parse_definition_line
245           Parse a definition line of the form "% po4a: ".
246
247           See the INLINE CUSTOMIZATION section for more details.
248
249       is_closed
250       parse
251       docheader
252

INTERNAL FUNCTIONS used to write derivated parsers

254       Command and environment functions take the following arguments (in
255       addition to the $self object):
256
257       A command name
258       A variant
259       An array of (type, argument) tuples
260       The current environment
261
262       The first 3 arguments are extracted by get_leading_command or
263       get_trailing_command.
264
265       Command and environment functions return the translation of the command
266       with its arguments and a new environment.
267
268       Environment functions are called when a \begin command is found. They
269       are called with the \begin command and its arguments.
270
271       The TeX module only proposes one command function and one environment
272       function: generic_command and generic_environment.
273
274       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
278       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
282       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

STATUS OF THIS MODULE

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

TODO LIST

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
299       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
303       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
307       Others
308           Various other points are tagged TODO in the source.
309

KNOWN BUGS

311       Various points are tagged FIXME in the source.
312

SEE ALSO

314       Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
315

AUTHORS

317        Nicolas François <nicolas.francois@centraliens.net>
318
320       Copyright © 2004, 2005 Nicolas FRANÇOIS
321       <nicolas.francois@centraliens.net>.
322
323       This program is free software; you may redistribute it and/or modify it
324       under the terms of GPL (see the COPYING file).
325
326
327
328Po4a Tools                        2021-11-01            Locale::Po4a::TeX(3pm)
Impressum