.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "LOCALE::PO4A::TEX.3PM 1" .TH LOCALE::PO4A::TEX.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH НАЗВА .IX Header "НАЗВА" Locale::Po4a::TeX — перетворення документів TeX та похідних документів на файли PO, і навпаки .SH ОПИС .IX Header "ОПИС" Метою проєкту po4a (PO для усього) є спрощення перекладу (та, що ще цікавіше, супровід перекладів) за допомогою інструментів gettext у областях, де такий переклад спочатку не передбачався, зокрема у документації. .PP Locale::Po4a::TeX — модуль, який допомагає у перекладі документів TeX іншими мовами (якими розмовляють люди). Модулем можна також скористатися як основою для побудови модулів для заснованих на TeX документів. .PP Ймовірно, користувачам варто скористатися модулем LaTeX, який є спадкоємцем модулі TeX і містити визначення загальних команд LaTeX. .SH "ПЕРЕКЛАД ЗА ДОПОМОГОЮ PO4A::TEX" .IX Header "ПЕРЕКЛАД ЗА ДОПОМОГОЮ PO4A::TEX" Цим модулем можна скористатися безпосередньо для обробки типових документів TeX. Він поділить ваш документ на менші блоки (абзаци, середовища verbatim, заголовки і пункти списків). .PP Передбачено декілька параметрів (які описано у наступному розділі), за допомогою яких можна налаштувати поведінку модуля. Якщо модуль не відповідає формату вашого документа, вам варто написати власний модуль, який походитиме від цього, і у якому ви опишете параметри формату. Опис процедури написання наведено у розділі \fBНАПИСАННЯ ПОХІДНИХ МОДУЛІВ\fR нижче. .PP Цей модуль також можна налаштувати рядками, які починаються з «% po4a:» у файлі TeX. Процедуру описано у розділі \fBНАЛАШТОВУВАННЯ НА МІСЦІ\fR section. .SH "ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ" .IX Header "ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ" Ось параметри, які можна передавати цьому модулю: .IP \fBdebug\fR 4 .IX Item "debug" Задіяти діагностику деяких внутрішніх механізмів цього модуля. Скористайтеся початковим кодом, щоб ознайомитися із частинами, діагностику яких можна виконувати. .IP \fBno_wrap\fR 4 .IX Item "no_wrap" Список відокремлених комами середовищ, у яких не слід змінювати перенесення рядків. .Sp Зауважте, що між середовищами verbatim і no_wrap є різниця. У блоках verbatim не виконується аналіз команд та коментарів. .Sp Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів. .IP \fBexclude_include\fR 4 .IX Item "exclude_include" Список відокремлених двокрапками назв файлів, які не слід включати за допомогою команд \einput і \einclude. .IP \fBdefinitions\fR 4 .IX Item "definitions" Назва файла, що містить визначення для po4a, як це визначено у розділі \fBНАЛАШТОВУВАННЯ НА МІСЦІ\fR. Ви можете скористатися цим параметром, якщо вставляння визначень до документа, який ви перекладаєте, є неможливим. .IP \fBverbatim\fR 4 .IX Item "verbatim" Список відокремлених комами назв середовищ, вміст яких слід відтворювати буквально. .Sp Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів. .PP Скористайтеся цими параметрами для перевизначення типової поведінки визначених команд. .SH "НАЛАШТОВУВАННЯ НА МІСЦІ" .IX Header "НАЛАШТОВУВАННЯ НА МІСЦІ" Налаштувати модуль TeX можна рядками, які починаються з \fB% po4a:\fR. Такі рядки вважатимуться командами, які віддаються засобу обробки. Передбачено такі команди: .IP "\fB% po4a: command\fR \fIкоманда1\fR \fBalias\fR \fIкоманда2\fR" 4 .IX Item "% po4a: command команда1 alias команда2" Вказує на те, що аргументи команди \fIкоманда1\fR слід вважати аргументами команди \fIкоманда2\fR. .IP "\fB% po4a: command\fR \fIкоманда1\fR \fIпараметри\fR" 4 .IX Item "% po4a: command команда1 параметри" Надає змогу докладно описати параметри команди \fIкоманда1\fR. Ці дані буде використано для перевірки кількості аргументів та їхніх типів. .Sp Ви можете вказати перед командою \fIкоманда1\fR .RS 4 .IP "зірочку (\fB*\fR)" 4 .IX Item "зірочку (*)" po4a видобуде цю команду з абзаців (якщо її розташовано на початку або наприкінці абзацу). Перекладачам слід буде перекласти параметри, які позначено як придатні до перекладу. .IP "плюс (\fB+\fR)" 4 .IX Item "плюс (+)" Як і для зірочки, команду буде видобуто, якщо вона стоятиме на початку або наприкінці блоку, але параметри не перекладатимуться окремо. Перекладачеві слід буде перекласти команду, об'єднану із усіма її параметрами. Це надає змогу зберегти більше контексту і корисно для команд із параметрами, які є короткими словами із багатьма значеннями (і перекладами). .Sp Зауваження: у цьому випадку вам не потрібно вказувати, які параметри можна перекладати, але po4a має знати тип і кількість параметрів. .IP "мінус (\fB\-\fR)" 4 .IX Item "мінус (-)" У цьому випадку команда не видобуватиметься з будь\-якого блоку. Але якщо вона цілком формуватиме блок, перекладачеві буде надано можливість перекласти лише параметри, які позначено як придатні до перекладу. Корисно для команд зміни шрифту. Такі команди, зазвичай, не слід відокремлювати від абзацу (щоб зберегти контекст), але немає ніякого сенсу показувати їх перекладачеві, якщо усередині такої команди залишається цілий рядок. .RE .RS 4 .Sp Аргумент \fIпараметри\fR є набором [] (щоб вказати необов'язковий аргумент) або {} (щоб вказати обов'язковий аргумент). Ви можете вказати символи підкреслювання (_) між дужками, щоб позначити, що параметр слід перекладати. Приклад: % po4a: command *chapter [_]{_} .Sp Це вказує на те, що у команди chapter є два параметри: необов'язковий (скорочений заголовок) і обов'язковий, обидва має бути перекладено. Якщо ви хочете вказати, що команда href має два обов'язкові параметри, які ви не хочете перекладати, адресу (перший параметр), і що ви не хочете, щоб цю команду було відокремлено від її абзацу (щоб перекладач міг пересунути посилання у реченні), ви можете зробити так: % po4a: command \-href {}{_} .Sp У цьому випадку відомості, що позначають, які аргументи має бути перекладено, використовуються, лише якщо абзац складається лише з цієї команди href. .RE .IP "\fB% po4a: environment\fR \fIсередовище\fR \fIпараметри\fR" 4 .IX Item "% po4a: environment середовище параметри" За допомогою цього рядка можна визначити параметри, які прийматимуться середовищем \fIсередовище\fR. Ці дані пізніше буде використано для перевірки кількості аргументів команди \&\ebegin і визначення тих параметрів, які слід перекласти. Синтаксис аргументу \fIпараметри\fR є тим самим, який описано для інших команд. Першим параметром команди \ebegin є назва середовища. Цей параметр має бути вказано у списку параметрів. Ось декілька прикладів: % po4a: environment multicols {} % po4a: environment equation .Sp Щодо команд, перед записом \fIсередовище\fR можна додавати «плюс» (+), щоб вказати, що команду \ebegin слід перекладати із усіма її аргументами. .IP "\fB% po4a: separator\fR \fIсередовище\fR \fB""\fR\fIформальний_вираз\fR\fB""\fR" 4 .IX Item "% po4a: separator середовище ""формальний_вираз""" Вказує, що середовище слід розділити за вказаним формальним виразом. .Sp Формальний вираз у лапках. Не повинен містити зворотних посилань. Якщо потрібна група, слід використовувати (?:). Також може знадобитися екранування деяких символів. .Sp Наприклад, у модулі LaTeX використовується формальний вираз "(?:&|\e\e\e\e)" для окремого перекладу усіх комірок таблиці (рядки відокремлюються «\e\e», а комірки — «&»). .Sp Позначення середовища буде розширено до типу, показаного у файлі PO. Цим можна скористатися для поділу за «\e\e\e\e» у першому обов'язковому аргументі команди title. У нашому випадку, середовищем буде title{#1}. .IP "\fB% po4a: verbatim environment\fR \fIсередовище\fR" 4 .IX Item "% po4a: verbatim environment середовище" Вказує, що \fIсередовище\fR є середовищем буквального цитування типу verbatim. Коментарі і команди у такому середовищі ігноруватимуться. .Sp Якщо це середовища ще не було зареєстровано, po4a вважатиме, що у нього немає жодних параметрів. .SH "НАПИСАННЯ ПОХІДНИХ МОДУЛІВ" .IX Header "НАПИСАННЯ ПОХІДНИХ МОДУЛІВ" .IP \fBpre_trans\fR 4 .IX Item "pre_trans" .PD 0 .IP \fBpost_trans\fR 4 .IX Item "post_trans" .IP \fBadd_comment\fR 4 .IX Item "add_comment" .PD Додати рядок як коментар до наступного перекладеного елемента. Здебільшого, корисно для модуля texinfo, оскільки коментарі автоматично обробляються у TeX. .IP \fBtranslate\fR 4 .IX Item "translate" Обгортка навколо translate з Transtractor, з фільтрами попередньої і остаточної обробки. .Sp Коментарі до абзацу буде встановлено як коментар у PO для першого рядка цього абзацу, який можна перекладати. .IP \fBget_leading_command\fR($buffer) 4 .IX Item "get_leading_command($buffer)" Ця функція повертає: .RS 4 .IP "Назву команди" 4 .IX Item "Назву команди" Якщо на початку вказаного буфера не буде знайдено команди, цей рядок буде порожнім. Беруться до уваги лише команди, які можна відокремити. Список таких команд міститься у хеші \f(CW%separated_command\fR. .IP Варіант 4 .IX Item "Варіант" Вказує, чи використано варіант. Наприклад, наприкінці команди section може бути додано зірочку (*) з метою вказати, що відповідний розділ не слід нумерувати. У цьому випадку у цьому полі буде міститися «*». Якщо варіантів немає, у полі міститиметься порожній рядок. .IP "Масив кортежів (тип аргументу, аргумент)" 4 .IX Item "Масив кортежів (тип аргументу, аргумент)" Типом аргументу може бути або «{» (для обов'язкових аргументів), або «[» (для необов'язкових аргументів). .IP "Решту буфера" 4 .IX Item "Решту буфера" Решта буфера після вилучення цієї початкової команди і її аргументів. Якщо команди не буде знайдено, модуль не змінюватиме вмісту початкового буфера і поверне його у це поле. .RE .RS 4 .RE .IP \fBget_trailing_command\fR($buffer) 4 .IX Item "get_trailing_command($buffer)" Те саме, що і \fBget_leading_command\fR, але для команд наприкінці буфера. .IP \fBtranslate_buffer\fR 4 .IX Item "translate_buffer" Рекурсивно перекласти буфер, відокремивши початкову і кінцеву команди (ті, які має бути перекладено окремо) з буфера. .Sp Якщо у \f(CW%translate_buffer_env\fR визначено функцію для поточного середовища, цю функцію буде використано для перекладу буфера замість \fBtranslate_buffer()\fR. .IP \fBread\fR 4 .IX Item "read" Перевантажує \fBread()\fR Transtractor. .IP \fBread_file\fR 4 .IX Item "read_file" Рекурсивно прочитати файл, дописавши включені файли, яких немає у списку масиву \f(CW@exclude_include\fR. Пошук включених файлів відбувається за допомогою команди \fBkpsewhich\fR з бібліотеки Kpathsea. .Sp Окрім частини, пов'язаної із включенням файлів, це буквальна копія read з Transtractor. .IP \fBparse_definition_file\fR 4 .IX Item "parse_definition_file" Підпрограма для обробки файла за допомогою інструкцій po4a (визначень нових команд). .IP \fBparse_definition_line\fR 4 .IX Item "parse_definition_line" Обробляє рядок визначення у формі «% po4a: ». .Sp Докладніший опис наведено у розділі \fBНАЛАШТОВУВАННЯ НА МІСЦІ\fR. .IP \fBis_closed\fR 4 .IX Item "is_closed" .PD 0 .IP \fBparse\fR 4 .IX Item "parse" .IP \fBdocheader\fR 4 .IX Item "docheader" .PD .SH "ВНУТРІШНІ ФУНКЦІЇ, які використовуються для написання похідних обробників" .IX Header "ВНУТРІШНІ ФУНКЦІЇ, які використовуються для написання похідних обробників" Функції команд і середовищ приймають такі аргументи (на додачу до об'єкта \f(CW$self\fR): .IP "Назву команди" 4 .IX Item "Назву команди" .PD 0 .IP Варіант 4 .IX Item "Варіант" .IP "Масив кортежів (тип, аргумент)" 4 .IX Item "Масив кортежів (тип, аргумент)" .IP "Поточне середовище" 4 .IX Item "Поточне середовище" .PD .PP Перші 3 аргументи видобуваються get_leading_command або get_trailing_command. .PP Функції команд і середовищ повертають переклад команди із аргументами і нове середовище. .PP Функції середовищ викликаються, якщо виявлено команду \ebegin. Вони викликаються з командою \ebegin та її аргументами. .PP Модуль TeX пропонує лише одну функцію команд і одну функцію середовищ: generic_command і generic_environment. .PP generic_command використовує інформацію, задану register_generic_command або додаванням визначення до файла TeX: % po4a: command \fIкоманда1\fR \fIпараметри\fR .PP generic_environment використовує інформацію, задану register_generic_environment або додаванням визначення до файла TeX: % po4a: environment \fIсередовище\fR \fIпараметри\fR .PP Обидві функції перекладають лише параметри, які було вказано як придатні до перекладу (за допомогою «_»). generic_environment дописує назву середовища до стосу середовищ, а generic_command дописує назву команди і ідентифікатором параметра (наприклад, {#7} або [#2]). .SH "СТАН ЦЬОГО МОДУЛЯ" .IX Header "СТАН ЦЬОГО МОДУЛЯ" Цей модуль потребує тестування. .PP Його було перевірено на одній книзі та документації до Python. .SH "СПИСОК ЗАВДАНЬ" .IX Header "СПИСОК ЗАВДАНЬ" .IP "Автоматичне виявлення нових команд" 4 .IX Item "Автоматичне виявлення нових команд" Модуль TeX міг би обробляти аргументи newcommand і намагатися вгадати кількість аргументів, їхній тип та те, чи слід їх перекладати. .IP "Переклад роздільника середовищ" 4 .IX Item "Переклад роздільника середовищ" Якщо \eitem використано як роздільник середовищ, аргумент item має долучатися до наступного рядка. .IP "Деякі команди має бути додано до стека середовища" 4 .IX Item "Деякі команди має бути додано до стека середовища" Ці команди має бути вказано парами. Цим можна скористатися для визначення команд, які розпочинають та завершують середовище verbatim. .IP Інше 4 .IX Item "Інше" Інші корисні нововведення вказано у файлі TODO архіву із початковим кодом. .SH "ВІДОМІ ВАДИ" .IX Header "ВІДОМІ ВАДИ" Вади вказано у файлі FIXME архіву із початковим кодом. .SH "ТАКОЖ ПЕРЕГЛЯНЬТЕ" .IX Header "ТАКОЖ ПЕРЕГЛЯНЬТЕ" \&\fBLocale::Po4a::LaTeX\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7) .SH АВТОРИ .IX Header "АВТОРИ" .Vb 1 \& Nicolas François .Ve .SH "АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ" .IX Header "АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ" © Nicolas FRANÇOIS , 2004, 2005. .PP Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до неї зміни за умов дотримання GPL версії 2.0 або пізнішої (див. файл COPYING).