|
|
pl:miw:miw08_dokulatex [2008/06/14 11:38] gjn |
pl:miw:miw08_dokulatex [2019/06/27 15:50] |
====== 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: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 ====== | |
| |