RE: Dokumentacja (długie, ale przeczytajcie proszę)

[Rafał Kleger-Rudomin]

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

On Mon, 1 Nov 1999, Jacek Konieczny wrote:

> On Mon, Nov 01, 1999 at 01:06:13AM +0100, Tomasz Kłoczko wrote:
> > > 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ł.
> 
> Mnie się ten pomysł wogóle nie podoba. A co przy uaktualnieniach
> dokumentacji? W końcu ludzie w PLD zajmowali by się tylko dokumentacją.

Nie. Chodzi o to by w przyszłości przy budowaniu pakietu dokumentacja była
przerabiana z texinfo i man (bo głównie o nie chodzi) _automatycznie_ na
Docbook (w wersji SGML lub od razu XML) i w
takiej postaci trzymana w dystrybucji. Kiedy będą już w powszechnym użyciu
przeglądarki XML będziemy do przodu.
Na razie ani z manów ani z info i tak nie można zrezygnować.

> Z drugiej strony, gdy twórcy programów tworzyli do nich dokumentację
> świadomie wybierali narzędzia i format i napewno mieli jakieś powody.
Strony mana pisze się ze względu na jego powszechność.
Dokumentację info - bo to oficjalny format GNU i są działające narzędzia.

Docbook liczy sobie wprawdzie osiem lat, ale w takich
zastosowaniach to ciągle nowość.

> Osobiście wolałbym, żeby PLD zawierało w miarę zunifikowany interfejs do
> najpopularniejszy formatów dokumentacji, a samą dokumentację zostawiało
> w formie w której jest rozprowadzana. 
> Moglibyśmy jedynie coś zmieniać, tam gdzie jest możliwość wyboru
> formatu.

> A co do dokumentacji, którą musimy zrobić do PLD - tu trzeba określić
> standard i sie jego trzymać.
> Mnie osobiście na JWL'99 przekonano do PDF-a, choć ma on swoje wady
> (trudno przeszukiwać). Napewno SGML jest dobrym kierunkiem - ale co
> dalej to nie jestem pewien.

PDF to raczej format wynikowy.
Poczytaj to co podał Ziemek Borowski:
	http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html
lub to co zgrubsza przetłumaczyłem:
	PLD-doc/SGML-DocBook/docbook-intro_pl/docbook-intro.html
zwłaszcza o ogólnych koncepcjach - 
dlaczego warto oznaczać treść nie formatki itp.

Jeśli chodzi o pisanie własnych rzeczy to właśnie najlepiej
żeby były od razu robione w docbooku.

Pozdrawiam
Rafał
 
> Według mnie dokumentacja powinna wyglądać mniej więcej tak:
>   - do każdej komendy przynajmniej minimalna strona "man"
>   - do każdego pakietu/zagadnienia jakiś HTML czy PDF
>   - z rzeczy które my tylko pakujemy - zostawiamy jak jest, w przypadku
>   mnogości formatów zostawiamy man/info i HTML



> Pozdrowienia,
>          Jacek
>