Provided by: po4a_0.45-1_all 
NAZWA
po4a-build.conf - plik konfiguracyjny do budowania przetłumaczonej dokumentacji
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
Zazwyczaj używany przez strony podręcznika skryptów powłoki lub innych interpreterów,
które nie mają własnego formatu dokumentacji typu POD. Odpowiedni XML można
wygenerować bezpośrednio z istniejącej strony podręcznika za pomocą "doclifter", a
"po4a-build" wygeneruje wtedy plik POT. Plik POT można wtedy zaoferować do
przetłumaczenia, a pliki PO można dodać do odpowiedniego katalogu po/. "po4a-build"
przygotuje wtedy nie tylko nieprzetłumaczoną stronę podręcznika używając "doclifter",
ale także wywoła "po4a" do przygotowania przetłumaczonych XML-i z plików PO i
wygenerowania z niego przetłumaczonych stron podręcznika.
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 <linux@codehelp.co.uk>
TŁUMACZENIE
Robert Luberda <robert@debian.org>