====== Opis ======
__**Projekt zakończony**__

Michał Kotra, <mkotra@student.agh.edu.pl>

[[misc:GraphViz]] plugin dla Dokuwiki, renderowanie diagramow z zamieszczonego w wiki kodu DOT oraz plikow umieszczanych w wiki.

====== Spotkania ======


===== 08.02.26 =====
co jest/czego brakuje w http://wiki.ioslo.net/dokuwiki/graphviz/
  * znaleziony plugin został przetestowany z dokuWiki i działa poprawnie. Wersja zapewnia podstawową funkcjonalność, tj. renderowanie diagramów z zamieszczonego w wiki kodu DOT (kod musi byc obłożony tagami: ''<graphviz mode></graphviz>'' (przy czym mode = dot, neato, twopi, circo, fdp). Działanie zostało przetestowane na systemie Linux z zainstalowaną dokuWiki 2007-06-26b oraz graphviz w wersji 2.12-4. 
  * plugin nie umożliwia generowania kodu z zamieszczonych gotowych plików DOT. Należałoby zatem dopisać taką funkcjonalność do istniejącego kodu. 
  * dodatkowo istnieje możliwość włączenia obsługi generowania diagramów uml (wymaga jeszcze przetestowania) [[http://www.spinellis.gr/sw/umlgraph/|Uml Graph]] [[http://java.sun.com/javase/downloads/index.jsp|Sun Java 5 Jsdk]] 


===== 08.03.11 =====
  * prototyp czytania z pliku dot w wiki, uwaga:

  <graphviz file="pl:miw:costam.dot"></graphviz>

  * Do istniejącego pluginu została dopisana żądana funkcjonalność. Możliwe jest korzystanie z plików *.dot, ścieżki do plików korzystają z przestrzeni nazw tak jak w przykładzie. 

  * Dodano obsługę adresów url 

  <graphviz url="http://www.costam.org/costam.dor"></graphviz>

  * Wersja testowa pluginu znajduje się pod adresem: http://student.agh.edu.pl/~mkotra/graphviz.tar

  * Aby możliwe było zamieszczanie w wiki plików *.dot niezbędne jest dodanie w pliku conf/mime.conf linii: 

  dot    application/graphviz 







===== 080401 =====
  * naprawa bugów
  * testy na stronie [[pl:miw:miw08_dokuviz:notatki]]
  * poprawiono obsługę url, wykorzystując narzędzie [[http://curl.haxx.se/|Curl]]
  * graphviz od razu generuje png [bez zbędnej konwersji ps-png]
  * dodanie możliwości ustawienia parametrów width i height '' height="300" width="800"''
  * aktualna wersja: http://student.agh.edu.pl/~mkotra/graphviz.tar




===== 080415 =====
  * sprawozd
  * debug - graphviz 
  * protot prologu - zrobiony, pokażę na konsultacjach


===== 080429 =====
  * obsługa scope?
  * popr do sprawozd






===== 080520 =====
Opis problemow z cache
   * Wiki w cache zapamiętuje jedynie wynikową stronę, stąd konieczne okazuje się przeglądnie stron w wiki w poszukiwaniu kodu prologu. W przypadku dużej ilości stron, przeszukiwane musiałyby być wszystkie strony znajdujące się w wiki. Zaproponowane rozwiązanie wykorzystuje osobny cache, dla kodu prologu. Jeżeli na stronie zostanie napotkany kod prologu z włączoną opcją cache="true" dla strony zostanie utworzony osobny plik w katalogu wiki/lib/plugins/tmp+(ścieżka taka jaką ma plik w wiki). Przy przeszukiwaniu dostępnego kodu prologu, zostaną zatem przeszukane tylko te pliki, a nie cała data zgromadzona w Wiki. Korzystne w sytuacji kiedy stosunkowo niewielka część stron zawiera kod prologu, który należy cache'ować. 
   * Drugim problemem jest fakt, że cache zależy od zawartości aktualnej strony. Jeżeli nastąpi zmiana strony w wiki, cache na innej stronie nie wykryje jej. Rozsądnym rozwiązaniem wydaje się wyłączenie cache na stronach, na których chcemy podać goal i otrzymać wynik działania prologu.
<code>~~NOCACHE~~</code>

  * prototyp - działa na razie lokalnie, umożliwia zadawanie scope, z którego będzie korzystał prolog, w ścieżce dopuszczane są wyrażenia regularne.

  * wstępna wersja do pobrania: http://student.agh.edu.pl/~mkotra/prolog.tar

  * przykład:
<code xml> 
<prolog scope="raz:dwa:trzy" goal="kobieta(X),write(X),nl,fail" cache="true">
kobieta(anna).
</prolog>
</code>

===== 080527 =====
  * testowanie pluginu
  * sprawozdanie (MK)
  * email sync

===== Na kiedyś =====

<del>na przyszłość:
  * dokuviewvc, patrz http://viewvc.org/ (embedded)
  * dokutrac, patrz: http://cvstrac.org/, http://trac.edgewall.org/</del>

Prostsza i lepiej zdefiniowana propozycja:
plugin do wiki do uruchamiania Prologu, scenariusze użycia:
  * zadaję pluginowi kod i goal

  <prolog goal="kobieta(X),write(X),nl,fail">
  kobieta(kasia).
  mezczyzna(jasiu).
  </prolog>

  * zadaję pluginowi nazwę pliku z kodem w wiki i goal

  <prolog goal="kobieta(X)" file="pl:miw:test.pl">
  </prolog>

  <prolog goal="kobieta(X) url="http://costam.org/test.pl">
  </prolog>


  * mogę skojarzyć z każdą strona wiki kod prologu, zadaję pluginowi goal i scope: interpretowanie tylko tej strony, zbioru stron, np. namespace

  <prolog goal="kobieta(X)" scope="."> ta str
  <prolog goal="kobieta(X)" scope="pl:miw:proj"> podana str
  <prolog goal="kobieta(X)" scope="pl:miw:"> namespace
  <prolog goal="kobieta(X)" scope="pl:miw:proj.*08"> regexp


  <prolog>
  kobieta(kasia).
  mezczyzna(jasiu).
  </prolog>

  * pytania:
    * co z frag prolog z goal? też merge
    * co z cache -> scenariusze?
    * jak zadawać scope, co może Panu przeszukać wiki? regexp
    * defaultowe wypisywanie w celu?
<code>
    <prolog goal="kobieta(X),write(X),nl,fail">
    <prolog goal="kobieta(X)" wrt="y">
</code>
  * mieszana składnia wiki... -> msc

====== Projekt ======

[[pl:miw:miw08_dokuviz:testy|Testy pluginu na osobnej stronie]]





====== Sprawozdanie ======

FIXME

[[pl:miw:miw08_dokuviz:sprawozdanie]]


===== Wstęp =====
  * celem zadania było utworzenie pluginu dla Dokuwiki umożliwiającego renderowanie diagramów z zamieszczonego kodu DOT, oraz plików umieszczonych w wiki.



===== Rozbudowa istniejącego pluginu =====
Graphviz plugin dla Dokuwiki został oparty na znalezionym rozwiązaniu http://wiki.ioslo.net/dokuwiki/graphviz/
Wersja ta obsługiwała podstawową funkcjonalność, tj. renderowanie diagramów z zamieszczonego w wiki kodu dot.
W stosunku do znalezionej w sieci wersji wprowadzono następujące ulepszenia:
  * możliwość renderowania diagramów z zamieszczonych w wiki plików dot
  * możliwość renderowania diagramów z plików dot znajdujących się w sieci, poprzez podanie ścieżki url. Funkcjonalność ta została osiągnięta, dzięki wykorzystaniu narzędzia Curl.
  * dodano możliwość zdefiniowania wysokości i szerokości renderowanych diagramów
  * poprawiono sposób generowania plików png, gdyż w poprzedniej wersji zastosowane nieoptymalne rozwiązanie powodujące utratę jakości.

===== Instalacja pluginu =====
  * plugin dostarczony jest w postaci archiwum TAR. Instalacja polega na wskazaniu odpowiedniej lokalizacji w managerze pluginów Dokuwiki. Dalszy proces instalacji przebiega automatycznie. 
  * aby możliwe było zamieszczanie w wiki plików *.dot niezbędne jest dodanie w pliku conf/mime.conf linii: 

  dot    application/graphviz
===== Sposób użycia =====
  * aby kod dot został przetworzony należy umieścić go pomiędzy odpowiednimi tagami, tak jak pokazano w poniższym przykładzie:
  <code> <graphviz>KOD DOT</graphviz> </code>
  * przykładowo po wpisaniu kodu:
  <code><graphviz>
  digraph G {
     a -> b;
  }
</graphviz></code>
uzyskany zostanie następujący efekt:

<graphviz>
digraph G {
   a -> b;
  }
</graphviz>
  * istnieje możliwość wczytania pliku DOT zamieszczonego w wiki, np. 
  <code><graphviz file="pl:miw:plik.dot"></graphviz></code>
  * można również wczytać plik DOT znajdujący się pod wskazanym adresem URL (do odczytania zawartości pliku plugin wykorzystuje narzędzie [[http://curl.haxx.se/|Curl]]). 
  <code><graphviz url="http://.../plik.dot"></graphviz></code>
  * istnieje możliwość wyboru stylu grafu (domyślnie dot) spośród dostępnych opcji: dot, neato, twopi, circo, fdp 
  <code> <graphviz neato>KOD DOT</graphviz> </code>
  * można ustalić rozmiar renderowanej bitmapy ustawiając odpowiednie wartości parametrów width i height:
  <code><graphviz height="300" width="800">KOD DOT</graphviz></code>
  * Bardziej rozbudowany przykład użycia:
  <code><graphviz neato file="pl:miw:plik.dot" width ="100" height="50"></graphviz></code>




===== Prolog plugin dla DokuWiki=====

Kolejnym celem było zbudowanie pluginu dla DokuWiki umożliwiającego uruchamianie kodu prologu. Plugin miał umożliwić podanie bazy wiedzy w postaci, kodu, adresu url, lub pliku zamieszczonego w wiki, oraz celu. Po zapisaniu strony miał zostać wyświetlony efekt działania. Dodatkowo należało umożliwić cache'owanie kodu prologu zgromadzonego na stronach DokuWiki, oraz zadawanie przestrzeni nazw (również w postaci wyrażeń regularnych), która miała zostać przeszukana. 

===== Instalacja pluginu=====
  * plugin dostarczony jest w postaci archiwum TAR. Instalacja polega na wskazaniu odpowiedniej lokalizacji w managerze pluginów Dokuwiki. Dalszy proces instalacji przebiega automatycznie. 

===== Sposób działania =====
    * aby kod Prologu został przetworzony należy umieścić go pomiędzy odpowiednimi tagami, oraz zadać goal i określić co chcemy wypisać:
<code xml>
<prolog goal="kobieta(X),write(X),nl,fail">
kobieta(kasia).
mezczyzna(jasiu).
</prolog>
</code>

  * istnieje również możliwość podania pliku w wiki:
<code xml>
<prolog goal="kobieta(X),write(X),nl,fail" file="pl:miw:test.pl">
</prolog>
</code>

  * lub adresu url:
<code xml>
<prolog  goal="kobieta(X),write(X),nl,fail" url="http://costam.org/test.pl">
</prolog>
</code>

  * dodatkowa funkcjonalność to możliwość cache'owania zgromadzonego na poszczególnych stronach kodu prologu, i określenie przestrzeni która ma zostać przeszukana. Przy podawaniu scope można stosować wyrażenia regularne, tak jak w przypadku grepa. PRzy czym ".*" określa całą przestrzeń wiki:
<code xml>
<prolog goal="kobieta(X),write(X),nl,fail" scope="pl:miw:proj.*08">
</prolog>
</code>

  * jeżeli chcemy jedynie zapamiętać w cache kod należy zastosować następującą składnię:
<code xml>
<prolog cache="true">
kobieta(anna).
</prolog>
</code>



===== Zasadzki =====
W związku ze sposobem działania mechanizmu cache w Dokuwiki istnieje możliwość, że plugin nie zadziała poprawnie. Nie wgłębiając się w szczegóły mechanizm cache w Dokuwiki wywołuje plugin podczas zapisywania dokumentu. Sam plugin renderuje diagramy w przypadku, gdy natrafi na kod, którego nigdy wcześniej nie renderował. W przeciwnym przypadku zostanie załadowany obrazek przechowywany w pamięci cache. Może się zatem zdarzyć, że renderując diagram z zewnętrznego pliku który ulegnie zmianie, plugin tych zmian nie wykryje gdyż podany kod:
  "<graphviz url=".."></graphviz>" 
będzie w obu przypadkach identyczny. W razie wystąpienia tego typu problemów pomóc powinno wyczyszczenie zawartości katalogu:
  wiki/data/media/graphviz
Można również użyć opcji NOCACHE -> http://wiki.splitbrain.org/wiki:caching



==== Testy ====
[[pl:miw:miw08_dokuviz:testyprolog]]

[[pl:miw:miw08_dokuviz:testyprolog2]]

====== Materiały ======
  * http://wiki.ioslo.net/dokuwiki/graphviz
  * http://wiki.splitbrain.org/wiki:plugins:syntax
  * http://wiki.splitbrain.org/wiki:plugins:syntax_tutorial