WWW: Nowy system do dokumentacji

[Rafał Kleger-Rudomin]

Cześć,
list pld-www wydaje się martwa więc piszę na główną:

Zrobiłem nowy 'framework' do robienia dokumentacji użytkownika,
Jest w module PLD-doc/doc (na razie jest tam tylko wsadzona
instrukcja do prowizorki Marcina Chojnowskiego, którą
znalazłem w PLD-doc/docmanual)

O co chodzi:
Dotychczasowy system tworzenia dokumentacji, ten stosowany
w module PLD-doc/docdevel do dokumentacji devel jest 
skomplikowany i bałaganiarski. Zasadniczą jego wadą
jest nastawienie na produkcję htmli pod kątem www co 
prowadzi do tego że żeby pracować nad dokumentacją trzeba mieć
zaistalowanego i poprawnie skonfigurowanego apacha z php.
Dodatkowym utrudnieniem jest konieczność samodzielnego
babrania się z wynikowymi htmlami w celu puszczenia ich na www.
W wyniku tego krąg osób zajmujących się dokumentacją w praktyce jest 
zawężony do osób związanych z www.

Nowy system został przygotowany w myśl założeń:
- ma to być moduł niezależny od www
- generowanie htmli dla www (odpowiednio przystosowanych 
  do wkomponowania w serwis www) odywać się ma po stronie serwera.
- każdy kto chce pisać dokumentację może sobie wygenerować
  htmle gotowe do poczytania wprost z filesystemu
- wynikowe htmle nie będą wogóle trzymane w cvsie, piszący dokumentację
  zajmują się jedynie źródłami docbookowymi.
  
Cechy nowego systemu:
- dokumentacja w Docbook _XML_
- przygotowanie do obsługi wielu wersji językowych


Jak to wygląda:

Katalog doc zawiera katalogi dla poszczególnych podręczników,
katalog common z różnymi dodatkowymi plikami oraz Makefile 
i ew. różne README. Każdy katalog z docami jest podzielony 
na podkatalogi z wersjami językowymi:

        doc
        +-common
        +-podręcznik_n
        | +-en
        | +-pl
        | +-Makefile
        ...
        +-Makefile
        +-README

Postawowy cel w głównym Makefile ('make') to wygenerowanie
zwykłych htmli ,,do poczytania''. 
Htmle są tworzone w tych samych katalogach co ich źródła,
W głównym katalogu tworzone są pliki index.html ze spisem podręczników,
po jednym na każdy język:

        ...
        +-index.en.html
        +-index.pl.html

Startując z tych plików osoba pracująca nad docami może
sobie pooglądać przekonwertowaną dokumentację wprost z dysku.
I to wszystko co jest potrzebne człowiekowi piszącemu/poprawiającemu doce.



Dla potrzeb serwera www jest dodatkowy cel 'make www WWWDIR=...',
który htmle, uprzednio skonwertowane za pomocą 'make',
przenosi w podane miejsce (WWWDIR) tworząc tam (w razie potrzeby) 
odpowiednią strukturę katalogów.
Dodatkowo pliki są przerabiane na potrzeby serwisu
(dodawane menu i nagłówki/stopki)

Teraz wady:
Ponieważ przy okazji robienia czegoś nowego skorzystałem z okazji
i przeskoczyłem od razu na XML, do konwersji potrzebna jest java,
bo większość narzędzi do XML w tym języku powstaje.


Ogólnie do konwersji potrzebne są następujące rzeczy:
- skrypty z katalogu PLD-doc/scripts
- java (mamy w PLD ibm-java ale tylko ix86 :( )
- xp
- xt
- docbook-dtd41-xml
- docbook-style-xsl
- iconv

Pytanie do administratorów serwera www:
Czy jest możliwość by konwertowanie zachodziło automatycznie
co jakiś czas bezpośrednio na serwerze www? (Jeśli nie, to można 
to robić na innej maszynie, a serwer www by to jedynie ściągał)

Czekam na uwagi.

Pozdrawiam,
Rafał

-- 
Rafał Kleger-Rudomin (klakier w pld.org.pl)