/******************************************************************************
 * program:     wp2latex                                                      *
 * function:    convert WordPerfect 5.0 or 5.1 files into LaTeX               *
 * modul:       readme                                                        *
 ******************************************************************************/

Attention:
----------
There is another version of Wp2LaTeX written from scratch
by the original author R. C. Houtepen at TUE-Eindhoven. This version
differs completely from the pakage in your hand. Please check it on
your nearest CTAN host at
    tex-archive/support/wp2latex/*    .
The version there has the disadvantage, that there isn't any source code
available. The source code in the subdirectories is very old. I tried
hardly to contact the author but failed. So I took the latest available
sources (which based on these in the subdirectories mentioned above)
and corrected some errors. I never checked the other version. I apologize
everybody to compare both versions and tell me the conclusion.

The program:
------------
Wp2LaTeX was originally designed to translate WordPerfect 5.0 documents
into LaTeX 2.09. Later some code was added to translate also WordPerfect 5.1
documents. Now the preambel is designed for LaTeX 2e (by changing the
preambel by hand it runs also under LaTeX 2.09 of course).

This version was compiled with EMX 0.9b (gcc 2.7.1) to run under both
DOS and OS/2 on 386 or higher.

Some general remarks:
---------------------
1. Don't expect a better looking result only caused by converting text
   from WordPerfect to LaTeX. You HAVE TO edit the resulting LaTeX files.
   The reason is, that wordprocessors didn't give the structur
   of the text (sections, itemizations, labels, ...) but only
   the formatting (boldface, underline (uurgh), italic, ...).

2. Tables are not converted. Only the text in tables is inserted
   line by line.
   Hint for tables: Call WordPerfect. Mark table as block. Save the
   block as DOS file. Now manual editing is easier.

3. In this version formulas are translated.
   The code for translating formulas was done by Dirk Lellinger (see below):
   I detected that there are problems when translating anything
   containig "over". So: CHECK ALL FORMULAS CAREFULLY!

4. Don't expect any miracles from this program.


In which case is Wp2LaTeX really useful?
----------------------------------------

   I have translated a huge WP file (about 1MB text) with a lot of
   footnotes but no tables and formulas.
   To get a nice LaTeX format I wrote about 5 C-programs and about
   40 sed-lines to convert some ugly formattings.
   After this I spend some time with manual editing.
   At last I wrote a LaTeX-style for a nice looking document.
   The whole procedure took me three days.


How to handle bugs?
-------------------

1. Correct the bug, send it to CTAN and send the latest author a remark
   about your bugfix.
   If the bug is only a "unknown character" (special WordPerfect character)
   look at the ent of the file wp2linit.c. It is very simple to add
   further special charcters.
2. If you are not able to correct the bug ask the latest author, whether
   he can do anything for you.
3. Remember that the reason of all the bugs is, that anybody wrote a
   text in WordPerfect. So the mistake was to use WordPerfect not
   to use Wp2LaTeX. Bugfix: Delete all WordPerfect stuff and enforce
   all people to use LaTeX.


Compiling the source
--------------------
There is a makefile for use with dmake 3.8 and EMX 0.9b (gcc 2.7.1) to run
under both DOS and OS/2 on 386 or higher.
There are no special dmake statements and I think, every make could handle
it.
The C source contains some #pragma-statements for Borland-C compiler.
I think it should also be possible to compile the source with Borland-C
(I beleave, the #pragma statements in wp2latex.c are necessary in all
files if needed at all. The changes according to the string sizes could
make them unneccessary.)
Perhaps there are memory problems caused by allocating space for reading
one whole paragraph of the strip file. If this is the case decrease
MaxParLength in wp2latex.h. In former releases it was 256 but it is NOT
enought. A more save choice may be 4096.
Also the code was compiled in former versions using gcc v. 2.6.3 in a
SunOS environment. I tried to ensure, that it wouldn't fail in this case.
Try the makefile or type
   gcc -o wp2latex *.c
When compiling in Linux environment you have to link the math libraries
as well (uncomment the appropriate line in the makefile) or try
   gcc -o wp2latex -lm *.c

I splitted the source, which originally was only one file, to make it
easier to correct bugs. I hope that it was a good decison.


Authorship history:
-------------------

  wp2latex was written in Turbo Pascal by R. C. Houtepen at TUE-Eindhoven.
  It was converted into C using p2c, and modified, by Glenn Geers (Sydney U).
  It was further modified by Michael Covington (U of Georgia).
  Modified to be used in unix/linux environment by Claudio Porfiri.
  The parsing of formulas was added by Dirk Lellinger (U Halle/Germany).
  The splitting of code into several files and the documentation
  was done by Andreas Tille.


Remarks of the authors:
-----------------------

Michael Covington:
  MC  KNOWN BUGS:
        Needs to put \hfill before \\ when in justified mode,
          so user doesn't get "underfull hbox" messages.

   Modifications by
   Michael A. Covington 1992, 1993, mostly marked "MC".
   This is Borland C, but should be fairly portable.

Claudio Porfiri:
  Notes on the Unix version:
    the code was compiled using gcc v. 2.6.3 in a SunOS environment
    without any problem, simply type "gcc wp2latex.c -o wp2latex", when
    compiling in Linux environment you have to link the math libraries
    as well, so give the command "gcc wp2latex.c -lm -o wp2latex"
    instead.

   1995-12-13  patch 2.3.1      Claudio Porfiri <porfiri@nism.tei.ericsson.se>
                                Since the SEEK_SET etc. constants are not
				defined into stdio.h but in unistd.h, and since
				I want the code to be portable, I added the
				defines into the source code.

Dirk Lellinger:
   Equation-parsing for WordPerfect 5.1
   (C) by Dirk Lellinger (Germany), May 1994,
   currently available under: dirk@sunny.dki.th-darmstadt.de

   known bugs and incompabilities
   ******************************

   HORZ n, VERT n, SCALESYM n c    are not implemented.

   WordPerfect allows "lazy" bracketing, for instance
   1 over 2 over 3 is interpreted in WordPerfect as {1 over 2} over 3
   this is not allowed in WP2LATEX and results in a bad translation

   the title of WP-equations is not translated

   currently only the charset 6 is supported for special characters
   all other chars are implemented by
   their full names, for instance alpha, bigsqcap  ...


   differences to WordPerfect and implementation details
   *****************************************************

   the author commonly writes equation arrays in WordPerfect using
   stackalign{...&...#...&...}
   therefore I interpreted this structure, which must be at the very beginning
   of the formula, as equation array.
   I decided not to use the eqnarray-environment in LATEX, because I entered
   problems with the numbering of formulas
   I rather use \displaystyle in connection with the array environment
   to get the right style of the formulas

   I have to make a decision wheter a formula is displayed using
   begin{equation} or using $ (text style).
   This is realized as follows
   if there are chars before the formula in the current line or
   the previous line is ended by a soft return and the WP-option
   "formula is treated as char" (this translation may be wrong)
   is on, then the text style mode is used, in the other cases the
   equation-environment is used.

   Note: Lazy bracketing causes error messages. Check the formula
         with the number given in the message carefully!


Andreas Tille <e2od5@mlucom.urz.uni-halle.de>:
  1) some rudiments of p2c substituted (Static -> static, Local -> static,
     Void -> void, Char -> char)
  2) simplification of the mechanism to add further special WP-charcters
     (#define WP_CHAR ...)
  3) some special WP-charcters added (Marked with AT)
  4) included unistd.h if not __BORLANDC__
  5) LaTeX2e - preambel: \documentclass{...} \usepackage{...}
  6) auxillary files (*.str and *.tbl) are really deleted (fclose() is
     necessary before unlink())
  7) If a '-' in the WP-text occured at the end of a line (the character
     in this case is represented as 0xaa instead of 0xa9) Wp2LaTeX leaved
     it out. Now 0xa9 and 0xaa both are handled correct.
  8) Some code-optimizations
     a) file opening
     b) Rd_word, Wr_word substituted for EMX (runs on all machines with
        Intel-byte order
     c) substitute some Pascal-fashioned string[256] stuff by allocating
        the really needed memory (sometimes more than 256!!!)
     d) substitute some constant strings, which only store other
        constant strings, to pointers, which point to constant
        strings (open_com, close_com, LOC_Convert_first_pass.lat,
        LOC_Convert_first_pass.ext_lat)
     e) substitute Jump_in_file by fseek(..., SEEK_CUR)
     f) reading of the split-file in second pass changed
  9) Split the code into several files to have a better overview when
     looking for bugs.
 10) Substitute some (only some, because I'm lazy ;-() functions from
        a(i, s)
        int i;
        char *s;
        {
        }
     to
        a(int i, char *s)
        {
        }
     style. Give the compiler a chance to detect wrong arguments!
 11) Prevent the formula parser from crashing with SIGSEGV
     (Note: These chrashes were caused by an internal error
     in formpars.c. I didn't correct the error but only check
     whether it occured and don't do anything which could cause
     a SIGSEGV. The resulting LaTeX file is the same in any case.
     Dirk Lellinger told me, that lazy bracketing causes the error.)
 12) Wrote this documentation.
 13) Warning if the file to convert seems to be a WordPerfect 6.0 document

 If somebody needs any sed scripts or little C-programs to do
 some further modifications automatically ask me. If there are a lot
 of users who need conversions like \"{a} -> „, "..." -> "`..."' and
 other stuff I will include some little utilities into the Wp2LaTeX
 package.

TODO LIST:
----------
  - Improve the translation quality
  - Add various makefiles to allow an easier compilation under various
    environment, like VMS, Win and so on.
  - Write a log-file of the ignored sequences
  - Add command-line options
     . use german.sty (\"{a} -> "a, ...)
     . use EmTeX (\"{a} -> „, ...)
     . include further packages (\usepackage{t1enc,...})
     . leave out optional arguments of \footnote
  - Optional LaTeX filename given in commandline (I hate so much questions
    while running a program).
  - Complete part 10) from Andreas Tilles changes
  - Handling of tables could be done so far, that columns are
    separated by '&' and lines separated by "\\\n". This would
    simplify manual editing
  - Correct errors within formula parser
    . "over" are not translated correctly
    . See the error messages while running
  - Handling of WordPerfect 6.0 documents.
  - Prevent anybody from using WordPerfect to decrease the probability
    of failures of this program ;-).

