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

NAME

6       Locale::Po4a::AsciiDoc - convert AsciiDoc documents from/to PO files
7

DESCRIPTION

9       The po4a (PO for anything) project goal is to ease translations (and
10       more interestingly, the maintenance of translations) using gettext
11       tools on areas where they were not expected like documentation.
12
13       Locale::Po4a::AsciiDoc is a module to help the translation of
14       documentation in the AsciiDoc format.
15

OPTIONS ACCEPTED BY THIS MODULE

17       These are this module's particular options:
18
19       definitions
20           The name of a file containing definitions for po4a, as defined in
21           the INLINE CUSTOMIZATION section.  You can use this option if it is
22           not possible to put the definitions in the document being
23           translated.
24
25           In a definitions file, lines must not start by two slashes, but
26           directly by po4a:.
27
28       entry
29           Space-separated list of attribute entries you want to translate.
30           By default, no attribute entries are translatable.
31
32       macro
33           Space-separated list of macro definitions.
34
35       style
36           Space-separated list of style definitions.
37
38       forcewrap
39           Enable automatic line wrapping in non-verbatim blocks, even if the
40           result could be misinterpreted by AsciiDoc formatters.
41
42           By default, po4a will not wrap the produced AsciiDoc files because
43           a manual inspection is mandated to ensure that the wrapping does
44           not change the formatting. Consider for instance the following list
45           item:
46
47            * a long sentence that is ending with a number 1. A second sentence.
48
49           If the wrapping leads to the following presentation, the item is
50           split into a numbered sub-list. To make things worse, only the
51           speakers of the language used in the translation can inspect the
52           situation.
53
54            * a long sentence that is ending with a number
55              1. A second sentence.
56
57           Note that not wrapping the files produced by po4a should not be a
58           problem since those files are meant to be processed automatically.
59           They should not be regarded as source files anyway.
60
61           With this option, po4a will produce better-looking source files,
62           that may lead to possibly erroneous formatted outputs.
63
64       noimagetargets
65           By default, the targets of block images are translatable to give
66           opportunity to make the content point to translated images. This
67           can be stopped by setting this option.
68
69       tablecells
70           This option is a flag that enables sub-table segmentation into cell
71           content.  The segmentation is limited to cell content, without any
72           parsing inside of it.
73
74       compat
75           Switch parsing rules to compatibility with different tools.
76           Available options are "asciidoc" or "asciidoctor". Asciidoctor has
77           stricter parsing rules, such as equality of length of opening and
78           closing block fences.
79
80       nolinting
81           Disable linting messages. When the source code cannot be fixed for
82           clearer document structure, these messages are useless.
83
84       yfm_keys
85           Comma-separated list of keys to process for translation in the YAML
86           Front Matter section. All other keys are skipped. Keys are matched
87           with a case-sensitive match. If yfm_paths and yfm_keys are used
88           together, values are included if they are matched by at least one
89           of the options. Array values are always translated, unless the
90           yfm_skip_array option is provided.
91
92       yfm_skip_array
93           Do not translate array values in the YAML Front Matter section.
94
95       yfm_paths
96           Comma-separated list of hash paths to process for extraction in the
97           YAML Front Matter section, all other paths are skipped. Paths are
98           matched with a case-sensitive match. If yfm_paths and yfm_keys are
99           used together, values are included if they are matched by at least
100           one of the options.  Arrays values are always returned unless the
101           yfm_skip_array option is provided.
102

INLINE CUSTOMIZATION

104       The AsciiDoc module can be customized with lines starting by //po4a:.
105       These lines are interpreted as commands to the parser.  The following
106       commands are recognized:
107
108       //po4a: macro name[attribute list]
109           This describes in detail the parameters of a macro; name must be a
110           valid macro name, and it ends with an underscore if the target must
111           be translated.
112
113           The attribute list argument is a comma separated list which
114           contains information about translatable arguments.  This list
115           contains either numbers, to define positional parameters, or named
116           attributes.
117
118           If a plus sign (+) is prepended to name, then the macro and its
119           arguments are translated as a whole.  There is no need to define
120           attribute list in this case, but brackets must be present.
121
122       //po4a: style [attribute list]
123           This describes in detail which attributes of a style must be
124           translated.
125
126           The attribute list argument is a comma separated list which
127           contains information about translatable arguments.  This list
128           contains either numbers, to define positional parameters, or named
129           attributes.  The first attribute is the style name, it will not be
130           translated.
131
132           If a plus sign (+) is prepended to the style name, then the
133           attribute list is translated as a whole.  There is no need to
134           define translatable attributes.
135
136           If a minus sign (-) is prepended to the style name, then this
137           attribute is not translated.
138
139       //po4a: entry name
140           This declares an attribute entry as being translatable.  By
141           default, they are not translated.
142

STATUS OF THIS MODULE

144       Tested successfully on simple AsciiDoc files.
145

AUTHORS

147        Nicolas François <nicolas.francois@centraliens.net>
148        Denis Barbier <barbier@linuxfr.org>
149
151        Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
152        Copyright © 2012 Denis BARBIER <barbier@linuxfr.org>.
153        Copyright © 2017 Martin Quinson <mquinson#debian.org>.
154
155       This program is free software; you may redistribute it and/or modify it
156       under the terms of GPL (see the COPYING file).
157
158       __END__
159
160       #  LocalWords: Charset charset AsciiDoc tablecells po UTF gettext msgid
161       nostrip
162
163
164
165Po4a Tools                        2023-01-23       Locale::Po4a::AsciiDoc(3pm)
Impressum