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

Paweł Miczko (4AR) <mieczyslav@gmail.com>

Kowerter DokuWiki do LaTeX.
Zbadać poziom zaimplementowania oferowanych rozwiązań.
Zaimplementować.

====== Spotkania ======
  *[[pl:miw:miw08_dokulatex:projekt|przebieg prac nad projektem]]

====== Projekt ======
  *[[http://hyper.ia.agh.edu.pl/~miczkop/dokulatex.zip|plugin]] {{:pl:miw:miw08_dokulatex:dokulatex.zip|:pl:miw:miw08_dokulatex:dokulatex.zip}}
  *[[pl:miw:miw08_dokulatex:instrukcja|instrukcja instalacji pluginu]]

====== Sprawozdanie ======
====1. Cel projektu====
Celem projektu było stworzenie pluginu do DokuWiki, który konwertowałby jej strony do formatu LaTeX.
Konwerter obejmuje podstawową składnię wiki, a więc:
  * formatowanie tekstu
  * nagłówki
  * listy numerowane i nienumerowane
  * linki wewnętrzne i zewnętrzne
  * tworzenie odnośników
  * wstawianie grafiki
====2. Wykonanie====
Na potrzeby projektu założone zostało wiki znajdujące się pod adresem  
http://student.agh.edu.pl/~micz/dokuwiki-2007-06-26b.

Prace nad projektem rozpoczęły się od określenia wstępnej specyfikacji fukcjonalności oraz scenariuszy użycia.

Funkcjonalności, jakie powinien wykazywać plugin, to przede wszystkim zamiana [[wiki:syntax|składni]] wiki na składnię latexa i tak na przykład:

  *czysty tekst parsujemy bez zmian

  * **Bold Text** -> \textbf{}

  * //Italic Text// -> \textit{}

  * __Underlined Text__ -> \underline{}

  * ''code'' -> \verb||

  dwie spacje -> \begin{verbatim}

  *<del>Strike-through Text</del> -> \sout{}

  *<sub>Subscript</sub> -> $_{subscript}$

  *<sup>Superscript</sup> -> $^{superscript}$

  *5 poziomów nagłówków, np.
  ======zzz====== -> /section{zzz} /label{zzz} (w celu póżniejszych odnośników)

  *- Ordered List Item -> \begin(enumerate} \item ... \end(enumerate}

  ** Unordered List Item -> \begin{itemize} \item ... \end{itemize}

  *[[http://link.zewnetrzny]] -> \url{http://link.zewnetrzny}

  *[[linkwewnętrzny]] -> \ref{linkwewnętrzny}

  *((footnote)) -> \footnote{}

  *{{Grafika|caption}} -> \begin{figure} \includegraphics{Grafika} \caption{caption} \end{figure}

Zdefiniowano 3 możliwe przypadki użycia:
  * 1str.wiki->1dok
  * zbiór str. z podanego ns (zadane wyr. regularnym) ->1 dok
  * cały ns -> 1 dok

Do realizacji wybrany został jeden z nich:
  * 1str.wiki->1dok

Do stworzenia pluginu wybrany został język PHP. Parser został napisany obiektowo (z zastosowaniem klas).

  *Stałe(definiowane poza klasą):
    * F_WIKI - przechowuje nazwę katalogu, w którym znajdują się strony.
  *Atrybuty:
    * $last_loaded - przechowuje nazwę ostatnio wczytanego pliku.
    * $unparsed - przechowuje niezamieniony kod stron,
    * $parsed - przechowuje zamieniony kod stron,
    * $blocks - przechowuje bloki do zamiany.
  *Operacje:
    * load() - wczytuje kod strony i zapisuje go jako kolejny element tablicy $unparsed
    * parse() - parsuje stronę i zapisuje wynik swojego działania jako kolejny element tablicy $parsed
    * show_result() - wyświetla sparsowaną stronę/strony

Funkcja konwertująca parse() działa na bazie wyrażeń regularnych i PHPowskiej funkcji preg_match_all.

Prace nad projektem zakończyły się spakowaniem pluginu i stworzeniem [[pl:miw:miw08_dokulatex:projekt|instrukcji]] obsługi potrzebnej do jego instalacji. Dokonuje się jej za pomocą plugin managera.

Po prawidłowym zainstalowaniu pluginu u góry każdej strony w Wiki obok przycisków "Edytuj stronę" i "Poprzednie wersje" pojawia się przycisk "Konwertuj do Latexa". Po jego naciśnięciu zostaje wywołana odpowiednia funkcja i otwiera się nowe okno zawierające przetworzony do Latexa kod. Kod ten może zostać bezpośrednio przekopiowany do edytora tekstu LaTeXa i skompilowany.

Ostatnim etapem prac było napisanie niniejszego sprawozdania.
====3. Zasadzki====
W trakcie prac nad projektem okazało się, że konieczna będzie odpowiednia obsługa 10 znaków specjalnych TeXa: { , }, \, $, _, %, &, ~, ^, # które w wiki nie sprawiają problemów, ale po przeklejeniu w niezmienionej postaci powodowałyby błędy w kompilacji. Zostały one dołączone do listy rzeczy do zrobienia i odpowiednio załatwione.

Spośród wymienionych na początku funkcjonalności nie wszystkie było jednakowo łatwo zrealizować. Przykładowo, przy bardzo rozbudowanych listach, z wieloma poziomami zagnieżdżenia, plugin nie zawsze sobie radzi. Mogą powstać drobne błędy konwersji, które można poprawić ręcznie.

Mimo usilnych starań nie udała się realizacja funkcjonalności, która rozpoznawałaby na wejściu
  taki tekst
i wstawiała go do środowiska verbatim. Jest to jedyna funkcjonalność, której nie udało się zrealizować. Kod wygląda poprawnie, lecz nie działa.. Zostaje to do realizacji przez przyszłe pokolenia.
====4. Możliwości kontynuacji====
Zdecydowana większość funkcjonalności założonych przy specyfikacji została zrealizowana. Nie oznacza to jednak, że plugin nie może zostać rozbudowany.
Przede wszystkim można zająć się dwoma pozostałymi scenariuszami użycia:
  * zbiór str. z podanego ns (zadane wyr. regularnym) ->1 dok
  * cały ns -> 1 dok
Ponadto, zająć się można bardziej zaawansowanymi strukturami składniowymi wiki, jak choćby tabele. Należałoby też zmusić nieszczęsny verbatim do zadziałania...
====== Materiały ======