Provided by: po4a_0.52-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
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.
Separate strings with a space.
# 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.
# HTML DocBook file
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>
Narzędzia po4a 2017-08-26 PO4A-BUILD.CONF(5)