Dokumentacja (długie, ale przeczytajcie proszę)

[Ziemek Borowski]

     * 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. 

> 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ć. 

> 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. 

>     cała dokumentacja sun-a

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

> 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?

>     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/ 

> linuxdoc:
>     Jest konwerter linuxdoc-docbook

A jaki % pracy wykonuje? (z mojej praktyki wynika że przejscie na
DocBooka z LinuxDoca to praktycznie ręczne przeznakowanie dokumentu
(korzystając z z DSSSLowych styleshetów z SGMLTools v2.0.)).


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.
  * 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


-- 
Ziemek Borowski ZB137-RIPE http://faq-bot.ziembor.waw.pl/zmb/