Porady dla piszących dokumentacje PLD

Te pakiety będą nam potrzebne do pracy przy tworzeniu dokumentacji:

Na pewno jakiś edytor tekstowy. Proponuje VIM™, gdyż ma kolorowanie i robi wcięcia ale oczywiście możemy użyć swojego ulubionego edytora. Dla VIMa możemy sobie ściągnąć .vimrc, skopiować do domowego katalogu (pamiętając o ustawieniu odpowiednich praw) i po uruchomieniu VIMa w trybie edycji mamy dodatkowo szybką obsługę tag�w docboka. Przykładowo po podaniu sekwencji ,pp stworzą nam się tagi para, a po poleceniu ,cm1 lewy tag command - a ,cm2 zamknie nam tag command. Przeglądając i edytująć w/w plik konfiguracyjny możemy bardzo łatwo przystosować pracę w VIMie do naszych upodobań.

Można także zajrzeć na stronę dpawsona. Do tego opisu można dodać jeszcze program conglomerate™ pod KDE™ (chociaż jeszcze nie nadaje się on do poważnej pracy - często oopsuje)

Gdy już jesteśmy przygotowani programowo i psychicznie proponuje podr�ż na strone Docbooka. Mimo że po angielsku to sekcja Read The Book jest na tyle zwięzła i czytelna że rozjaśni wiele w naszych głowach... a jak nie to standardowo - lista PLD-doc, IRC i google :)

Dla ułatwienia pracy w SVN skopiowane zostały szablony dokument�w docbooka dla języka angielskiego i polskiego (w katalogu template). Kopiujemy odpowiedni szablon do pliku, kt�ry chcemy stworzyć pamiętając o przyjętej notacji nazewnictwa np:

język_dział__temat.docb

czyli przykładowo: "pl_instalacja__instalacja_pld.docb". Należy zwr�cić uwagę na podw�jny __ po dziale, co ułatwi p�źniej obr�bkę pliku. Um�wmy się także, że w nazwach nie używamy wielkich liter. Zwr�ćmy także uwagę na podział opisany niżej.

Praca nad dokumentami jest zmodularyzowana. Oznacza to, że istnieje dokument gł�wny, kt�ry zawiera odpowiednie zapisy dotyczące zewnętrznych plik�w (w template opisuje to plik "pl_template__master.docb") i pliki na kt�rych pracujemy - są to rozdziały (*.chp) i sekcje (*.sec) - przykład plik�w podrzędnych mamy w katalogach "template/pl_template/".

Po edycji dokument�w należy bezwzględnie dokonać sprawdzenia (walidacji) - Dokonujemy tego poleceniem:

xmllint --valid --noout (przykładowo: xmllint --valid --noout pl_test.docb)

W przypadku korzystania z modularnie zbudowanych dokument�w, walidacji dokonujemy tylko na gł�wnym dokumencie. Przykładowo w naszym katalogu ./book jest to plik pl_book__master.docb

$ xmllint --valid --noout pl_book__master.docb

Oczywiście wszystkie błędy składniowe, kt�re podczas sprawdzenia zostaną wyświetlone, musimy poprawić.

Interesuje nas pewnie wizualizacja tego co robimy. Możemy skorzystać ze skryptu docbook2html z pakietu docbook-utils, kt�ry z poprawnego docbooka zbuduje nam strony html... chyba nie trzeba już tłumaczyć co potem? Przydatna może być tutaj opcja '-u', kt�ra z podanego dokumentu docbook stworzy pojedyńczy plik HTML (domyślnie każdy rozdział ląduje w innym pliku).

Gdy już jesteśmy pewni swojego dzieła udostępniamy go SVN. A potem poprawiamy, poprawiamy i poprawiamy :)

Dokumentację piszemy po polsku. Co to znaczy? Przede wszystkim unikamy wszelkich kolokwializm�w, nie piszemy, że "jeśli nie działa, to dupa". Nie piszemy, że "wszystko bangla" albo że "coś nie hula". Nie piszemy jej dla siebie, będą czytać ją inni ludzie i oczekują od niej konkret�w, a nie niezwykle elokwentnego i wysublimowanego poczucia humoru.

Unikamy komentarzy odautorskich w stylu "ale ja bym do tego użył ..." albo "mimo wszystko, wolę ...". Nie piszemy też, że "to m�j ulubiony pakiet".

W miarę możliwości stawiamy znaki przestankowe zgodnie z zasadami polskiej interpunkcji. Przed wysłaniem własne dokumenty przepuszczamy przez ispella.

W długich paragrafach łamiemy wiersze. Nie każdy ma terminal na cały ekran w 1600x1200. Dużo łatwiej jest wtedy wyłapać błędy i znacznie ułatwia p�źniejsze tłumaczenie dokumentu.

Screeny prezentujące polecenia konsekwentnie zaczynamy od stosownego znaku zachęty. Dolar oznacza polecenia niewymagające praw roota, hash polecenia wymagające takich uprawnień. Przy opisie poleceń og�lnego użytku (kt�re same z siebie nie wymagają żadnych specjalnych uprawnień) wybieramy przykłady r�wnież niewymagające uprawnień. Np. nie jest dobrym pomysłem pokazanie jako przykład zastosowania polecenia cp konstrukcji takiej jak poniżej:

# cp /etc/modules.conf /etc/modprobe.conf

Screeny prezentujemy bez zbędnych rzeczy, np. nie wklejamy prompta, jeśli nie jest on przedmiotem screena. To samo tyczy się końcowego znaku zachęty. Nie wklejamy więc na końcu screena pustego znaku "#".

Nazwy własne pakiet�w i program�w otaczamy tagami "productname", np.:

Do tego celu posłuży nam program poldek™

Nazwy poleceń otaczamy tagami "command":

Aby go uruchomić, wpisz po prostu poldek.

Zauważ r�żnicę kontekstu, w kt�rym występuje słowo "poldek" w obu powyższych przykładach.

Na samym początku musimy pobrać tzw. repozytorium. Wydajemy taką komendę:

svn co http://svn.pld-linux.org/svn/PLD-doc PLD-doc

Pojawi się monit o wpisanie hasła. Logujemy się i po chwili powiniśmy mieć ściągnięte repozytorium pld-doc z serwera SVN.

Aby założyć katalog piszemy:

svn mkdir nasz_katalog

Do katalogu kt�ry założyliśmy przed chwilą możemy kopiować pliki w taki sam spos�b jak robimy to podczas normalnej pracy. O czym należy pamiętać. Jeżeli chcemy aby katalog jak r�wnież pliki kt�re do niego skopiowaliśmy stały się dostępne dla innych użytkownik�w systemu svn, musimy wykonać następujące czynności. Po pierwsze musimy jak gdyby 'powiedzieć' systemowi kt�re pliki będziemy mu wysyłać. Wykonujemy:

svn add plik1 plik2 plik[n]

a następnie udostępniamy swoje zmiany innym, wykonując tzw. commita.

svn ci -m "- krotki opis co zrobiliśmy"

Zostaniemy poproszeni o wpisanie hasła. Po udanej autoryzacji nasze zmiany już są dostępne dla innych.

Uwaga! Przed commitem należy wykonać trzy czynności:

Przed zmianami w naszym lokalnym repozytorium SVN należy dokonać aktualizacji. Wszelkie modyfikacje jakie zostały poczynione przez innych zostaną wczytane i zmniejszy się prawdopodobieństwo wystąpienia konflikt�w, kt�re mogą wystąpić gdy trwają prace przy tych samych fragmentach dokumentacji.

cd ~/pld-doc 
svn up