Dokumentacja

Opis działania parsera z \latex do Wiki

Program tex.py dokonuje konwersji podstawowych elementów dokumentu przygotowanego w \latex do formatu stosowanego w Wiki. Do działania programy niezbędna jest obecność pliku wzorce.xml w katalogu, w którym uruchamiamy program. Plik wzorce.xml zawiera definicje wg. których program przetwarza plikina format \latex.

Elementy które nie znalazły się w definicjach to:

• tabele
• wypunktowania

Pozostałe elementy zawarte są w pliku wzorców i można je dowolnie modyfikować i dodawać własne. Celem programu jest ułatwienie pracy, jeżeli musimy ręcznie zamineiać w całym pliku jakieś oznaczenia na inne, program nas w tym doskonale wyręczy, o ile odpowiedznie zdefiniujemy nasze potrzeby.

Wyrażenia

Ponieważ we wzorcach do odnajdywania elementów tekstu do zamiany, używamy wyrażeń rególarnych, pozawalam sobie tytułem przypomnienia napisać na ich temat słów kilka. Wyrażenia rególarne są powszechnie przyjętą metodą wyszukiwania wzorców w tekście. Uproszczonym ich odpowiednikiem jest tzw. dzikie karty stosowane w przeszukiwaniu plików, np. *.exe jest wzorcem do którego pasują wszystkie pliki kończące się na exe. W wyrażeniach rególarnych odpowiada mu wzorzec .*\.exe, gdzie:

• . odpowiada dowolnemu znakowi
• * oznacza dowolną ilość powtórzeń (tu dowolnego znaku)
• \. oznacza po prostu kropkę, ponieważ kropce zostało przypisane specjalne znaczenie, jeżeli chcemy powiedzieć że w danym miejscu ma się znajdować właśnie kropka a nie dowlny znak, musimy ją poprzedzić znakiem \
• exe czyli w tym miejscu mają się znajdować właśnie takie litery

Proszę się nie obawiać, wyrażenia rególarne zostałe użyte w podstawowym zakresie, można więc założyć źe krótka instrukcja i analiza kilku przykładów powinna umoźliwić definiowanie wzorców. Teraz podam kilka najważniejszych znaków specjalnych używanych w tworzeniu wzorców:

• . dowolny znak
• $ początek wiersza
• ^ koniec wiersza
• \ powoduje że następujący po nim znak jest traktwany jak zwykła litera
• * poprzedzający gwazdkę znak może sie powtórzyć dowolną ilość razy (lub nie wystąpić wogóle)
• + poprzedzający znak musi wystąpić co najmniej raz, lub więcej razy

Szczególną rolę odgrywają nawiasy, tekst ujęty nawiasami może szostać użyty w dalszym przetwarzaniu tekstu. Przy tworzeniu wzorców należy pamiętać żeby znaki mające specjalne znaczenie, jeżeli wystąpią we wzorcu poprzedzać \ takie znaki wymagające poprzedzenia to np.:

• \}
• \{
• \[
• \]
• \$
• \*

Rodzaje wzorców

wzorce.xml to plik xml zawierający następujące typy wzorców:

wzorzec

prosta zamiana linii odpowiadającej wzorcowi na zadany tekst

Np. aby zamienić

\section{ala ma kota}

Na:

=ala ma kota=

piszemy:

       <wzorzec>
           <re>\\section\{(.*)\}</re>
           <string>=%s=
</string>
       </wzorzec>
       

• re tu opisujemy jak ma wyglądać szukana linijka tekstu, jeźeli chcemy zachować część tej linii, otaczamy ją nawiasami, \{(.*)\} zapamięta dowlny tekst znajdujący się w nawiasach okrągłych
• string napis jaki ma się znależć w miejsce znalezionej linii tekstu, jeżeli zapamiętaliśmy jakąś część tekstu możemy ją tu wstawić pisząc %s

element

definiujemy wzorzec dla początku i końca bloku, string jaki ma być wpisany w początku i końcu bloku i definicje specjalnyc parametrów jakie mają być w tym bloku wyszukane. Np. mamy zamienić:

\begin{dfn}[lalala]
\label{bleble}
bla bla bla
blu blu
\end{dfn}

Na:

{{definicja|lalala|bleble| bla bla bla blu blu }}

Wzorzec który tego dokona wygląda następująco:

      <element>      
           <begin>
               <re>\\begin\{dfn\}</re>
               <string>{{definicja|%(nazwa)s|%(etykieta)s|</string>
           </begin>
           <end>
               <re>\\end\{dfn\}</re>
               <string>}}</string>
           </end>
           <param name="nazwa">
               <re>\\begin\{dfn\}\[(.*)\]</re>
           </param>
           <param name="etykieta">
               <re>\\label\{(.*)\}</re>
           </param>
       </element>
       

Przeanalizujmy zatem przykład:

• begin definiuje początek bloku, elementy definicju bloku to są wzorce, z tym szczególęm że używamy tu parametrów nazwanych czyli zamiast %s piszemy %(nazwa)s
• end definicja końca bloku, wszystko co się znajduje między początkiem a końcem bloku jest traktowane jako część bloku.
• param definicja parametru, w podanym przykłdzie musimy znaleźć w bloku nazwę (tutaj lalala) i etykietę (tutaj bleble), aby ich użyć w stringu dla początku bloku

jezyk

To chyba najprostszy z wzorców.

       <jezyk nazwa="C">
           <slowo>auto</slowo>
           <slowo>break</slowo>
       </jezyk>

Definicja języka zawiera nazwę, i słowa kluczowe, blok z kodem żródłowym o wskazanej nazwie zostanie przesunięty o jedną spację, tabulacje zostaną zamienione na 2 spacje, a słowa kluczowe zostaną wyróżnione.