Ubuntu Manpage: Locale::Po4a::AsciiDoc - convert AsciiDoc documents from/to PO files

NAME

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

DESCRIPTION

       The po4a (PO for anything) project goal is to ease translations (and more interestingly,
       the maintenance of translations) using gettext tools on areas where they were not expected
       like documentation.

       Locale::Po4a::AsciiDoc is a module to help the translation of documentation in the
       AsciiDoc format.

OPTIONS ACCEPTED BY THIS MODULE

These are this module's particular options:

definitions
The name of a file containing definitions for po4a, as defined in the INLINE
CUSTOMIZATION section. You can use this option if it is not possible to put the
definitions in the document being translated.

In a definitions file, lines must not start by two slashes, but directly by po4a:.

entry
Space-separated list of attribute entries you want to translate. By default, no
attribute entries are translatable.

macro
Space-separated list of macro definitions.

style
Space-separated list of style definitions.

forcewrap
Enable automatic line wrapping in non-verbatim blocks, even if the result could be
misinterpreted by AsciiDoc formatters.

By default, po4a will not wrap the produced AsciiDoc files because a manual inspection
is mandated to ensure that the wrapping does not change the formatting. Consider for
instance the following list item:

* a long sentence that is ending with a number 1. A second sentence.

If the wrapping leads to the following presentation, the item is split into a numbered
sub-list. To make things worse, only the speakers of the language used in the
translation can inspect the situation.

* a long sentence that is ending with a number
1. A second sentence.

Note that not wrapping the files produced by po4a should not be a problem since those
files are meant to be processed automatically. They should not be regarded as source
files anyway.

With this option, po4a will produce better-looking source files, that may lead to
possibly erroneous formatted outputs.

noimagetargets
By default, the targets of block images are translatable to give opportunity to make
the content point to translated images. This can be stopped by setting this option.

tablecells
This option is a flag that enables sub-table segmentation into cell content. The
segmentation is limited to cell content, without any parsing inside of it.

compat
Switch parsing rules to compatibility with different tools. Available options are
"asciidoc" or "asciidoctor". Asciidoctor has stricter parsing rules, such as equality
of length of opening and closing block fences.

nolinting
Disable linting messages. When the source code cannot be fixed for clearer document
structure, these messages are useless.

yfm_keys
Comma-separated list of keys to process for translation in the YAML Front Matter
section. All other keys are skipped. Keys are matched with a case-sensitive match. If
yfm_paths and yfm_keys are used together, values are included if they are matched by
at least one of the options. Array values are always translated, unless the
yfm_skip_array option is provided.

yfm_skip_array
Do not translate array values in the YAML Front Matter section.

yfm_paths
Comma-separated list of hash paths to process for extraction in the YAML Front Matter
section, all other paths are skipped. Paths are matched with a case-sensitive match.
If yfm_paths and yfm_keys are used together, values are included if they are matched
by at least one of the options. Arrays values are always returned unless the
yfm_skip_array option is provided.

INLINE CUSTOMIZATION

The AsciiDoc module can be customized with lines starting by //po4a:. These lines are
interpreted as commands to the parser. The following commands are recognized:

//po4a: macro name[attribute list]
This describes in detail the parameters of a macro; name must be a valid macro name,
and it ends with an underscore if the target must be translated.

The attribute list argument is a comma separated list which contains information about
translatable arguments. This list contains either numbers, to define positional
parameters, or named attributes.

If a plus sign (+) is prepended to name, then the macro and its arguments are
translated as a whole. There is no need to define attribute list in this case, but
brackets must be present.

//po4a: style [attribute list]
This describes in detail which attributes of a style must be translated.

The attribute list argument is a comma separated list which contains information about
translatable arguments. This list contains either numbers, to define positional
parameters, or named attributes. The first attribute is the style name, it will not
be translated.

If a plus sign (+) is prepended to the style name, then the attribute list is
translated as a whole. There is no need to define translatable attributes.

If a minus sign (-) is prepended to the style name, then this attribute is not
translated.

//po4a: entry name
This declares an attribute entry as being translatable. By default, they are not
translated.

STATUS OF THIS MODULE

       Tested successfully on simple AsciiDoc files.

AUTHORS

        Nicolas François <nicolas.francois@centraliens.net>
        Denis Barbier <barbier@linuxfr.org>

COPYRIGHT AND LICENSE

        Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
        Copyright © 2012 Denis BARBIER <barbier@linuxfr.org>.
        Copyright © 2017 Martin Quinson <mquinson#debian.org>.

       This program is free software; you may redistribute it and/or modify it under the terms of
       GPL (see the COPYING file).

       __END__

       #  LocalWords: Charset charset AsciiDoc tablecells po UTF gettext msgid nostrip