Wstęp

po4a-build.conf opisuje sposób "po4a-build" budowania tłumaczonej i nietłumaczonej dokumentacji ze zbioru nieprzetłumaczonych dokumentów źródłowych i odpowiadających im plików PO.

Wszystkie dostępne formaty i wszystkie dostępne kombinacje można zawrzeć w pojedynczym pliku konfiguracyjnym po4a-build.conf i w pojedynczym wywołaniu programu "po4a-build". Jednakże można również rozdzielić katalogi po/ i używać oddzielnego pliku konfiguracji dla każdego uruchomienia (należy wtedy za każdym razem wywołać "po4a-build -f PLIK").

Proszę zauważyć, że chociaż po4a-build umożliwia obsługę tłumaczeń komunikatów wyjściowych skryptów powłoki, to po4a-build.conf nie wspiera tego. po4a-build.conf jest związany tylko z tłumaczeniami statycznej zawartości, na przykład stron podręcznika ekranowego.

Proszę przeczytać po4a-runtime(7), aby dowiedzieć się o wspieraniu przez po4a-build tłumaczeń komunikatów skryptów powłoki.

Obsługiwane formaty

Obecnie "po4a-build" obsługuje następujące kombinacje:

DocBook XML dla sekcji 1 i 3

Typically used for manpages for shell scripts or other interpreters that do not have their own documentation format like POD. Suitable XML can be generated directly from an existing manpage using "doclifter"(1) and "po4a-build" will then generate a POT file with no extra workload. The POT file can then be offered for translation and the PO files added to the relevant po/ directory. "po4a-build" will then prepare not only the untranslated manpage from the "doclifter" XML but also use "po4a" to prepare translated XML from the PO files and then build translated manpages from the XML.

Strony podręcznika są generowane przy użyciu domyślnych ustawień docbook-xsl. Użyty arkusz stylów można zmienić za pomocą ustawienia "XSLFILE" pliku konfiguracyjnego "po4a-build".

DocBook XML dla HTML

Arkusz stylów używany do wygenerowania ostatecznego HTML-a można zmienić za pomocą ustawienia "HTMLXSL" pliku konfiguracyjnego "po4a-build"; można też użyć domyślnego arkusza.

POD dla sekcji 1, 3, 5 oraz 7

pod2man jest używany do konwersji zawartości POD dla każdej z obsługiwanych sekcji.

Prosimy użyć "PODFILE" dla sekcji 1, "PODMODULES" dla sekcji 3, "POD5FILES" dla sekcji 5, "POD7FILES" dla sekcji 7.

W przypadku zawartości sekcji 5 lub 7 (które zazwyczaj wymagają nazwy pliku używanego również w przypadku zawartości sekcji 1), jeśli częścią nazwy pliku jest 5 lub 7, to zostaną one automatycznie usunięte z nazwy pliku (łącznie z jakimkolwiek rozszerzeniem nazwy pliku).

Na przykład, aby przygotować /usr/share/man/man7/po4a.7.gz:

 # pliki POD dla sekcji 7
 POD7FILES="doc/po4a.7.pod"

Zawartość pliku

Kolejność występowania zmiennych konfiguracji w pliku jest dowolna.

Jakakolwiek zawartość po znaku ``#'' jest ignorowana.

Wartości, które zawsze będą puste, można usunąć z pliku.

Niektóre pola konfiguracji są wymagane - po4a-build może nic nie zrobić, jeśli pola te nie będą wypełnione.

CONFIG

Wymagany.

Nazwa i lokalizacja (tymczasowego) pliku konfiguracyjnego "po4a", który "po4a-build" wygeneruje i którym będzie zarządzał. Pliku tego nie trzeba dodawać do systemu kontroli wersji i może być czyszczony podczas budowania pakietu.

 # nazwa i lokalizacja pliku konfiguracji
 CONFIG="_build/po4a.config"

PODIR

Wymagany.

Katalog zawierający pliki PO WSZYSTKICH tłumaczeń obsługiwany przez ten plik konfiguracyjny. Wszystkie komunikaty będą połączone do jednego pliku POT w tym katalogu, a wszystkie pliki PO połączone z tym plikiem POT. Każdy próg KEEP (patrz niżej) będzie stosowany do wszystkich komunikatów ze wszystkich plików wejściowych podanych w tym pliku i do wszystkich plików PO w tym katalogu. Katalog nie musi się nazywać ``po''. Proszę jednakże zauważyć, że niektóre narzędzia do generowania statystyk oczekują, że katalog będzie się nazywał ``po'', dlatego zalecamy używanie tej nazwy.

 # pkatalog po stron podręcznika/dokumentacji
 PODIR="po/pod"

