LOCALE:...DOC.3PM(1)

📦
version 0.74 · 15 versions
, in alpine 3.23

💖 LOCALE:...DOC.3PM — Locale::Po4a::AsciiDoc 💖

okay so bestie, the manual page here is LOCALE:...DOC.3PM(1), part of the User Contributed Perl Documentation — and honestly? she's a little icon. let's get into it 🫶

✨ NAME ✨

Locale::Po4a::AsciiDoc — the module that converts AsciiDoc documents from/to PO files. that's the whole vibe. 💅

🌸 DESCRIPTION 🌸

so the po4a project — that's "PO for anything", which is lowkey the most main-character name ever — has one goal: make translations easier (and, even more interestingly, make maintaining those translations easier) by using gettext tools on places nobody expected them to show up. like documentation. icon behavior, no cap. 👑

Locale::Po4a::AsciiDoc is the module that helps you translate documentation written in the AsciiDoc format. she's the bestie for this specific job. 🦋

🎀 OPTIONS ACCEPTED BY THIS MODULE 🎀

these are this module's particular options, i.e. her special little talents:

  • definitions — the name of a file containing definitions for po4a, exactly as defined in the INLINE CUSTOMIZATION section. use this option when it's just not possible to put the definitions inside the document you're translating. ok and important: in a definitions file, lines must not start with two slashes — they start directly with po4a:. don't mess that up bestie 🙈
  • entry — space-separated list of attribute entries you want translated. by default, literally zero attribute entries are translatable. none. nada. 💀
  • macro — space-separated list of macro definitions.
  • style — space-separated list of style definitions.
  • forcewrap — enables 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 make sure the wrapping doesn't 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 gets split into a numbered sub-list. and 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.

ngl, note that not wrapping the files produced by po4a should not be a problem, since those files are meant to be processed automatically. they shouldn't be regarded as source files anyway.

with this option, po4a will produce better-looking AsciiDoc files, but it may lead to possibly erroneous formatted outputs. trade-offs, bestie. 💅

  • noimagetargets — by default, the targets of block images are translatable, to give you the opportunity to make the content point to translated images. setting this option stops that. 🖼️
  • tablecells — this option is a flag that enables sub-table segmentation into cell content. the segmentation is limited to cell content, with no parsing inside of it. it's giving "just the surface, don't dig". 🍓
  • compat — switch parsing rules to compatibility with different tools. available options are "asciidoc" or "asciidoctor". heads up: Asciidoctor has stricter parsing rules, such as equality of length of opening and closing block fences. 👀
  • nolinting — disable linting messages. when the source code can't be fixed for a clearer document structure, these messages are useless. so, bye. 💀
  • cleanspaces — remove extra spaces from the source segments in no-wrap mode. this is useful when the translation tools are sensitive to the number of spaces. 🧚
  • 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're 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. periodt.
  • 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're matched by at least one of the options. arrays values are always returned unless the yfm_skip_array option is provided. ⭐

🦋 INLINE CUSTOMIZATION 🦋

bestie this is the fun part — the AsciiDoc module can be customized with lines starting by //po4a:. these lines get interpreted as commands to the parser. here's every command she recognizes:

🌈 //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 containing info 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. no need to define an 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 containing info about translatable arguments. this list contains either numbers, to define positional parameters, or named attributes. the first attribute is the style name, and it will not be translated.

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

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

if a percent sign (%) is appended to the style name, then the style is processed as verbatim. the lines in a paragraph or block of such style are preserved in the po files, and the corresponding entries are marked as no-wrap. 🔥

💜 //po4a: entry name

this declares an attribute entry as being translatable. by default, they are not translated. (we love a little opt-in moment ✨)

👑 STATUS OF THIS MODULE 👑

tested successfully on simple AsciiDoc files. she ate and left no crumbs. 💅

💖 AUTHORS 💖

  • Nicolas François <nicolas.francois@centraliens.net>
  • Denis Barbier <barbier@linuxfr.org>
  • 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 v2.0 or later (see the COPYING file). 🫶

ngl the legal bit is the only part you can't vibe-edit, bestie — that's perl v5.42.0, dated 2025-07-13, straight from the LOCALE:...DOC.3PM(1) page. mwah 💋
📦 where this page comes from