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.
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>