POTFILE

Wymagany.

Ścieżka do pliku POT (względna w stosunku do lokalizacji tego pliku konfiguracyjnego), który będzie generowany, zarządzany i aktualizowany przez "po4a-build".

 # ścieżka do pliku POT
 POTFILE="po/pod/po4a-pod.pot"

BASEDIR

Wymagany.

Katalog bazowy do zapisywania przetłumaczonej zawartości.

 # katalog bazowy dla wygenerowanych plików, np. plików doc
 BASEDIR="_build"

BINARIES

Wymagany.

Nawet jeśli budowany jest tylko jeden pakiet, wymagane jest podanie co najmniej jednej wartości w tej zmiennej.

Wartość tego pola może być przypadkowa, ale zazwyczaj zawiera nazwę pakietu. Wygenerowane dokumenty pojawią się w podkatalogach BASEDIR/BINARIES:

 _build/po4a/man/man1/foo.1

Jeśli pakiet buduje więcej niż jeden pakiet binarny (tj. jeden pakiet źródłowy i wiele plików *.deb lub *.rpm), to to pole może pomóc w rozdzielaniu zawartości każdego pakietu, ułatwiając tym samym automatyzację procesu budowania.

Łańcuchy znaków należy rozdzielać spacjami.

 # pakiety binarne, które będą zawierać wygenerowane strony podręcznika
 BINARIES="po4a"

KEEP

Wartość przekazywana bezpośrednio do "po4a -k" określająca procentowy próg tłumaczeń pozwalający zachować tłumaczenie (w przypadku nieprzekroczenia progu wygenerowany przetłumaczony dokument jest usuwany). Proszę zostawić to pole puste lub usunąć go, aby użyć wartości domyślnej (80%), albo ustawić wartość na zero, aby wymusić włączenie pełnej zawartości, nawet kompletnie nieprzetłumaczonej.

Aby mieć pełny wpływ na to zachowanie. prosimy ostrożnie przypisywać pliki do zmiennych w pliku konfiguracyjnym po4a-build.conf.

Proszę zauważyć, że umieszczenie wielu plików w jednym pliku POT może być wygodniejsze dla tłumaczy, zwłaszcza jeżeli pliki te mają wspólne akapity. Z drugiej zaś strony pliki POT z tysiącami komunikatów do przetłumaczenia zniechęcają tłumaczy i prowadzą do długotrwałego okresu wstrzymania zmian oryginalnych komunikatów.

 # minimalny procentowy próg tłumaczeń pozwalający zapisać plik wynikowy
 KEEP=

XMLMAN1

Nazwy plików DocBook XML do wygenerowania w sekcji 1. Nazwy plików powinny być rozdzielone spacjami. Wszystkie pliki powinny się znajdować w katalogu XMLDIR.

Powszechną praktyką jest składanie wielu plików XML w jedną książkę w celu dostarczenia spisu treści itp. Jeśli książka zawiera pliki podane również w XMLMAN3, tutaj należy podać tylko pliki należące do sekcji 1, a nie plik z nazwą całej książki. Jeśli książka składa się tylko z tej sekcji, należy podać plik z nazwą całej książki.

 # pliki DocBook XML do sekcji 1
 XMLMAN1="po4a-build.xml po4aman-display-po.xml po4apod-display-po.xml"

XMLMAN3

Nazwy plików DocBook XML do wygenerowania w sekcji 3. Nazwy plików powinny być rozdzielone spacjami. Wszystkie pliki powinny się znajdować w katalogu XMLDIR.

Powszechną praktyką jest składanie wielu plików XML w jedną książkę w celu dostarczenia spisu treści itp. Jeśli książka zawiera pliki podane również w XMLMAN1, tutaj należy podać tylko pliki należące do sekcji 3, a nie plik z nazwą całej książki. Jeśli książka składa się tylko z tej sekcji, należy podać plik z nazwą całej książki.

 # pliki DocBook XML do sekcji 3
 XMLMAN3=""

XMLDIR

Lokalizacja wszystkich plików DocBook XML. Obecnie "po4a-build" oczekuje, że będzie w stanie znaleźć wszystkie pliki wymienione w XMLMAN1 i XMLMAN3, szukając w tym katalogu plików *.xml.

Musi być podane, jeśli używa się XMLMAN1 lub XMLMAN3. Ścieżki są względne w stosunku do lokalizacji pliku konfiguracji.

 # lokalizacja plików XML
 XMLDIR="share/doc/"

