[svn/pld-doc]: rev 170 - pld-doc/howto
ciesiel w svn.pld-dc.org
ciesiel w svn.pld-dc.org
Sob, 3 Sty 2004, 21:25:34 CET
Author: ciesiel
Date: 2004-01-03 21:25:33 +0100 (Sat, 03 Jan 2004)
New Revision: 170
Modified:
pld-doc/howto/pl_wskazowki__docbook.chp
Log:
- added description about modular docbook
- cleaning
Modified: pld-doc/howto/pl_wskazowki__docbook.chp
===================================================================
--- pld-doc/howto/pl_wskazowki__docbook.chp 2004-01-03 19:26:02 UTC (rev 169)
+++ pld-doc/howto/pl_wskazowki__docbook.chp 2004-01-03 20:25:33 UTC (rev 170)
@@ -1,31 +1,65 @@
<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $LastChangedDate: 2004-01-02 10:37:52 +0100 (Fri, 02 Jan 2004) $ $LastChangedBy: ciesiel $ $Rev: 138 $ -->
- <chapter>
- <title>Tworzymy dokumentacje</title>
+<chapter>
+ <title>Tworzymy dokumentacje</title>
+ <para>
+ Do tego nie trzeba wiele - a najważniejsze są chęci i przynajmniej trója z polskiego :)
+ </para>
+ <section>
+ <title>Wymagania programowe</title>
<para>
- Do tego nie trzeba wiele - a najważniejsze są chęci i przynajmniej trója z polskiego :)
+ Te pakiety będą nam potrzebne do pracy przy tworzeniu dokumentacji:
</para>
- <section>
- <title>Wymagania programowe</title>
- <para>
- Te pakiety będą nam potrzebne do pracy przy tworzeniu dokumentacji:
- </para>
- <itemizedlist>
- <listitem><para>libxml2-progs</para></listitem>
- <listitem><para>docbook-dtd42-xml</para></listitem>
- </itemizedlist>
- <para>Na pewno jakiś edytor tekstowy. Proponuje VIM, gdyż ma kolorowanie i robi wcięcia ale oczywiście możemy poszukać swojego środowiska. Można np. zajrzeć na <ulink url="http://www.dpawson.co.uk/docbook/tools.html#d841e305"> strone dpawsona</ulink>. Do tego opisu można dodać jeszcze program conglomerate pod KDE (chociaż jeszcze nie nadaje się on do poważnej pracy - za dużo oopsuje :(</para>
- <para>Gdy już jesteśmy przygotowani programowo i psychicznie proponuje podróż na strone <ulink url="http://www.docbook.org"> Docbooka</ulink>. 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 :)</para>
- </section>
- <section>
- <title>Tworzymy dokument docbooka</title>
- <para>Dla ułatwienia pracy w CVS i SVN skopiowane zostały szablony dokumentów docbooka dla języka angielskiego i polskiego. Kopiujemy odpowiedni szablon do pliku, który chcemy stworzyć pamiętając o przyjętej notacji nazewnictwa:</para>
- <para>język_dział__temat.docb</para>
- <para>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</para>
- <para>Po edycji pliku należy bezwzględnie dokonać sprawdzenia (walidacji) - Dokonujemy tego poleceniem:</para>
- <para>xmllint --valid --noout (przykładowo: <command>xmllint --valid --noout pl_test.docb</command>)</para>
- <para>Oczywiście wszystkie błędy składniowe musimy naprawić. Jedynie błąd, który wskazuje na brak obsługi LANG możemy zignorować.</para>
- <para>Interesuje nas pewnie wizualizacja tego 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). </para>
- <para>Gdy już jesteśmy pewni swojego dzieła udostępniamy go w CVSie lub SVN. A potem poprawiamy, poprawiamy i poprawiamy :)</para>
- </section>
- </chapter>
+ <itemizedlist>
+ <listitem><para>libxml2-progs</para></listitem>
+ <listitem><para>docbook-dtd42-xml</para></listitem>
+ </itemizedlist>
+ <para>Na pewno jakiś edytor tekstowy. Proponuje VIM, gdyż ma
+ kolorowanie i robi wcięcia ale oczywiście możemy poszukać swojego środowiska.
+ Można np. zajrzeć na
+ <ulink url="http://www.dpawson.co.uk/docbook/tools.html#d841e305"> strone dpawsona</ulink>.
+ Do tego opisu można dodać jeszcze program conglomerate pod KDE (chociaż jeszcze nie nadaje
+ się on do poważnej pracy - często oopsuje)
+ </para>
+ <para>Gdy już jesteśmy przygotowani programowo i psychicznie proponuje podróż na strone
+ <ulink url="http://www.docbook.org"> Docbooka</ulink>. 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 :)</para>
+ </section>
+ <section>
+ <title>Tworzymy dokument docbooka</title>
+ <para>Dla ułatwienia pracy w CVS i SVN skopiowane zostały szablony dokumentów docbooka
+ dla języka angielskiego i polskiego (w katalogu template SVN bądź CVS). Kopiujemy odpowiedni
+ szablon do pliku, który chcemy stworzyć pamiętając o przyjętej notacji nazewnictwa np:</para>
+ <para>język_dział__temat.docb</para>
+ <para>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.</para>
+ </section>
+ <section>
+ <title>Organizacja dokumentów PLD</title>
+ <para>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/".
+ </para>
+ </section>
+ <section>
+ <title>Czynności końcowe związane z edycją plików docbook PLD</title>
+ <para>Po edycji pliku należy bezwzględnie dokonać sprawdzenia (walidacji) -
+ Dokonujemy tego poleceniem:</para>
+ <para>xmllint --valid --noout
+ (przykładowo: <command>xmllint --valid --noout pl_test.docb</command>)</para>
+ <para>Oczywiście wszystkie błędy składniowe musimy naprawić.</para>
+ <para>Interesuje nas pewnie wizualizacja tego 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).</para>
+ <para>Gdy już jesteśmy pewni swojego dzieła udostępniamy go w CVSie lub SVN.
+ A potem poprawiamy, poprawiamy i poprawiamy :)</para>
+ </section>
+</chapter>
Więcej informacji o liście dyskusyjnej pld-doc