Konwerter-0.2.4

INTRODUCTION

Quite often during writing longer texts using a wonderful high-quality typesetting
program called LaTeX, there appears necessity to include pictures
containing objects which should be numbered and additionally, should be called (reffered) in
the text using these numbers. Such a situation is typical for chemical
publications, which contain many chemical schemes with many compounds
in every of them. Up to now, the author of the publication had to number
every object (formula) manually which was both time consuming and unpleasant
work. Consider, what would happened if at the end of writing it is
necessary to add a new compound just at the beginning of a document. If you are
lucky you can add any letter index at the number, but in the worst case you 
have to renumber all the schemes.

The konwerter program solves this problem. Using it one doesn't 
number any object in graphics anymore, but gives them names
called labels. These labels are used instead of numbers, both in a text 
and in figures. When the text is ready, the start-up of the konwerter program
on the main tex file will just replace all labels with proper numbers both in 
the graphics and in the text. The numbers order depends on the order of labels in 
the graphic files. The label which appeared earlier will have lower number. User has a
possibility to use five types of numbering:
- Arabic numbers
- small Roman numbers
- capital Roman numbers
- small letters
- capital letters

All these types of numbers can be used at the same time in a
document. Additionally there can appeared letter indexes (e.g.
1a, 2b, 3a etc) but they are not set automatically. This is author 
who decides how the index looks like by creating the label in a
special way.

The converter program supports only graphics in eps format. See
the compatibility list.

WHAT IS NECESSARY FOR COMPILATION

GNU make
g++ in version 3.0 or higher

COMPILATION

Compilation doesn't differ from a typical compilation for the unix
systems. The first step is the edition of Makefile, in which one must
set the DESTDIR variable. This variable shows where will the program
be installed. By default it is /usr/local/bin and that is the place
the program will be installed. After edition, the program should be 
compiled and installed using below commands (the second one, may 
require the superuser privileges):

1. make
2. make install

HOW DOES IT WORK

The konwerter program reads the tex file and searches there for graphics in
the eps format. When any is found the next step is to look for any labels
in the eps file. The labels are queued in a special quie and then changed to numbers. 
The second step of working is to replace all labels in a tex file. As a result
of work a new file name.tex.auto.tex will be produced, which should be
compiled with LaTeX once again. After that the dvi file is formed
in which all labels are already replaced with numbers both in the text and
graphics. It is necessary to know that during label changing process
the eps files are also changed (the tex file stays unchanged). One can
restore the original eps files by running the konwerter with the proper
option on the original tex file. 

*********************************************************************
IT IS STRONGLY RECOMMENDED TO DO A BACKUP COPY OF ALL FILES BEFORE THE
USAGE OF THE KONWERTER PROGRAM.
*********************************************************************

PROGRAM USAGE

The konwerter program needs a special constructed labels in eps
files. The labels can contain any letters from the English 
alphabet and the numbers. The underline "_" is not allowed because 
it is special character for LaTeX. The dot, semicolon and colon are 
also not allowed because they have some special meaning for konwerter. 
The label can have up to 200 letters.

Each label may start from a construction which controls a way
of numbering. The lack of this construction will result in default numbering
style. There exist five controlling constructions.
:r - small Roman numbers
:R - big Roman numbers
:a - Arabic numbers
:l - small letters
:L - big letters

Quite often chemists use letter indexes with numbers for example:
1a, 1b, 1c etc. The konwerter program also helps the author to make
above numbers. To get such a result it is enough to add the dot
at the end of label and then a letter. It is not allowed to put two 
letters after the dot because the program will not
recognize it as an index.

THE EPS FILES PREPARING

In the eps file every object to be numbered should be
labeled in the following way:

?et{label_name;number}

- label_name - any label prepared in the way described above
- number - any number higher than zero. The existence of this
parameter needs small explanation. The eps files are red
by konwerter line by line. Because of that the labels can appeared not in
a proper order. To prevent such a situation each label in the eps should 
conain this number. When the konwerter program finds two labels 
?et{label1;1} and ?et{label2;2} it will just know, that label1 should have 
lower number that label2. The author of the eps file knows the order, the program 
doesn't - therefore it needs these parameters. If you forget to add the number, 
it will be set to 0 automatically. Please avoid putting two the same numbers 
in one figure (they can be the same in different figures) because it will 
results in errors during numbering. A few example of the proper labels are presented below: 
?et{benzene;1} - the default numbering style will be used
?et{:Rbenzene;2} -the big Roman numbering style will be used
?et{:rbenzene;3} - the small Roman numbering style will be used
?et{:rbenzene.a;4} - the same number as above will be used, but
		    additionally the index 'a' will be given 
		    for example: iva.
?et{hexane.a;5} - the default numbering style will be used, and
                 additionally the index 'a' will be used, for example: 2a
                 or 4a.

