summaryrefslogtreecommitdiff
path: root/support/konwerter/README.pl
diff options
context:
space:
mode:
Diffstat (limited to 'support/konwerter/README.pl')
-rw-r--r--support/konwerter/README.pl239
1 files changed, 239 insertions, 0 deletions
diff --git a/support/konwerter/README.pl b/support/konwerter/README.pl
new file mode 100644
index 0000000000..db541b0476
--- /dev/null
+++ b/support/konwerter/README.pl
@@ -0,0 +1,239 @@
+Konwerter-0.2.4
+
+WSTĘP
+
+ Niejednokrotnie pisząc dłuższe teksty przy wykorzystaniu doskonałego
+systemu składu tekstu, którym jest LaTeX, pojawiała się potrzeba dodania
+do tekstu rysunków, zawierających obiekty, które wymagały odwoływania się
+do nich w tekście dokumentu poprzez numerek. Wiązało się to z koniecznością
+ręcznego ich numerowania, gdyż LaTeX, nie posiada mechanizmu
+umożliwiającego zautomatyzowanie tej czynności. Taka metoda pracy
+powodowała, że każde dodanie nowego obrazka pociągało za sobą konieczność
+przenumerowywania wszystkich pozostałych. Przysparzało to autorowi
+dużo pracy, oraz było bardzo czasochłonnym zajęciem.
+
+ Program konwerter rozwiązuje ten problem. Używając go, nie numerujesz
+obiektów na obrazkach, tylko je nazywasz. Również w tekście odnosisz się
+do nich poprzez nazwę. Gdy tekst jest gotowy, uruchomienie programu
+konwerter spowoduje zamianę nazw (zwanych dalej etykietkami) na numerki,
+zarówno w plikach eps, jak i w tekście. Numery są nadawane w zależności
+od kolejności pojawiania się w plikach eps, a do dyspozycji użytkownik
+ma 5 typów numeracji:
+- cyfry arabskie
+- cyfry rzymskie małe
+- cyfry rzymskie wielkie
+- literki małe
+- literki wielkie
+
+ Wszystkie te typy numeracji, można jednocześnie używać w jednym dokumencie.
+Dodatkowo mogą się pojawić indeksy literowe na przykład: 1a, 2b, Ia itd,
+lecz nie są one ustawiane automatycznie. O tym co będzie indeksem, decyduje
+autor tekstu.
+
+ Program pracuje tylko i wyłącznie na plikach eps. Jednak nie wszystkie
+programy produkują odpowiedni plik graficzny. Zobacz listę wspieranych
+programów, aby sprawdzić które działają.
+
+WYMAGANIA DO KOMPILACJI
+
+GNU make
+g++ w wersji 3.0 i wyższej
+
+KOMPILACJA
+
+ Kompilacja wygląda identycznie jak dla wszystkich systemów uniksowych.
+Pierwszym etapem będzie edycja pliku Makefile, w którym należy ustawić
+zmienną DESTDIR na katalog, do którego chcemy zainstalować program.
+Domyślnie jest to /usr/local/bin i jeśli nic nie zmienimy, to tam
+właśnie program zostanie zainstalowany. Po edycji należy skompilować
+zainstalować program przy pomocy poniższych komend (druga komenda,
+w zależności od DESTDIR, może wymagać uprawnień superużytkownika):
+
+1. make
+2. make install
+
+DZIAŁANIE
+
+ Program czyta plik tex, w poszukiwaniu grafik eps. W razie znalezienia
+takowej, jest ona przeszukiwana w celu znalezienia etykiet. Etykiety te
+są kolejkowane, a następnie zamieniane na numerki. Drugim etapem jest zamiana
+etykiet w pliku texowym. Użytkownik jako wynik dostaje plik nazwa.tex.auto,
+który trzeba ponownie skompilować latexem. Po tej operacji dostajemy plik
+wynikowy dvi, w którym etykiety powinny być już pozamieniane na numerki,
+zarówno w plikach eps, jak i w pliku tex. Należy zauważyć, że o ile oryginalny
+plik tex, nie jest zmieniany, o tyle pliki eps tak. Można bez problemu
+przywrócić oryginalną formę plikom eps, uruchamiając konwerter z odpowiednią
+opcją na oryginalnym pliku tex.
+
+UŻYCIE PROGRAMU
+
+ Prawidłowe działanie programu wymaga pojawienia się w plikach eps odpowiednio
+zbudowanych etykiet. Mogą one zawierać dowolne litery języka angielskiego oraz
+cyfry. Niedozwolone jest użycie kropki, średnika i dwukropka gdyż są one
+wykorzystywane w innym celu. Użycie podkreślenia "_" również nie jest wskazane
+gdyż ma on specjalne znaczenie dla LaTeXa. Nie powinno również
+powodować błędów użycie polskich liter lecz nie jest to zalecane.
+Etykieta może mieć do 200 znaków.
+
+ Każda etykieta powinna się zaczynać konstrukcją sterującą, informującą
+o sposobie jej numerowania. Brak takiej konstrukcji, powoduje że etykieta
+zostaje automatycznie ponumerowana w sposób domyślny. Istnieje pięć
+konstrukcji sterujących:
+:r - małe liczby rzymskie
+:R - wielkie liczby rzymskie
+:a - liczby arabskie
+:l - małe literki
+:L - duże literki
+ Często stosowaną metodą numerowania jest dodawanie indeksów literowych do
+liczb np. 1a, 1b, 1c itd. Konwerter również w znacznym stopniu pomaga tworzyć
+takie numerki. Aby to uzyskać, wystarczy że do etykietki dodasz na końcu kropkę,
+a po kropce literę, która tam powinna się znaleźć. Niedozwolone jest
+występowanie po kropce dwóch znaków, gdyż wtedy program nie potraktuje
+tego jako indeksu literowego.
+
+PRZYGOTOWANIE PLIKÓW EPS:
+
+ W schemacie każdy obiekt podpisujemy etykietą w następujący sposób:
+
+?et{etykieta;numer}
+
+- etykieta - dowolna etykieta stworzona według opisu powyżej;
+- numer-(dowolna liczba większa od zera).
+ Ponieważ plik eps jest czytany sekwencyjnie i etykiety niekoniecznie
+będą się pojawiać w odpowiedniej kolejności, konieczne jest ich ponumerowanie
+w pliku eps. Dzięki temu zostanie zachowana odpowiednia kolejność.
+Numery nie muszą być kolejnymi liczbami. Brak numeru spowoduje błędne
+numerowanie etykiet. Numery mogą się powtarzać ale również może to spowodować
+błędy.
+Przykład użycia
+?et{benzen;1} - użyty zostanie domyślny styl numerowania
+?et{:Rbenzen;2} - użyty zostanie styl numerowania wielkimi liczbami rzymskimi
+?et{:rbenzen;3} - użyty zostanie styl numerowania małymi liczbami rzymskimi
+?et{:rbenzen.a;4} - użyty zostanie ten sam numer co dla etykiety powyższej
+ lecz, dodatkowo zostanie dodana literka a np. ia, iia itd.
+?et{heksan.a;5} - użyty zostanie domyślny styl numerowania i dodatkowo przy
+ numerku pojawi się literka a np. 2a, 2b
+
+ Ważne jest aby pamiętać, że dla programu etykiety :Rbenzen oraz :rbenzen to
+dwie różne etykiety i będą im przydzielone różne numerki, oraz że w przypadku
+pojawienia się etykiet ?et{heksan.a;1} i ?et{heksan;2} w jednym bądź wielu
+pliku eps, obie dostaną ten sam numerek, tyle że pierwsza dodatkowo indeks
+a - czyli w tym przypadku będzie to: 2a i 2.
+
+PLIKI LaTeX
+
+ Pliki tex też wymagają dopowiedniego przygotowania. Ponieważ nie wszystkie
+pliki eps zawierają etykietki oraz z powodu tego, że w LaTeX nie ma jednej
+metody załączania rysunków do tekstu, konwerter wyszukuje w kodzie tex,
+instrukcji nakazującej mu przeszukanie pliku. Aby wskazać mu plik eps
+zawierający etykietki należy użyć konstrukcji:
+%?plik{nazwa_pliku}
+
+ Jest to komentarz dla LaTeXa i nie zostanie on wyświetlony nigdzie w tekście.
+Instrukcji tej nie mogą poprzedzać żadne inne znaki, musi to być pierwszy tekst
+w nowej linijce. Po znalezieniu tego, program konwerter będzie przeszukiwał plik
+nazwa_pliku w poszukiwaniu etykiet.
+
+ Warto zaznaczyć, że polecenie %?plik{nazwa_pliku} nie musi się odnosić
+koniecznie do pliku eps. Może to być dowolny plik tekstowy, zawierający
+odpowiednio zbudowane etykietki (patrz przygotowanie etykiet). Umożliwia nam
+to pośrednie sterowanie numeracją.
+
+ Aby odwoływać się w tekście do etykiet należy stworzyć odpowiednie polecenie.
+(\newcommand). Domyślnie jest to \nrzw{etykietka}, lecz może być to zmienione,
+poprzez użycie odpowiedniej opcji wywołania programu (patrz OPCJE WYWOŁANIA
+PROGRAMU). Konstrukcja \nrzw{etykietka} może pojawić się w dowolnym miejscu
+w linijce tekstu i nie musi być pierwszą w danym wierszu. Pozwala to na
+swobodne pisanie, bez zwracania uwagi na formatowanie (w końcu to TeX powinien
+za nas to zrobić). Etykieta ma postać dokładnie taką samą jak w pliku eps, po
+odrzuceniu numerka po średniku i samego średnika. Załóżmy na przykład że w plik
+eps wygląda następująco:
+?et{benzen.a;1}
+?et{:Rtoluen;2}
+?et{:rksylen;3}
+?et{benzen.b},
+to w tekście dokumentu należy umieścić: \nrzw{benzen.a}, \nrzw{:Rtoluen},
+\nrzw{:rksylen}, \nrzw{benzen.b}. Jeśli umieścimi dodatkowo w tekście
+\nrzw{benzen}, to również zostanie to ponumerowane, pomimo że w plikach eps
+jak do tej pory się to nie pojawiło(będzie miało ten sam numerek co etykietki
+benzen.a i benzen.b, tylko bez indeksu literowego). Wynika to ze sposobu
+działania programu i według autora jest to poprawne.
+
+ Po przetworzeniu pliku o nazwie plik.tex programem konwerter otrzymamy
+nowy plik o nazwie plik.tex.auto w którym powyższe etykiety zostaną zamienione
+na np: związek \nrzw{3} reaguje z \nrzw{4} dając... Plik plik.tex.auto należy
+przetworzyć ponownie programem latex.
+
+ Program konwerter rozpoznaje polecenie LaTeXowe \input{}, dzięki czemu możliwe
+jest przetwarzanie dokumentów składających się z wielu plików.
+
+ Czasami może być niezbędne aby, od jakiegoś miejsca w tekście (na przykład
+nowy rozdział) rozpocząć numerację od nowa. Program konwerter umożliwia i to.
+W tym celu wystarczy w pliku tex umieścić jedną z poniższych instrukcji:
+%--set-r-to a
+%--set-R-to a
+%--set-a-to a
+%--set-l-to a
+%--set-L-to a
+Spowodują one ustawienie licznika dla odpowiednio liczba rzymskich małych
+i wielkich, liczb arabskich oraz liter małych i wielkich na liczbą a. "a"
+musi być liczbą, czyli dla %--set-l-to i %--set-L-to również musi się pojawić
+liczba. O ile będzie to potrzebne, zostanie dodana możliwość ustwiania liczników
+dla liter w postaci liter. Przykłady użycia
+%--set-R-to 12 - ustawienie licznika wielkich cyfr rzymskich na 12
+%--set-a-to 21 - ustawienie licznika liczb arabskich na 21
+Powyższe instrukcje muszą zaczynać się od nowej linijki.
+ Czasami podczas pisania, może pojawić się konieczność zmiany
+domyślnego stylu numeracji, dla danego rozdziału. Konwerter wspiera
+również tę opcję. W tym celu wystarczy w pliku źródłowym tex umieścić
+polecenie:
+%--set-d-to K,
+gdzie K może być: r, R, a, l, L. Warto również zaznaczyć, że opcje te
+działają tylko na nowe etykiety. Etykiety, które pojawiły się już
+wcześniej, będą miały poprzedni numer.
+
+JĘZYK I OPCJE WYWOŁANIA PROGRAMU
+ Program konwerter obsługuje obecnie dwa języki: angielski
+(domyślnie) i polski. Język ustawiany na podstawie zmiennej
+środowiskowej LANG. Jeśli jest ona ustawiona na pl_PL, program będzie
+mówił po polsku, w przeciwnym wypadku językiem komunikatów będzie
+angielski.
+ Wpisz konwerter --help, aby zobaczyć opcje wraz z krótką charakterystyką.
+
+WSPIERANE PROGRAMY
+1) ChemDraw z pakietu ChemOffice.
+2) Xfig - program do grafiki wektorowej dla linuksa.
+3) Chemtool - program do rysowania wzorów chemicznych dla linuksa.
+4) BKchem - program do rysowania wzorów chemicznych dla linuksa.
+
+PRZYKŁADOWE UŻYCIE
+
+ Program rozpoznaje z jaką nazwą został wywołany. Wywołanie nazwą konwerter
+jest równoznaczne z wywołaniem: konwerter -ltn, natomiast wywołanie etykietuj
+jest równoznaczne z: konwerter -ntl. Oto kilka przykładów użycia:
+
+konwerter -dns R plik.tex - zamień etykiety na numery w pliku plik.tex
+ i wymienionych w nim plikach eps, stosując
+ jako domyślny styl numeracji cyfry rzymskie
+ wielkie.
+
+etykietuj -ltn -dns R plik.tex - j.w.
+
+konwerter -ntl plik.tex - zamień numery na etykiety w plikach eps
+ wymienionych w pliku plik.tex
+
+etykietuj plik.tex - j.w.
+
+konwerter -is plik.tex - zamień etykiety na numerki ignorując wystąpienia
+ $--set-counter-to
+
+konwerter -if plik.tex - zamień etykietki na numerki stosując domyślny
+ styl numeracji dla wszystkich etykiet.
+
+Aby uzyskać więcej informacji odwiedź stronę domową konwertera:
+http://piti.vsv.pl/konwerter/
+
+AUTOR
+Piotr Wawrzyniak piti@piti.vsv.pl
+W razie pytań proszę kontaktować się na powyższy adres.
+Miłego użytkowania.