Dokumentacja (długie, ale przeczytajcie proszę)

[Rafał Kleger-Rudomin]

Witam

Jakiś czas temu zaproponowałem rozpoczęcie dokumentowania PLD
Kloczek i Wiget zwrócili wtedy moją uwagę na SGML-Docbook-DTD i możliwość
jego wykorzystania, w aspekcie szerszym niż tylko napisanie manuala do PLD.

Przedstawiam moje wnioski i propozycje dotyczące zastosowania tych narzędzi do
stworzenia w miarę jednolitego systemu dokumentacji.

Dla tych którzy nie wiedzą co to SGML i Docbook polecam lekturę
    PLD-doc/SGML-DocBook/docbook-intro_pl/docbook-intro.html
    są tam również odnośniki do innych źródeł


    
*** Wprowadzenie ***

Obecnie źródła dokumentacji występujące w dystybucji to:

    txt: pliki tekstowe z pakietów
    texinfo: z pakietów
    many: z pakietów
    html: z pakietów
    sgml-linuxdoc: z pakietów
    sgml-linuxdoc: HOWTO i JTZ
    chyba latex?: podręczniki LDP
    sgml-docbook: dokumentacja gnome
    texinfo: materiał o CVS na www.pld.org.pl
    jakieś inne? formaty: materiały na www.pld.org.pl
    (zapomiałem o czymś?)

Później mogłyby do tego dołączyć na przykład:

    sgml-docbook: z pakietów pld-specific (rc-csripts, pam itd)
    sgml-docbook: PLD-reference
    sgml-docbook: PLD-user-manual
    sgml-docbook: PLD-tutorial

Jeśliby móc skonwertować i trzymać całą tę dokumentację w jednolitym formacie
ułatwione byłyby następujące zadania: 

    Stworzenie wspólnego drzewa całej dokumentacji przychodzącej z dystrybucją
    Budowanie z CVS wersji HTML dla www.pld.org.pl
    Budowanie dokumentacji HTML (kiedyś może XML?) do przeglądania w  obrębie
	dystrybucji
    Konwersja do formatów drukowalnych
    Tworzenie indeksów i wyszukiwanie
    


*** Dlaczego kolejny format? ***

Docbook ma wiele zalet wśród nich:

    jest sprawdzonym standardem przemysłowym
    możliwa będzie konwersja do XML
    zmusza do bardzo dokładnego oznaczania treści dokumentów
    są do niego dobre narzędzia
    jest zgodny ze standardem ISO - SGML, co wróży mu dalszą przyszłość 
    ... po bardziej kompletną listę odsyłam do docbook-intro i innych źródeł

Przykłady zastosowań Docbooka:

    cała dokumentacja sun-a
    cała dokumentacja gnome
    ponoć M$ też używa ...


*** Co z dokumentacją w innych formatach? ***

man:
    Docbook zawiera specjalne struktury przeznaczone do trzymania 
    opisów takich jak unixowe man-pages. Kloczek pisał że w solarisie
    many są trzymane w docbooku, a program man jest tak spreparowny by
    konwertować to w locie. Czyli jest to wykonalne.
    Oprócz tego tak spreparowane many mogłyby być podłączone do głównego drzewa

texinfo: 
    Format texinfo sam w sobie jest całkiem "informacjonośny" i możnaby go 
    nieźle wpasować w DocBooka. Przykładów że ktoś to zrobił nie znam.
    Trochę żal by było "pinfo". Ale z drugiej strony można by też napisać
    konwerter docbook2info i traktowac info jako kolejny format wynikowy,
    obok html i texa.

linuxdoc:
    Jest konwerter linuxdoc-docbook


aspekty związane z innymi formatami:
    gimp manual ma źródła w jakimś innym formacie
    lyx ma doce w lyxie
    tex ma doce w texu, dvi i sam w sobie
    
    i pewnie ciężko będzie coś na to szybko poradzić - trudno
    
    

*** Projekt drzewa ***

Ogólne drzewo wyobrażam sobie mniej więcej tak:

/
|-Dokumentacja developera
|	|-jeśli autorzy się zgodzą byłoby tu to co jest obecnie w dziale technikalia
|	|-i instrukcja jak pisać dokumentację w docbooku
|	|-i jeszcze inne 
|
|-PLD Przewodnik (Tutorial)
|-PLD Podręcznik Użytkownika (User Manual)
|-PLD Dokumentacja systemu (Reference)
|	|-pakiet rc-scripts
|	| ...
|	|-pakiet pam
|	
|-JTZ
|-KDE,GNOME doce
|-Oprogramowanie
|	|-pakiet aaa
|	| ...
|	|-pakiet zzz
|	    |-doce skonwertowane z man
|	    |-doce skonwertowane z info
|		i wszystko inne co się uda
|-Indeksy

Dla www drzewo byłoby odpowiednio opowiednio okrojone


Gdzie byłyby trzymane poszczególne rzeczy?
Dokumentacja Developera, PLD Przewodnik i Podręcznik miałyby swoje własne
moduły.
PLD dokumentacja systemu miałaby swój moduł ale tam byłby tylko główny
dokument - reszta w poszczególnych modułach
Cała ta dokumentacja mogłaby być normalnie w pakietach
do zaistalowania w formie html. Źródła byłyby tylko w cvs

Co do dokumentacji oprogramowania:
Tutaj kwestia jest raczej otwarta. Na pewno można spróbować
zamienić many na docbook.


*** Co można zrobić na razie ***

Powyższe to tylko projekt, jest wiele problemów do rozwiązania
aby coś takiego w całości osiągnąć.

Na razie można pisać dokumentację do rzeczy które są tworzone przez PLD-team
tzn. do działu Dokumentacja systemu.
Pozwoliłem sobie wrzucić przykład do rc-scripts/doc (sysconfig.docb)
To jest przykład tworzenia "reference entry"

Jeśliby ktoś chciał pisać jakiś artykuł to ogólnym przykładem
może być PLD-doc/SGML-DocBook/sources/docbook-intro_pl.sgml



Ja chciałbym zacząć od tworzenia modułu dokumentacji developera
wyglądałoby to np. tak

moduł docdevel:
index.docb - dokument główny
docbook-intro.pl.docb - rozdział o docbooku
inne pliki - rozdziały
jeśli potrzeba - w podkatalogach podrozdziały itd

I tyle. W tworzeniu i poprawianiu dokumentacji
będą mogli brać udział wszyscy. Żeby stworzyć nowy rozdział
wystarczy wrzucić nowy plik i podpiąć go do dokumentu głównego.


To tyle
Proszę o uwagi

-- 
Rafał Kleger-Rudomin (klakier w pg.gda.pl)