Both sides previous revision
Poprzednia wersja
Nowa wersja
|
Poprzednia wersja
|
pl:miw:miw08_dokulatex [2008/05/13 16:35] miw |
pl:miw:miw08_dokulatex [2019/06/27 15:50] (aktualna) |
====== Opis ====== | ====== Opis ====== |
| __**Projekt zakończony**__ |
| |
Paweł Miczko (4AR) <mieczyslav@gmail.com> | Paweł Miczko (4AR) <mieczyslav@gmail.com> |
| |
| |
====== Spotkania ====== | ====== Spotkania ====== |
| *[[pl:miw:miw08_dokulatex:projekt|przebieg prac nad projektem]] |
===== 08.02.26 ===== | |
* kto już cos z tym robił? | |
* http://danjer.doudouke.org/tech/dokutexit | |
* wstępna spec. funkc. | |
| |
===== 08.03.11 ===== | |
* scenariusze użycia | |
* 1str.wiki->1dok | |
* zbiór str. z podanego ns (zadane wyr. regularnym) ->1 dok | |
* cały ns -> 1 dok | |
| |
| |
| |
| |
===== 080401 ===== | |
* prototyp: 1str.wiki->1dok | |
* customizowalne poziomy section | |
* standalone (generowanie prologu LaTeXa) / embedded (do włączenia, tylko treść dokuemntu) | |
* plugin NIE używa samego LaTeXa! generujemy czysty plik TEX | |
| |
| |
| |
===== 080415 ===== | |
* postawione wiki! | |
| |
| |
| |
===== 080429 ===== | |
* [[http://wiki.splitbrain.org/wiki:plugins?plugintag=button|guziczki]] | |
* //ala:// pusta linia i jestesmy w itemize/enum -> enditem/enum | |
- aaa | |
* quoting znaków texa!!!! | |
| |
{ -> $\lbrace$ | |
} -> $\rbrace$ | |
$ -> \$ | |
_ -> \_ | |
\ -> $\$ | |
nie działa - trzeba przez $\backslash$ | |
| |
| |
| |
===== 080520 ===== | |
* testowanie, do zainst. -> instr | |
* import latexa do wiki | |
http://wiki.splitbrain.org/plugin:latex | |
http://wiki.erazor-zone.de/doku.php?id=wiki:projects:php:dokuwiki:plugins:latex | |
| |
====== Projekt ====== | ====== Projekt ====== |
aspekty: | *[[http://hyper.ia.agh.edu.pl/~miczkop/dokulatex.zip|plugin]] {{:pl:miw:miw08_dokulatex:dokulatex.zip|:pl:miw:miw08_dokulatex:dokulatex.zip}} |
* co tłumaczymy, https://ai.ia.agh.edu.pl/wiki/wiki:syntax | *[[pl:miw:miw08_dokulatex:instrukcja|instrukcja instalacji pluginu]] |
* struktura: sub/sections | |
* \label{stronawiki_naglowek}/ref | |
| |
===== 08.02.26 ===== | ====== 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. |
| |
czysty tekst parsujemy bez zmian; | Prace nad projektem rozpoczęły się od określenia wstępnej specyfikacji fukcjonalności oraz scenariuszy użycia. |
| |
**Bold Text** -> \textbf{} | Funkcjonalności, jakie powinien wykazywać plugin, to przede wszystkim zamiana [[wiki:syntax|składni]] wiki na składnię latexa i tak na przykład: |
| |
//Italic Text// -> \textit{} | *czysty tekst parsujemy bez zmian |
| |
__Underlined Text__ -> \underline{} | * **Bold Text** -> \textbf{} |
| |
<del>''Code Text'' -> begin{verbatim}</del> FIXME | * //Italic Text// -> \textit{} |
| |
''code'' -> \verb|| | * __Underlined Text__ -> \underline{} |
dwie spacje na pocz jak poniżej -> \begin{verbatim} | |
| |
ala ma kota | * ''code'' -> \verb|| |
| |
<del>Strike-through Text</del> -> \sout{} | dwie spacje -> \begin{verbatim} |
| |
- Ordered List Item -> \enumerate | *<del>Strike-through Text</del> -> \sout{} |
| |
* Unordered List Item -> \itemize | *<sub>Subscript</sub> -> $_{subscript}$ |
| |
Linki zewnętrzne -> \url | *<sup>Superscript</sup> -> $^{superscript}$ |
| |
do sections subsections trzeba by utworzyć jakiś licznik, w zależności od tego ile jest poziomów zagnieżdżenia | *5 poziomów nagłówków, np. |
| ======zzz====== -> /section{zzz} /label{zzz} (w celu póżniejszych odnośników) |
| |
===== 08.03.11 ===== | *- Ordered List Item -> \begin(enumerate} \item ... \end(enumerate} |
| |
Powstaje pytanie: gdzie dokładnie w strukturze dokuwiki znajdują sie kody źródłowe stron? Czy jest to struktura drzewiasta, np. dla każdego | ** Unordered List Item -> \begin{itemize} \item ... \end{itemize} |
ns jest osobny folder a w nim pliki z tego ns? Jeśli tak to możnaby poprzez wybór parametru wybierać które strony mają być sparsowane, np. | |
* nazwa 1 konkretnej strony | |
* wiele stron po przecinku | |
* nazwa_ns/*.txt lub po prostu nazwa ns | |
| |
Jeśli będziemy konwertować zbiór stron do jednego pdfa, to będą one wyróżnione jako \chapter{}. Jednak będzie to głupio wyglądało... | *[[http://link.zewnetrzny]] -> \url{http://link.zewnetrzny} |
Dużo lepszym rozwiązaniem byłoby \chapter*, wtedy nie mamy słowa Rozdział, jednak wtedy \ref{} nie działa i jest jeszcze gorzej... | |
Natomiast w obrębie jednej strony kolejne poziomy nagłówków konwertowane będą do: | |
*\section{} | |
*\subsection{} | |
*\subsubsection{} | |
*\paragraph{} | |
*\subparagraph{} | |
* odnośniki: w obrębie 1 dok LaTeX label/ref | |
* nazwy stron i nagłowki ''==========='' -> label | |
* odnośniki wewn. ''[[...]]'' (bez http) wiki, które dot. generowanego dok latex -> ref | |
np. dla tej strony będzie to wyglądało mniej więcej: | |
<code> | |
\begin{document} | |
\maketitle | |
\chapter{miw08_dokulatex} | |
\label{miw08_dokulatex_main} | |
\section{Opis} | |
\label{miw08_dokulatex_Opis} | |
Paweł Miczko (4AR) | |
Kowerter DokuWiki do \LaTeX{}. Zbadać poziom zaimplementowania oferowanych rozwiązań. Zaimplementować. | |
| |
| *[[linkwewnętrzny]] -> \ref{linkwewnętrzny} |
| |
\subsection{Spotkania} | *((footnote)) -> \footnote{} |
\label{miw08_dokulatex_Spotkania} | |
| |
\subsubsection{08.02.26} | *{{Grafika|caption}} -> \begin{figure} \includegraphics{Grafika} \caption{caption} \end{figure} |
\label{miw08_dokulatex_08.02.26} | |
| |
\begin{itemize} | Zdefiniowano 3 możliwe przypadki użycia: |
\item kto już cos z tym robił? | * 1str.wiki->1dok |
\item * \url{http://danjer.doudouke.org/tech/dokutexit} | * zbiór str. z podanego ns (zadane wyr. regularnym) ->1 dok |
\item wstępna spec funkc | * cały ns -> 1 dok |
\end{itemize} | |
\subsection{Projekt} | |
\label{miw08_dokulatex_Projekt} | |
aspekty: | |
\begin{itemize} | |
\item co tłumaczymy, \url{https://ai.ia.agh.edu.pl/wiki/wiki:syntax} | |
\item struktura: sub/sections | |
\end{itemize} | |
| |
</code> | Do realizacji wybrany został jeden z nich: |
| * 1str.wiki->1dok |
| |
Przy włączeniu pakietu hyperref w miejscu użycia ref pojawi się hiperłącze do danego labela. Przykładowo, gdybyśmy dodali kolejną stronę z namespace'u, odnośnik wyglądałby tak: | Do stworzenia pluginu wybrany został język PHP. Parser został napisany obiektowo (z zastosowaniem klas). |
<code> | |
\chapter{jakastamstrona} | |
\label{jakastamstrona_main} | |
Projekt DokuLatex znajduje się tutaj: \ref{miw08_dokulatex_main} (...) | |
</code> | |
* narzędzia, PHP? jakieś wsparcie? po stronie wiki? | |
| |
Kody źródłowe przetwarzamy przy pomocy PHP. Parser zostanie napisany obiektowo(czyt. z zastosowaniem klas), zastanówmy się więc najpierw jakie | *Stałe(definiowane poza klasą): |
powinien posiadać funkcje(operacje) i zmienne(atrybuty). | * 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 |
| |
Wynik: | Funkcja konwertująca parse() działa na bazie wyrażeń regularnych i PHPowskiej funkcji preg_match_all. |
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'' | |
| |
| 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. |
| |
===== 08.04.01 ===== | Ostatnim etapem prac było napisanie niniejszego sprawozdania. |
Bardzo wstępna wersja pluginu jest dostępna pod adresem | ====3. Zasadzki==== |
http://hyper.ia.agh.edu.pl/~miczkop/dokulatex/ | 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. |
póki co działa tylko dla B/I/U/ich kombinacji | |
ale początki zawsze są trudne ;) | |
| |
| 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 |
===== 08.04.15 ===== | 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... |
Postawione wiki znajduje się pod adresem | |
| |
http://student.agh.edu.pl/~micz/dokuwiki-2007-06-26b | |
| |
Na razie konwerter jest dostepny w panelu administratora i trzeba nazwę strony wpisać "z ręki" | |
| |
docelowo planuję wyświetlać listę stron w wiki i będzie się zaznaczać które by się chciało skonwertować. | |
| |
Konwertowanie działa na bazie wyrażeń regularnych i PHPowskiej funkcji preg_match_all. | |
| |
Z planowanych funkcjonalności na razie zrobione są i działają: | |
*bold | |
*italik | |
*podkreślenie | |
*przekreślenie | |
*code | |
*subscript/superscript | |
*poziomy menu łącznie z dołączaniem w tym miejscu label | |
*mailto | |
*konwersja linków zewnętrznych nie jest konieczna | |
*linki wewnętrzne + w tym miejscu ref | |
*footnotes | |
| |
Do zrobienia pozostały: | |
*listy numerowane i nienumerowane | |
*kod zaczynający się w wiki od dwóch spacji | |
| |
| |
| |
| |
| |
===== 08.04.29 ==== | |
*guziczki -> zrobione | |
*quoting -> zrobione | |
+ dodatkowo znaki | |
% -> /% | |
& -> /& | |
~ -> $\sim$ | |
^ -> \verb=^= | |
# -> \# | |
| |
| |
| |
| |
===== 08.05.20 ==== | |
- instalacja Plugin Managerem z adresu http://hyper.ia.agh.edu.pl/~miczkop/dokulatex.zip | |
- aby na stronie pojawił się przycisk umożliwiający konwersję, należy w pliku /lib/tpl/default/main.php | |
w okolicach linii 60. - dokładnie przed, po lub pomiędzy liniami: | |
| |
< ?php tpl_button('edit')?> | |
< ?php tpl_button('history')?> | |
| |
należy dopisać: | |
< ?php if (!plugin_isdisabled('dokulatex') && ($dokulatex =& plugin_load('helper', 'dokulatex'))) $dokulatex->html_convert_button(); ?> | |
| |
oczywiście bez spacji po < | |
| |
====== Sprawozdanie ====== | |
====== Materiały ====== | ====== Materiały ====== |
| |