Opis

Projekt zakończony

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

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

Spotkania

Projekt

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 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}
  • Strike-through Text → \sout{}
  • Subscript$_{subscript}$
  • Superscript$^{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}
  • 1) → \footnote{}
  • 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 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

1)
footnote
pl/miw/miw08_dokulatex.txt · ostatnio zmienione: 2019/06/27 15:50 (edycja zewnętrzna)
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0