summaryrefslogtreecommitdiff
path: root/support/konwerter/README.pl
blob: db541b0476b3692b1cb72f0e7a11e923310a6b18 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
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.