(C) 2002 Pawe Paucha ISL project

$Id$

Ten plik opisuje, jak zainstalowa i uywa "Cocoon'owej" czci projektu ISL.

0. Spis treci:

1. Zawarto katalogu.
2. Instalacja.
3. Struktura katalogu isl.
4. Dodawanie nowych plikw.


1. Zawarto katalogu.

Katalog zawiera nastpujce pliki i katalogi:
	
	- README.TXT - plik z opisem instalacji i podstawowymi informacjami
	- isl	     - katalog, zawierajcy dane dla Cocoona


2. Instalacja.

Instalacja polega na kilku prostych krokach. Zakadam, e Cocoon zosta
zainstalowany na Tomcacie 4 (opis instalacji Cocoona - patrz plik
../doc/COCOON-HOWTO.txt) i e znajduje si w katalogu 
/var/tomcat4/webapps/cocoon. Katalog ten bdziemy nazywa katalogiem gwnym 
Cocoona. 

Do tego katalogu kopiujemy katalog "isl" wraz z zawartoci. Nastpnie do pliku
sitemap.xmap w katalogu gwnym Cocoona do elementu <map:pipeline> (w
<map:pipelines> w <map:sitemap>) dodajemy nastpujcy wpisy:

<map:match pattern="isl/**">
   <map:mount uri-prefix="isl/" src="isl/" check-reload="yes"/>
</map:match>

<map:match pattern="isl">
   <map:redirect-to uri="isl/"/>
</map:match>

W pliku cocoon.xconf w katalogu gwnym Cocoona znajdujemy nastpujcy 
fragment:

 <event-pipeline
 	class="org.apache.cocoon.components.pipeline.CachingEventPipeline"
        logger="core.event-pipeline"
	pool-max="32" pool-min="16" pool-grow="4"/>

Zamieniamy go na:

<event-pipeline
 	class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"
        logger="core.event-pipeline"
	pool-max="32" pool-min="16" pool-grow="4"/>
				     
(dodajemy "Non" przed "CachingEventPipeline").

To wszystko! Jeli chcemy, aby "isl" byo domylnym kontekstem cocoona, naley
jeszcze w pliku 'sitemap.xmap' w katalogu gwnym cocoona we fragmencie:

  <map:match pattern="">
    <map:redirect-to uri="welcome"/>
  </map:match>

zamieni "welcome" na "isl".

3. Struktura katalogu ISL.

Katalog isl zawiera nastpujce elementy:

- plik sitemap.xmap - Opisuje struktur generowanych stron, umiejscowienie
  plikw, zalenoci midzy nimi, sposb generowania danych wyjciowych. Nie ma
  potrzeby jego modyfikacji.
  
- katalog stylesheets - Zawiera szablony XSLT uywane do generowania danych
  wyjciowych. Nie ma potrzeby ich modyfikacji.

- katalog resources - Zawiera zasoby wsplne dla wszystkich generowanych stron.
  Nie ma potrzeby ich modyfikacji.

- katalogi odpowiedzialne za konkretne obiekty, np. "gliwice". Szczeglnym
  przypadkiem jest katalog "praterm", zawierajcy dane dla strony gwnej.
  Kady z tych katalogw ma nastpujc struktur:
  * katalog "docs" - zawiera dokumenty rdowe - isl (czyli specjaln odmian 
  SVG). S one przeksztacane na posta wyjciow zgodnie z zasadami opisanymi
  poniej. Zawarte tam dokumenty HTML, przeksztacane na posta wyjciow
  zawierajca ewetualnie zagniedone obrazki.
  * katalog "resources" - zawiera zasoby (np. obrazki, pliki html) dla 
  konkretnego obiektu. S one bezporednio odczytywane z tego katalogu (bez
  przeksztace).

Zasoby generowane s nastpujco: w przegldarce wpisywany jest adres w
postaci:
	[prefiks]/[obiekt]/[typ-danych]/[rdo]
gdzie:
	[prefiks] oznacza odwoanie do serwera Cocoon, katalogu isl. Dokadna
	posta jest zalena od konkretnej instalacji. Moe mie ona np. posta
	"http://localhost:8180/cocoon/isl".
	
	[obiekt] oznacza nazw obiektu (a dokadniej odpowiadajcego mu
	podkatalogu w katalogu "isl"), np. "gliwice", "praterm".
	
	[typ-danych] oznacza format informacji, jakie chcemy otrzyma.
	Aktualnie, dla rda bdcego plikiem ISL, dostpne s nastpujce:
	- png - obrazek w formacie Potrable Network Graphics.
	- svg - statyczny dokument SVG.
	- dsvg - dynamiczny dokument SVG (skrypty), odczytywany przez Batika
	- isl - oryginalny plik isl.
	Dla dokumentw HTML [typ-danych] powinien by pusty.

	[rdo] - oznacza nazw pliku z rozszerzeniem "isl", lub "html"
	znajdujcego si w podkatalogu "docs" katalogu obiektu.

Tak wic, jeli katalog "gliwice" w podkatalogu "docs" zawiera plik
"kociol1.isl", to aby zobaczy reprezentacj tego pliku w postaci obrazka png
naleaoby do przegldarki wpisa co w stylu:
http://localhost:8180/cocoon/isl/png/kociol1.isl.

Aby odwoa si do plikw z katalogu "resources", wystarczy poda bezporedni
ciek do nich.

UWAGA! Cocoon wymaga, aby wszystkie parsowane przez niego pliki korzystay z
kodowania UTF-8. W szczeglnoci, prba uycia polskich liter w kodowaniu
ISO-8859-2 czy cp-1250 spowoduje bd parsera XML. Do przekodowywania plikw
mona uy np. programu "iconv".


4. Dodawanie nowych plikw.

Dodawanie nowych plikw i obiektw, oraz modyfikacja istniejcych jest prosta -
wystarczy utworzy odpowiednie katalogi i doda pliki lub zmodyfikowa
istniejce. Pliki musz by zapisane z kodowaniem UTF-8, musz zawiera 
deklaracje wszystkich uywanych przestrzeni nazw. Nie powinny zawiera DTD
zewntrznych (bo parser bdzie si do nich odwoywa).

Jeeli pliki ISL tworzymy za pomoc edytora SVG "sodipodi", naley podda je
po edycji nastpujcym przeksztaceniom:
- zamieni warto atrybutu "standalone" w nagwku XML na "yes"
- skasowa deklaracj DTD
- doda deklaracj przestrzeni nazw ISL do elementu SVG

