diff options
Diffstat (limited to 'support/konwerter/README.pl')
-rw-r--r-- | support/konwerter/README.pl | 239 |
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. |