Wskazówki dotyczące tworzenia dokumentacji Gentoo

1.  Tworzenie środowiska pracy

Lokalne środowisko dla współpracowników

Tworzymy katalog poświęcony tylko i wyłącznie tworzeniu dokumentacji. Na przykład ~/praca/gentoo/doc. Wewnątrz tego katalogu tworzymy podkatalog w którym będziemy przechowywali (aktualną) angielską dokumentację (przykładowo en/).

Następnie ściągamy tarball z najświeższą angielską dokumentacją:

$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2

Wypakowujemy plik do katalogu en/ i mamy najnowszy obraz angielskiej dokumentacji. Za każdym razem kiedy chcemy uaktualnić nasz obraz, należy ściągnąć tarball ponownie. Można również otworzyć określony dokument za pomocą przeglądarki, dodając ?passthru=1 do adresu URL. Przykładowo:

$ wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O alsa-guide.xml

Jeśli chcemy pomóc w tłumaczeniu dokumentów, to należy stworzyć katalog pl/ w którym będziemy trzymać już przetłumaczone dokumenty:

$ mkdir pl
$ cd pl
$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-pl.tar.bz2
$ tar xvjf docs-latest-pl.tar.bz2

Zanim zaktualizujemy jakiś dokument, należy zawsze skopiować starszą wersję z pl/ do katalogu ~/praca/gentoo/doc, a następnie zmienić skopiowany plik. Oryginał jest nam potrzebny do stworzenia łatki:

$ diff -U6 ${LANG}/alsa-guide.xml alsa-guide.xml > alsa-guide.diff

Interaktywne repozytorium CVS

Można korzystać z interaktywnego repozytorium CVS, aby zobaczyć zmiany pomiędzy poszczególnymi wersjami. Główne angielskie repozytorium jest dostępne dla wszystkich i jest aktualizowane co godzinę.

Lokalne repozytorium dla deweloperów

Tworzymy katalog roboczy przeznaczony na dokumentację Gentoo; dla przykładu ~/praca/gentoo/doc. Następnie tworzymy podkatalog cvs/ w którym umieszczamy obraz CVS:

$ mkdir cvs; cd cvs/
$ export CVSROOT=<login>@cvs.gentoo.org:/var/cvsroot
$ cvs co doc

Aby uaktualnić obraz CVS, należy wykonać polecenie cvs update -dP w katalogu cvs/doc.

2.  Testowanie GuideXML

Testowanie środowiska

Najpierw tworzymy katalog test/ w którym umieścimy pliki guide.xsl, main.css oraz kilka obrazów:

$ mkdir -p test/{css,images}
$ cd test
$ wget -P css/ http://www.gentoo.org/css/main.css
wget -P images/ http://www.gentoo.org/images/gridtest.gif \ http://www.gentoo.org/images/gentoo-new.gif \ http://www.gentoo.org/images/gtop-www.jpg

Po czym ściągamy specjalną wersję guide.xsl dostępną na stronie neysxa. Ta wersja jest przystosowana do przekształcenia GuideXML do HTML na lokalnych systemach oraz posiada wsparcie dla kilku języków. Można również pobrać znacznie krótszą wersję, która posiada wsparcie jedynie dla języka angielskiego.

$ wget http://dev.gentoo.org/~neysx/guide.xsl
(Lub w przypadku kiedy potrzebujemy jedynie angielskiego)
$ wget -O guide.xsl http://dev.gentoo.org/~neysx/guide-en.xsl

Na koniec edytujemy plik /etc/xml/catalog dodając następującą linię:

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Jeśli plik /etc/xml/catalog jest pusty lub nie zawiera żadnych wpisów, konieczne będzie dodanie taga <rewriteURI> wewnątrz elementu <catalog>:

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

Ponadto niektóre pliki mogą odwoływać się do DTD znajdującego się w sieci, na przykład poprzez wpis http://www.gentoo.org/dtd/guide.dtd. W takim przypadku warto również je przepisać i uniknąć spowalniającego pracę odwoływania się do plików w Internecie.

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Testowanie przewodnika Gentoo

Tekst napisany w GuideXML można sprawdzić za pomocą narzędzia xmllint z pakietu dev-libs/libxml2:

$ xmllint --valid --noout alsa-guide.xml

Jeśli xmllint nic nie zwróci, oznacza to, że plik jest bez błędów (przynajmniej tagi XML). Następnie przekształcamy go do HTML. Użytecznym narzędziem do tego jest xsltproc z pakietu dev-libs/libxslt:

$ xsltproc test/guide.xsl alsa-guide.xml > test/alsa-guide.html

Jeśli żaden błąd nie zostanie zwrócony, wystarczy otworzyć dokument za pomocą przeglądarki. Znajduje się on pod adresem file:///home/użytkownik/praca/gentoo/doc/test/alsa-guide.html. Jeśli nie zadziałało, to należy tak długo naprawiać przewodnik aż proces się uda.

Testowanie Podręcznika Gentoo

Podręcznik Gentoo jest podzielony na rozdziały. Aby przetworzyć jeden z nich, tak jakby znajdował się on na naszym serwerze internetowym, należy posłużyć się zarówno plikiem handbook-x86.xml jak i wymaganym hb- (na przykład hb-install-about.xml). Następnie dokument musi przejść przez xsltproc z tymi samymi parametrami z którymi będzie przeglądany, mianowicie part i chap. Poniższy przykład prezentuje w jaki sposób można sprawdzić poprawność pliku hb-install-about.xml. Należy mieć na uwadze, że potrzebujemy wszystkich plików, które składają się na podręcznik.

$ xmllint --valid --noout handbook-x86.xml
$ xmllint --valid --noout hb-install-about.xml
$ xsltproc --stringparam part 1 --stringparam chap 1 test/guide.xsl handbook-x86.xml > test/hb-install-about.html

