# Direc­tory tex-archive/support/konwerter

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},
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

AUTHOR
Piotr Wawrzyniak wopozka@gmail.com
Have a fun and enjoy my program.


Name Notes
Ex­am­ple

## Files

Name Size Date Notes
.scon­sign.dblite 3969 2007-01-03 16:08
COPYING 17983 2007-01-03 16:08
Changelog 1629 2007-01-03 16:08
Make­file 1135 2007-01-03 16:08
TODO 215 2007-01-03 16:08
ZMIANY 1633 2007-01-03 16:08
czyt_za­pis.cc 3617 2007-01-03 16:08
czyt_za­pis.h 228 2007-01-03 16:08
dl_wier­sza.h 400 2007-01-03 16:08
kon­werter.cc 21852 2009-01-04 01:03
num_na_etyk.cc 4233 2007-01-03 16:08
num_na_etyk.h 37 2007-01-03 16:08
op­er­acje.cc 37962 2007-01-03 16:08
op­er­acje.h 290 2007-01-03 16:08
op­er­acje_na_tex.cc 3878 2007-01-03 16:08
op­er­acje_na_tex.h 140 2007-01-03 16:08
prz_string.cc 2399 2007-01-03 16:08
prz_string.h 23 2007-01-03 16:08
sys­tem_za­pisu.cc 8659 2007-01-03 16:08
sys­tem_za­pisu.h 2394 2007-01-03 16:08

Down­load the con­tents of this pack­age in one zip archive (106.8k).

## kon­werter – A pro­gram for au­to­matic num­ber­ing of com­pounds in chem­i­cal pub­li­ca­tions

Kon­werter au­to­mat­i­cally num­bers com­pounds in chem­i­cal pub­li­ca­tions cre­ated by LaTeX. It is writ­ten in C++ and works both in Unix and Win­dows op­er­at­ing sys­tems. It works sim­i­lar to LaTeX \la­bel and \ref com­mands. In­stead of giv­ing num­ber to ev­ery com­pound you give them la­bels and then re­fer to the struc­ture in the text us­ing the same la­bel. The kon­werter is able to re­solve la­bels to num­bers both in the eps files and in the text.

 Pack­age De­tails kon­werter Home page http://kon­werter.ex­root.org/ Ver­sion 0.2.4 Li­cense GNU Gen­eral Public Li­cense, ver­sion 2 Main­tainer Piotr Wawrzy­niak Topics chem­istry doc­u­ment sup­port