It is important to remember that the labels: :Rbenzene and :benzene
are totally different and they will receive different
number. Additionally, in case of such 2 labels: ?et{hexane.a;1} and
?et{hexane;2} both labels will receive the same number, but the first one will 
recive the 'a' index. In this case it will be as follows: 2a and 2.

THE LaTeX FILES

The tex files also need a proper handling. Because not all the eps files
contain labels and because in LaTeX doesn't exist one general method
for pictures including, the konwerter program searches in the tex
code for the instruction which tells  in which file the labels
should be searched for. To inform the konwerter where are labels below 
construction should be used:

%?plik{filename}

As one can see this is a comment in LaTeX file. The construction
should always start from a new line. After konwerter finds such a line it
will search for the labels in file called filename.

It is worth to notice that the file named 'filename' doesn't need to be a
real eps file. It can be any text file containing the labels prepared
as above written. 

To call the label in the tex file, the special command should be
created (the \newcommand command). By default it is \nrzw{label}, but this can
be changed using the command line parameter. The \nrzw{label}
construction doesn't need to start from the beginning of the line, it
can be placed at any position. It allows us to write without thinking
where the line should be broken (that is finally TeX business). The label
should be the same as in eps file after semicolon and the number
removing. Let us consider below example. 

If in the eps file below labels are present:

?et{benzene.a;1}
?et{:Rtoluene;2}
?et{:rxylene;3}
?et{benzene.b}

in the tex file we should place:  \nrzw{benzene.a},
\nrzw{:Rtoluene},\nrzw{:rxylene}, \nrzw{benzene.b}. If additionally in
the tex file we placed \nrzw{benzene} it also will be given a number
- the same as for the 'benzene.b'. That is the result of program
project, and according to the author, that is correct.

After processing is done a new file filename.tex.auto.tex is 
produced, in which all the above labels will be changed to numbers.
The filename.tex.auto.tex should be once again compiled with LaTeX to get dvi file.

The konwerter program changes also labels to numbers in eps
file. To restore the original eps files  run the konwerter with
the -ntl option, or using name etykietuj on the main tex file.

 The konwerter program recognizes the LaTeX \input{} command which
allows us to process documents that contained many files.

It is sometimes necessary to start numbering from the beginning
for some part of the text (for example in the new
chapter). The konwerter program supports such a situation. To get such
result it is enough to include in tex file one of the below
instruction:

%--set-r-to a
%--set-R-to a
%--set-a-to a
%--set-l-to a
%--set-L-to a

These commands results in setting the counter for small Roman number,
capital Roman numbers, Arabic numbers, small letters and capital
letters to the number a. The a, should be a number for each of
the numbering style. These command should start from the new line.
Examples:
%--set-R-to 12 - setting the counter for capital Roman numbers to 12
%--set-a-to 21 - setting the counter for Arabic numbers to 21

It could be sometimes useful to use another numbering style in a new chapter.
The konwerter program supports also this feature. It is enough to place in the
tex file below command:
%--set-d-to K, 
where K could be: r, R, a, l, L. Beginning from this line, the default numbering
style for new labels will be set to K. 

It is worth to notice that the new settings, given by above commands, will
concern only new labels. The old ones will have the same numbers.

THE LANGUAGE AND THE COMMAND LINE PARAMETERS

The konwerter program supports at present two languages: English (default) and
Polish. It also recognizes the LANG environment variable. If it is set to pl_PL,
the konwerter will speak in polish, otherwise English will be used as default.
Type konwerter -l en -h to see the possible parameters with short characteristic.

COMPATIBILITY LIST
The konwerter is known to work with eps files produced by:
1) ChemDraw from ChemOffice package
2) Xfig - vector drawing program for linux
3) chemtool - chemical drawing software for linux
4) BKchem - chemical drawing software for linux.

EXAMPLES

The program konwerter recognizes the name using which it was run.
The konwerter name is equal to the  -ltn parameter, and the etykietuj
name is equal to the -ntl parameter. 

konwerter -dns R  plik.tex - change labels to numbers in plik.tex file
			     using capital Roman numbers as default numbering
			     style.
			     
etykietuj -ltn plik.tex    - the same as above

konwerter -ntl plik.tex    - change numbers to labels in eps files mentioned
			     in the plik.tex file

etykietuj plik.tex -         the same as above

konwerter -is plik.tex    - change labels to numbers in plik.tex file
 			     ignoring $--set-counter-to switch

konwerter -if plik.tex	   - change labels to numbers using default
			     numbering style for all labels. This
                             command ignores :r, :R, :a, :l, :L
			     switches

For more information visit konwerter webpage: http://konwerter.exroot.org
			     
AUTHOR
Piotr Wawrzyniak wopozka@gmail.com
In case of any questions please contact using above address.
Have a fun and enjoy my program.