XMLPACKAGES

Które pakiety, z listy podanej w BINARIES, używają źródłowego XML-a.

Jeśli wypełniono XMLMAN1 lub XMLMAN3, należy wypełnić również tę zmienną.

 # pakiety binarne używające DocBook XML & xsltproc
 XMLPACKAGES="po4a"

DOCBOOKDIR

Podobne do XMLDIR, ale używane tylko do utworzenie przetłumaczonych plików DocBook. Jeśli Twój pakiet używa plików *.sgml, prosimy przedyskutować sposób jego budowania na liście e-mailowej po4a-devel.

 # wzorzec wyszukiwania plików .docbook
 DOCBOOKDIR=""

XSLFILE

Arkusz stylów XSL używany do przygotowania przetłumaczonej i nieprzetłumaczonej zawartości plików DocBook XML.

 # plik XSL używany w DocBook XML
 XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

PODFILE

Pliki POD tworzące sekcję 1 stron podręcznika ekranowego. Nazwy plików POD powinny być rozdzielone spacjami. Ścieżki, jeśli są używane, powinny być względne w stosunku do lokalizacji podanego pliku konfiguracji.

 # pliki POD dla sekcji 1
 PODFILE="po4a po4a-gettextize po4a-normalize scripts/msguntypot"

PODMODULES

Specjalne wsparcie modułów Perla zawierających zawartość POD - nazwa modułu będzie zbudowana ze ścieżki pliku (tak więc ścieżka powinna odzwierciedlać typowy układ ścieżek Perla), a strony podręcznika będą automatycznie umieszczone w sekcji 3.

 # pliki POD dla sekcji 3 - nazwy modułów utworzone ze ścieżki
 PODMODULES="lib/Locale/Po4a/*.pm"

POD5FILES

Dowolna zawartość POD tworząca strony podręcznika ekranowego w sekcji 5. Ścieżki, jeśli są używane, powinny być względne w stosunku do lokalizacji podanego pliku konfiguracji.

W przypadku zawartości sekcji 5 lub 7 (które zazwyczaj wymagają nazwy pliku używanego również w przypadku zawartości sekcji 1), jeśli częścią nazwy pliku jest 5 lub 7, to zostaną one automatycznie usunięte z nazwy pliku (łącznie z jakimkolwiek rozszerzeniem nazwy pliku).

 # pliki POD dla sekcji 5
 POD5FILES="doc/po4a-build.conf.5.pod"

POD7FILES

Dowolna zawartość POD tworząca strony podręcznika ekranowego w sekcji 7. Ścieżki, jeśli są używane, powinny być względne w stosunku do lokalizacji podanego pliku konfiguracji.

W przypadku zawartości sekcji 5 lub 7 (które zazwyczaj wymagają nazwy pliku używanego również w przypadku zawartości sekcji 1), jeśli częścią nazwy pliku jest 5 lub 7, to zostaną one automatycznie usunięte z nazwy pliku (łącznie z jakimkolwiek rozszerzeniem nazwy pliku).

 # pliki POD dla sekcji 7
 POD7FILES="doc/po4a.7.pod"

PODPACKAGES

Podobne do XMLPACKAGES - każdy pakiet oczekujący dokumentacji zbudowanej z plików POD powinien być wymieniony w PODPACKAGES. Pole jest wymagane, jeśli podano wartości w PODFILE, PODMODULES, POD5FILES lub POD7FILES.

 # pakiety binarne używające POD
 PODPACKAGES="po4a"

HTMLDIR

Podkatalog katalogu BASEDIR, w którym będą umieszczone wynikowe pliki HTML, zarówno przetłumaczone, jak i nieprzetłumaczone.

 # wyjście HTML (podkatalog BASEDIR)
 HTMLDIR=""

HTMLFILE

Plik DocBook jest konwertowany do HTML-a (może być taki sam jak jeden z plików w XMLMAN1 lub XMLMAN3). Sekcje nie mają znaczenia w przypadku wyjścia HTML, więc można użyć tutaj pojedynczego pliku książki, tak żeby miał spis treści itp.

 # plik DocBook HTML
 HTMLFILE=""

HTMLXSL

Domyślnie jest używany jeden arkusz stylów XSL. Podanie większej liczby arkuszy stylów dla jednego przebiegu generowania HTML-a nie jest obecnie wspierane.

 # plik XSL używany z HTML
 HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

AUTORZY

 Neil Williams <[email protected]>

TŁUMACZENIE

 Robert Luberda <[email protected]>