НАЗВАНИЕ¶

Locale::Po4a::AsciiDoc: преобразование документов AsciiDoc в/из PO-файлы

ОПИСАНИЕ¶

Целью проекта po4a (PO for anything, PO везде и для всего) является облегчение процесса перевода (и что более важно — поддержки перевода), используя инструменты gettext в тех случаях, когда их применение может выглядеть неожиданным, например для документации.

Locale::Po4a::AsciiDoc — это модуль, предназначенным для помощи в переводе документации в формате AsciiDoc.

ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ¶

Ниже приведены специфические для данного модуля параметры:

definitions

Имя файла с po4a-определениями (definitions), которые описаны в разделе ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ. Вы можете использовать этот параметр, если добавить эти определения непосредственно в переводимый документ не является возможным.

В файле с определениями строки должны начинаться не, как комментарии, с двух слешей, а сразу с po4a:.

entry

Список атрибутов, разделённых пробелами, значения которых должны переводиться. По умолчанию ни какие атрибуты не считаются переводимыми.

macro

Список определений макросов (macro definitions), разделённых пробелами.

style

Список определений стилей (style definitions), разделённых пробелами.

forcewrap

Включить автоматический перенос строк (кроме дословных (verbatim) блоков), даже если результат может быть в дальнейшем некорректно интерпретирован другими инструментами AsciiDoc.

По умолчанию po4a не будет переносить строки в создаваемых файлах AsciiDoc, поскольку для того, чтобы полученных текст был корректен, требуется ручная проверка, дабы убедиться, что перенос строк не испортит форматирование. Например, рассмотрим следующий элемент списка:

 * длинное предложение, оканчивающееся цифрой 1. Второе предложение.
    

Если перенос строк приведёт к следующей разбивке, то из элемента списка будет выделен в новый нумерованный подсписок. Что ещё хуже, эту проблему могут смогут заметить только носители языка, на котором осуществляется перевод.

 * длинное предложение, оканчивающееся цифрой
   1. Второе предложение.
    

Обратите внимание, что если po4a не будет добавлять дополнительные переносы строк, то это не должно создать ни каких проблем, поскольку эти файлы предназначены, в первую очередь, для обработки автоматическими инструментами. В любом случае, к ним не стоит относится, как к полноценным исходным файлам.

При указании этой опции po4a будет создавать более красивые файлы в формате AsciiDoc, однако это может привести к ошибочному форматированию в документах, созданных на их основе этих файлов.

noimagetargets

По умолчанию, дабы дать переводчикам возможность вставлять в документ локализованные версии изображений, ссылки на них являются переводимыми строками. Это можно изменить, указав данный параметр.

tablecells

Этот параметр является флагом, при указании которого таблицы будут разбиты на ячейки. Разбиение ограничивается только ячейками без какого-либо разбора их содержимого.

compat

Этот параметр переключает правила парсинга в режим совместимости со сторонними инструментами. Доступные варианты: "asciidoc" и "asciidoctor". Asciidoctor предъявляет более строгие требования к документам, например, он требует чтобы линии, стоящие в начале и конце блока, состояли из одинакового количества символов.

nolinting

Отключить сообщения с предложениями по улучшению. Иногда эти советы могут быть контрпродуктивны, т.к. буквальное следование оным может привести к ухудшению читаемости.

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

Список (разделённый запятыми) ключей из YAML-загаловка (Front Matter), которые нужно переводить. Все остальные ключи переводиться не будут. Ключи чувствительны к регистру. Если одновременно заданы и yfm_keys, и yfm_paths, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр yfm_skip_array).

yfm_skip_array

Не переводить значения массивов, присутствующих в YAML-загаловке (Front Matter).

yfm_paths

Список (разделённый запятыми) «путей» из ключей хешей в YAML-заголовке (Front Matter), которые нужно переводить. Все остальные пути переводиться не будут. Пути чувствительны к регистру. Если одновременно заданы и yfm_keys, и yfm_paths, то значения ключей будут переводиться, если они перечислены хотя бы в одном из этих параметров. Значения массивов всегда переводятся (если не задан параметр yfm_skip_array).

ВСТРОЕННЫЕ НАСТРОЙКИ ПОВЕДЕНИЯ¶

Поведение модуля AsciiDoc может быть изменено добавлением команд данному парсеру, находящихся непосредственно в самом документе. Такими командами являются строки, начинающиеся с //po4a:. Поддерживаются следующие команды:

//po4a: macro имя[список атрибутов]

Этот параметр описывает, как именно нужно обрабатывать макрос и его параметры. Имя должно быть действительным именем макроса. Если цель (target) макроса должна быть переведена, то к имени оного должно быть добавлено подчёркивание.

список атрибутов — это список аргументов макроса, разделённых пробелами, которые также должны быть переведены. Этот список состоит либо из чисел, которые задают номера позиционных параметров, либо из непосредственно самих имён оных атрибутов.

Если в начало имени добавлен знак плюс (+), то макрос и все его аргументы переводятся как единое целое. В этом случае нет необходимости задавать список аргументов, но скобки всё равно должны присутствовать.

//po4a: style [список атрибутов]

Этот параметр описывает, какие именно атрибуты стиля должны переводиться.

список атрибутов — это список аргументов, разделённых запятыми, которые должны быть переведены. Этот список содержит либо числа, которые задают номера позиционных параметров, либо непосредственно сами имена оных. При этом первым аргументом считается имя стиля, которое в любом случае не будет переведено.

Если в начало имени стиля добавлен знак плюс (+), то весь список атрибутов переводится как единое целое. В этом случае нет необходимости задавать список атрибутов.

Если в начало имени стиля добавлен знак минус (-), то его атрибуты не будут переводиться.

//po4a: entry имя

Этот параметр делает значение атрибута переводимым. По умолчанию значения атрибутов остаются без перевода.

СОСТОЯНИЕ ЭТОГО МОДУЛЯ¶

Успешно протестирован на простых файлах AsciiDoc.

АВТОРЫ¶

 Николя Франсуа (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>.

Данная программа является свободным программным обеспечением; вы можете распространять и/или изменять её на условиях Универсальной общественной лицензии (GPL) GNU v2.0 или новее (см. файл COPYING).