Dokumentacja (długie, ale przeczytajcie proszę)

[Tomasz Kłoczko]

On Sat, 30 Oct 1999, Ziemek Borowski wrote:

>      * To: Lista PLD <pld-list w pld.org.pl>
>      * Subject: Dokumentacja (długie, ale przeczytajcie proszę)
>      * From: Rafał Kleger-Rudomin <klakier w pg.gda.pl>
>      * Date: Sun, 17 Oct 1999 13:17:24 +0000 (/etc/localtime)
> 
> > Obecnie źródła dokumentacji występujące w dystybucji to:
> >     jakieś inne? formaty: 
> 
> parę pakietów ma wynikowe PSy i PDF, coś (named, na pewno samba) było pisane w 
> loutcie. 

Z tego co pamietam to postać źródłowa i tak była w latexu.

> > Jeśliby móc skonwertować i trzymać całą tę dokumentację w jednolitym formacie
> > ułatwione byłyby następujące zadania:
> 
> Ale praktycznie jest to niemożliwe. Za dużo roboty. 
> Np. w moim podręcznym testowym systemie na 297 pakietów jest 5668 plików 
> z dokumentacją.  Większość trzebaby przełożyć. 

Jeżeli chcesz to zrobić w jednym podejściu owszem. Jeżeli wyznaczysz to   
jako kierunek w którym należy iść to juz jest to mniej obciązające.
Pierwszrego podejścia nikt chyba o zdrowych zmysłach nie będzie
poroponował.

> 
> > Docbook ma wiele zalet wśród nich:
> > 
> >     jest sprawdzonym standardem przemysłowym
> >     możliwa będzie konwersja do XML
> 
> I co z tego? 
> Nb. decydując się na docbooka w grunice rzeczy nie musicie wybierać 
> SGMLa -- można od razu pisać w DocBook XML. 

Można. Jak uważasz, ze będzie łatwiej z jednoczesnym rozsądnym poziomem
elestyczności ?

> >     cała dokumentacja sun-a
> 
> Nieprawda. Tj. nie do końca prawda. Własny format NA BAZIE DocBooka. 
> Dawno odeń oddzielowny (AFAIR). 

Sunbook jest dość podonbny do Docbook.

> > 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.
> 
> A napiszesz takiego man(1)a? Tak by działał w miarę on-line?

Skoro przykład z solka pokazuje, ze jest to możliwe. Skoro jest bazowa
wersja man i bazowa wersja narzędzi do konwersji (szybkiej .. sam
sprawdzałem) z sgml do groff output to nie bedzie to trudne i w tym
wypadku już mało co przeszkadzać moze jeśli chodzi o względy techniczne
żeby to zrobić. Pozostaje usiąćś i zrobić to wreszcie.

> >     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.
> 
> Poszukaj koło 10 października na comp.text.xml było coś o docbook2info. 
> Chodziło bodaj o: 
>  http://shell.ipoline.com/~elmert/hacks/docbook2X/ 

O to chodziło :-)
Kolejny pukt można zakreślić jako "possible".

> Generalnie: na początek proponuję raczej przyjęcie, że nowotworzoną
> dokumentację robicie w DocBooku (ale tutaj na gwałt trzeba kilka rzeczy
> zrobić najpierw:
>   * przerzucić się z jade na openjade (ten przynajmniej jest rozwijany
>    -- jade nie bo James Clark stawia wszystko na XMLa i XSLa).
>   * zrobić pljadetex jak proponował to Piotrek Bolek na Bachotku (chyba
>   że udało się wam zwalczyć pliterki inaczej). Nie zaszkodziłby też
>   plpdfjadetex.

Czy dałoby sie to potem zintegrować z openjade  przez podrzucenie
maintainegom jakiś poprawek ?

>   * przepracować metody rejestracji CATALOGów i innych zasobów
>   XML/SGMLowych przy czym robiąc to w miarę zgodnie z innymi dystrybucjami
>   (np. SuSE i Debianem -- te mają wsparcie dla DocBooka).
> 
> Acha. Przydać się  może lektura
> http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html

Dzieki. Wogóle fajno, ze zacząłeś znowu włączać się jakoś konstruktywnie w
to co możesz i potrzfisz robić :-)

kloczek
-- 
-----------------------------------------------------------
*Ludzie nie mają problemów, tylko sobie sami je stwarzają*
-----------------------------------------------------------
Tomasz Kłoczko, sys adm @zie.pg.gda.pl|*e-mail: kloczek w rudy.mif.pg.gda.pl*