Możemy również sprawdzić i przekształcić, którykolwiek z rozdziałów podręcznika w taki sam sposób jak inne przewodniki. Jednak w tym wypadku odnośniki do innych części podręcznika nie zostaną poprawnie wygenerowane.

$ xmllint --valid --noout hb-install-about.xml
$ xsltproc test/guide.xsl hb-install-about.xml > test/hb-install-about.html

3.  Często zadawane pytania

Jak przekonwertować plik do UTF-8?

Istnieje dość sporo narzędzi, które mogą nam w tym pomóc. Najpopularniejsze są app-text/recode oraz iconv, który jest częścią pakietu sys-libs/glibc.

Użycie recode jest bardzo proste. Mówimy mu jakie jest obecne kodowanie dokumentu, a następnie jakie kodowanie chcielibyśmy uzyskać.

Przykładowo, aby przekonwertować dokument w ISO-8859-2 (standardowe polskie kodowanie, Latin-2) na UTF-8, używamy:

(l2 = ISO-8859-2, u8 = UTF-8)
$ recode l2..u8 file.xml

4.  Pomocne sztuczki przy sprawdzaniu poprawności dokumentacji

Sprawdzanie poprawności tagów <guide>

Należy upewnić się, że atrybuty znacznika <guide> prowadzą do poprawnej lokalizacji dokumentu. Zazwyczaj jest to /doc/${LANG}/nazwapliku.xml. Jeżeli nasz dokument jest przetłumaczony zawsze precyzujemy ścieżkę dokładnie do niego (np. /doc/${LANG}/). Jeżeli zajmujemy się dokumentem używającym DTD guide bądź book, możemy zamiennie używać /doc/${LANG}/nazwapliku.xml i nazwapliku.xml. Jednak GDP zaleca używanie tej pierwszej formy.

Sprawdzanie poprawności odnośników

Musimy mieć pewność, że wszystkie odnośniki w naszym dokumencie działają. Jeżeli zajmujemy się tłumaczeniem, że odnośniki w naszym teście prowadzą do innych przetłumaczonych i istniejących dokumentów.

Sprawdzanie tabulatorów

Tabulatory są zabronione w dokumentach pisanych za pomocą GuideXML. Jedynie w przypadku gdy w dokumencje zaleca się używanie tabulatorów użytkownikowi, można odstąpić od tej zasady. Aby sprawdzić dokumentację pod tym względem, należy uruchomić polecenie grep "CTRL+V<TAB>" file.xml, a następnie poprawiamy wszystkie linie, które zostaną wskazane przez grep.

Bugzilla

Kiedy już ukończymy dokument, wysyłamy go do zespołu dokumentacji za pomocą Bugzilli. Nie musimy przy tym podawać informacji takich jak rodzaj architektury, platformę, wynik polecenia emerge info itp. Jeżeli wysyłamy tłumaczenie należy upewnić się, że wybieramy komponent Doc Translations dla naszego raportu. Pomocną rzeczą może się również okazać dodanie podsumowania w formacie: "[fr] New translation: /doc/fr/gnupg-user.xml". Oczywiście [fr] zastępujemy dwuliterowym kodem naszego języka.

Domyślnie błędy przypisywane są do docs-team@gentoo.org. Nie ma potrzeby zmieniać tego pola.

Pliki i łatki dołączamy wybierając "plain text (text/plain)". Nie należy wybierać "XML source (application/xml)", nawet w przypadku kiedy dołączamy plik .xml. Łatki powinni być wysyłane z włączoną opcją "Patch". Nie powinniśmy wysyłać całych archiwów z dokumentami. Każdy dokument i łata powinni być wysłane oddzielnie.

5.  Najczęściej popełnianie błędy

Zapominanie o aspekcie wielu architektur Podręcznika Gentoo

Pliki w [gentoo]/xml/htdocs/doc/en/handbook, które nie kończą się przyrostkiem "-<ARCHITEKTURA>.xml" są wspólne dla wszystkich architektur.

Jeśli potrzebujemy dodać coś dotyczącego tylko wybranej architektury i nie wiemy w jaki sposób to umieścić w tym pliku, wtedy należy poprosić o rozwiązanie tego problemu pisząc na adres gentoo-doc@gentoo.org. Czasami istnieje sposób modyfikacji pliku bez komplikowania życia użytkownikom innych architektur.

Nie wstawianie informacji o wersji i dacie lub czynienie tego w zły sposób

Trzeba zmienić wersję i datę podczas dokonywania zmian (SwifT morduje tych, którzy o tym zapomną). Wersja jest naszą wewnętrzną informacją ułatwiającą tłumaczom dokumentacji śledzenie zmian w dokumentach, a data mówi użytkownikom kiedy dokument był zmieniany po raz ostatni.

Jeżeli zmieniamy zawartość dokumentu (np. instrukcje, przykładowe polecenia itp.) wtedy zmiana wersji jest przymusowa. W przypadku wprowadzania zmian, które nie zmieniają zawartości (np. literówka, poprawa kodu GuideXML itp.) zmiana wersji nie jest potrzeba.

Podczas aktualizacji Podręcznika zmieniamy datę i wersję wyłącznie tych plików które uaktualnialiśmy. Nie zmieniamy pliku handbook-ARCHITEKTURA.xml jeśli nie zmienialiśmy jego zawartości.

Innym częstym błędem jest aktualizacja wersji tak jakby to była liczba dziesiętna. A mianowicie ona nią nie jest. Po 3.9 powinno być 3.10, nie 4.0, ani nie 3.91.

Materiał udostępniany na podstawie licencji Creative Commons - Attribution / Share Alike.