What is konwerter

The konwerter is the software, that automatically numbers the chemical compounds in publication. It is worth to notice that it can number anything, so can be used not only in chemistry. The only thing you need to use it, is the LaTeX and an eps file creator that produces a proper eps files (see compatibility list). It supports 5 types of numbering:

Additionally, one can use also small letter indexes for example 1a, 1b, 1c. This letter indexes can be used for every type of numbers, and konwerter doesn't check whether it has any sense. Therefore the author can do anything even something like: Aa, aa, where A and a are numbers, and small a in both are indexes.

Of course all these numbers type can be used in one document at the same time. How to achieve that functionality you can find in the next sections.

A short history of konwerter

Why have I made this program? Like people say necessity is the mother of invention. Not another it was with konwerter.

When I was writing my MSc thesis, at the almost end of my work, I had to add one more picture at the beginning of the document. Because in chemistry (yes, I'm chemist) all compounds should have own numbers, I had to renumber all formulas on all pictures. That was hard work. After that I thought, why I did it myself, such a thing should a computer do. I started to look in the Internet for proper software, but I didn't find anything. So I decided to write it myself.

The konwerter is written using c++ programming language. I realise that it is not the best choice, for such software, but I wanted to learn more about this language, and that was a good method to do that. When I will find some free time, I will rewrite it in python, that is much more suitable for such purpose, but that is a future.

Installation of konwerter

Installation under POSIX operating system

To install the konwerter under any POSIX operatin system (Linux, BSD) just download the source code, unpack it and then execute two commands: "make" and "make install". You need the c++ compiler, and the make program to do this. Please refer to you operating system documentation how to install these programs. After you will successfully install konwerter it is ready to be used.

Installation under Windows

The konwerter was projected mainly for Linux and BSD, but I realise that there are many potential user of this software who have never used Linux or BSD. Just for them I created the Windows version of konwerter. To install my program go to the Download section, download the proper rar archive, and unpack it to the C:\Windows directory. The rar archive contains two files 1) the konwerter.exe file which is the main program 2) the library cygwin1.dll, the library from the cygwin project (this library creates the abstraction layer which allows the konwerter to run under windows).

After you install the konwerter in specified directory (C:\Windows) you can run in using cmd shell (Menu->Run->cmd.exe). Just go to the directory where you store your LaTeX files (cd command), and run konwerter with the proper option. If the number of information which konwerter prints on the screen is to much to analyse, you can redirect output to the file using ">" sign:.

konwerter file.tex > output.txt

How does it work

The konwerter works similar to the \label, and \ref LaTeX methods. Therefore instead of giving number to every compound, you give them labels. The same labels you use in the TeX file. After your publication is ready you run konwerter on the main LaTeX file, and get a file, where all labels are changed to numbers, both in the eps and latex files.

Preparation of eps file

There exist a special method to insert labels into eps file which is at present ?et{labelname}. So instead of writing 5, you should write ?et{labelname}. After compilation with konwerter the number will appear at the question mark position. One can ask why in so complicated way? The answer is because of historical meaning. In the first version of konwerter, I implemented this method, and at present I didn't want to change it. In the next version the possibility of customization is planned but at present only ?et{label} works.

The label

The label should be prepared in special way and should contain numbers and letters belonging only to the English alphabet. The dot, comma, colon and semicolon are generally not allowed, because have same meaning for konwerter. Underline "_" should not be used as well, because it will cause problems during compilation with LaTeX. At the beginning of label there should appear an instruction (a switch) which informs konwerter which numbering style should be used. There are 5 switches:

  1. :r - for small Roman numbers
  2. :R - for capital Roman numbers
  3. :a - for Arabic numbers
  4. :l - for small letters
  5. :L - for capital letters

If such instruction is not there, then default numbering style is used. Because in one eps file you can place many compounds (many different labels) and the konwerter reads the eps file line by line, it doesn't really know what is the order of labels in the file. Therefore it is necessary to inform it about the labels order. We do this by adding a semicolon at the end of label followed by a number. The konwerter reads labels in eps file, put them to the queue, and then puts them in the proper order using numbers. So if there appear such two labels:

