Initial commit

1 files changed, 263 insertions, 0 deletions

diff --git a/support/konwerter/README b/support/konwerter/README
new file mode 100644
index 0000000000..5b13e4645b
--- /dev/null
+++ b/support/konwerter/README
@@ -0,0 +1,263 @@
+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.