Linux Certif

Toute la documentation sur la certification Linux LPI

po4a-build.conf

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

(Patrz także opis opcji KEEP poniżej, żeby dowiedzieć się o ograniczeniach łączenia większej liczby plików do jednego pliku POT w jednym uruchomieniu "po4a-build".)

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 "XSLFILE" 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 pliku konfiguracji
  CONFIG="_build/po4a.config"
 
 

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.

PODIR

Wymagany.

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

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

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 POTFILE
  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 w pełni kontrolować to zachowanie, prosimy rozważnie przypisywać pliki do odpowiednich zmiennych pliku konfiguracyjnego po4a-build.conf. Każdy plik wymieniony w jakimkolwiek pliku po4a-build.conf będzie używany w wyliczeniu procentowej wartości przetłumaczonych komunikatów. Jeden duży, ale w niewielkim stopniu przetłumaczony plik spowoduje wyrzucenie innych, mniejszych plików z budowanego pakietu, nawet jeśli każdy z tych mniejszych plików jest przetłumaczony w 100%.

Z drugiej strony 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. Odwrotnie, pliki POT z tysiącami komunikatów do przetłumaczenia zniechęcają tłumaczy i prowadzą do zamrożenia 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.

  # strony podręcznika 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 XSL
  XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
 
 

PODFILE

Plik(i) 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 man1
  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 man3/ - 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 XMLFILE). 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 Docbook XSL
  HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
 
 

AUTORZY

  Neil Williams <linux@codehelp.co.uk>