the konwerter simply knows, that label benzene, should have lower number than label toluene. It is not necessary, to use succeeding numbers, you can use every second, third, forth etc. It is even advisable to do that in this way, because in case of adding a new structure to the picture, it will not be necessary to change all others labels.

In case that one would like to add letter indexes to the number, the dot is used. The letters indexes are not given automatically, the konwerter just copies them from the label. So if you create label like: benzene.a, benzene.b, benzene.c konwerter will replace label with proper number and then copy the letter. Finally one will get 1a, 1b, 1c. In the latex file you should refer to labels like benzene.a, benzene.b, benzene.c.

Examples of labels in eps file

  1. ?et{benzene;1} - will be replaced with number, using default numbering style
  2. ?et{:Rbenzene;1} - will be replaced with number, using capital Roman numbers
  3. ?et{:abenzene;1} - the same like above, but Arabic numbers will be used
  4. ?et{:abenzene.a;2} - there will appear Arabic number with an "a" index for example 1a
  5. ?et{benzene.b;2} - default numbering style will be used, and additionally "b" index given

LaTeX file

Informing konwerter about eps files in which there are labels

Because in LaTeX exists many methods for graphics including you have to inform konwerter about eps files in which contains labels. To do that you should place below command:
That is a comment in the LaTeX file and does nothing. When konwerter finds such a line in LaTeX file, it knows that file_name.eps should be searched for labels.

Konwerter understands also LaTeX \input command, so you can have multi file source.

Calling labels in LaTeX file

To call the labels in LaTeX file, one should make special command (look into your LaTeX documentation to find out how to do it). Default is \nrzw{}, but it can be changed (see, command line arguments). Konwerter doesn't really care what \nrzw command does. It only looks for it in the text. That allows you to insert numbers into the final document using any formating style. I use the \nrzw command can be created in the following way:


The labels in LaTeX file should be the same like in eps files, but without the semicolon and the number at the end. For example when in the eps file you put ?et{benzene;1}, ?et{:Rbenzene;2} and ?et{:abenzene.a;3} labels, in the LaTeX file you call them like: \nrzw{benzene}, \nrzw{:Rbenzene}, \nrzw{:abenzene.a}. All these labels are different for konwerter and all will receive different numbers.

Setting the counters from LaTeX file

If you write big publication, sometimes it is necessary, to change numeration for a new chapter etc. Konwerter supports also such thing. To achieve that it is enough to place in LaTeX file one of below instructions:

If one of the above instruction will be found in LaTeX file, in all new labels above settings will be used. It does not affect old labels.

Compiling with konwerter

When your publication is ready it is time to compile the tex file using konwerter program. Just type:
konwerter file.tex
After that you will be given file file.tex.auto.tex, in which all labels are already replaced with numbers, both in LaTeX file and eps files. You should compile this file using latex command.

Command line arguments

-ltn, --labels-to-numbers - change labels to numbers [-n]

-ntl, --numbers-to-labels - change numbers to labels (only in eps files)

-srf n, --start-roman-from n - start number with small roman numbers from n [-srf 1]

-sRf n, --start-Roman-from n - start number with capital roman numbers from n [-sRf 1]

-saf n, --start-arabic-from n - start number with Arabic numbers from n [-saf 1]

-slf n, --start-letter-from n - start number with small letters from n [-slf 1]

-sLf n, --start-Letter-from n - start number with capital letters from n [-sLf 1]

-dns n, --default-numbering-style n - set default number style. Possible values: r, R, a, l, L [-dns a]

-ln, --label-name - LaTeX command for numbers inserting [\nrzw]. There must be always 2 backslashes e.g. -ln \\xyz

-l, --language - set language. There are 2 possible parameters: [pl] and en. Unknown parameter is handle as en

-is, --ignore-switches - ignore switches %--set-X-to

-if, --ignore-formating - use for all labels default number style

-v, --verbose - be verbose

-t, --test - run konwerter but without changing the files. This option is used to check if there exist unresolved labels.

-h, --help - short help

--version - print version number and exit

Type konwerter -h, to see all command line parameters with short description.

Compatibility list

Here you can find information which programs produces eps files, that my konwerter understands. In case you will find any new, please send me an information.