1Locale::Po4a::AsciiDoc(3pm) Po4a Tools Locale::Po4a::AsciiDoc(3pm)
2
6 Locale::Po4a::AsciiDoc - convert AsciiDoc documents from/to PO files
7
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 Locale::Po4a::AsciiDoc is a module to help the translation of
14 documentation in the AsciiDoc format.
15
17 These are this module's particular options:
18 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 In a definitions file, lines must not start by two slashes, but
26 directly by po4a:.
27 entry
29 Space-separated list of attribute entries you want to translate.
30 By default, no attribute entries are translatable.
31 macro
33 Space-separated list of macro definitions.
34 style
36 Space-separated list of style definitions.
37 forcewrap
39 Enable automatic line wrapping in non-verbatim blocks, even if the
40 result could be misinterpreted by AsciiDoc formatters.
41 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 * a long sentence that is ending with a number 1. A second sentence.
48 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 * a long sentence that is ending with a number
55 1. A second sentence.
56 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 With this option, po4a will produce better-looking source files,
62 that may lead to possibly erroneous formatted outputs.
63 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 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 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 nolinting
81 Disable linting messages. When the source code cannot be fixed for
82 clearer document structure, these messages are useless.
83 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 yfm_skip_array
93 Do not translate array values in the YAML Front Matter section.
94 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
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 //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 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 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 //po4a: style [attribute list]
123 This describes in detail which attributes of a style must be
124 translated.
125 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 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 If a minus sign (-) is prepended to the style name, then this
137 attribute is not translated.
138 //po4a: entry name
140 This declares an attribute entry as being translatable. By
141 default, they are not translated.
142
144 Tested successfully on simple AsciiDoc files.
145
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 This program is free software; you may redistribute it and/or modify it
156 under the terms of GPL (see the COPYING file).
157 __END__
159 # LocalWords: Charset charset AsciiDoc tablecells po UTF gettext msgid
161 nostrip
162Po4a Tools 2023-01-23 Locale::Po4a::AsciiDoc(3pm)