Dokumetntacja.

[Tomasz Kłoczko]

On Fri, 6 Oct 2000, Lukas Dobrek wrote:

> Wrrrrrrrrrrrrrrr,
> Moim zdaniem mamy koncepcyjny problem do rozwiazania z dokumentacja.
> Najpier moj ulubiony przyklad. Wyobraz sobie ze instalujesz PLD 
> niestety z jakiegos powodu nie chca sie odpalic X. Nie ma problemu 
> sciagasz pakiet XFree86-doc instalujesz go. I zaby poczytac zawarta tam 
> dokumentacja albo kupujesz drukarka albo odpalasz spokojnie X i w gv juz
> mozesz sobie poczytac pliki Postscriptowe. To jest CHORE.

> Naprawde powinno sie dac czytac dokumentacje pod konsola. Nie zawsze mozna 
> odpalic X. A juz PostScript jest najgorszym rozwiazaniem. To lepiej pdf.
> przynajmniej mozna dokumenty przeszukiwac. 

Nie do mnie na ten temat. Dokumetacja jaka jest dostarczana do XF to już
zupełnie inna bajka. Postać źródłowa jest od nfoff do wordowych DOC-ów.
Ktoś w XFree86 musiałby zacząć pracować nad tym żeby wreszcie przestawić
całą dokumentacje na "Jedyny SŁuszny Format (TM)" czyli SGML/docbook.

> Byla kiedys koncepcja dostarczania pakietow wraz z roznoraka dokumentacja.
> Tomek byl przeciw i nawet widzialem ze ostatnio powycinal to z zsh. Ale 
> moze to nie byl taki zly pomysl. Ja mam taka propozycje. 
> Zeby pakiet dostarczac z max dwoma podpakietami z dokumentacja. 
> Jeden jest czytelny na konsoli. Typu txt, html, itp. A drugi z czyms co 
> da sie latwo wydrukowac. Mozna to nawet nazywac albo zsh-doc-txt i zsh-doc-pdf.
> Albo np: zsh-doc-readable zsh-doc-printable bedzie  nieco wiekszy porzadek.

Będzie nieco większy bajzel. Zamiast mieć dokumentację we wszystkich
możliwych formatach wyjściowych lepiej mieć ją w jednym formacie
wejściowym + odpoowiednie filtry do uzyskania pdf, latex, ps, info, roff
output.

> To ma ta zalete ze mozna by sobie pewnie wyobrazic ze w takim wuchu ustawia sie
> instalowanie pakietow wraz z dokumentacja np: readable. I to dziala.

Cały kłopot polega na tym, że w takiej postaci dokumentacja to spory
kawałek całości. Przyjrzy sie dokumentacji GOWTO. Postać SGML to 26 MB
wynikowych rpm-ów (wszystkie języki). Po dodaniu do tego, ps, txt, html
robi się tego Kilka razy więcej objętościowo plików (prawie 13MB
wynikowych rpm-ów) i całość (już tylko HOWTO) zaczyna stanowić grubo ponad
20% objętości RH. Skutek tego był takie, że ktoś wpadł na pomysł, że
lepiej wogóle zrezygnować z dokumentacji w wersji podstawowej umieszczając
to obok dystrybucji. Ptzu ptzyjęciu, że dostarcza sie możliwie uniwersalną
postać źródłową (SGML) + narzedzia do przeglądania tego w możliwie róznych
warunkach zaczyna być to do przełknięcia, a po wybraniu tylko konkretnych
języków nie wybranie instalacji dokumentacji w instaklacji standalone
srv/wrks zaczyna być już mało rosądne bo całość po instalacji to bedzie
raptem paręnaście MB.
Stwarzanie warunków w których instalacja dokumentacji staje się bardziej
skomplikowana niż to być może w optymalnych warunkach lub kiedy
niepotrzebnie zaczyna się to komplikować nie powinno być naszym celem i to
już ze względu na to że tejże dokumentacji sami od czasu do czasu
potrzebujemy.

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*