********************************************************************************
*			reLyX -- a LaTeX to LyX translator                     *
********************************************************************************

The purpose of reLyX is to translate *well-behaved* LaTeX into LyX. If your
LaTeX file doesn't compile, don't even dream of trying reLyX on it. Even if it
does compile, if you do weird things, like redefining commands, it may choke.

reLyX is in its earliest stages. Therefore it's messy, buggy, and in many ways
imperfect. Currently, though, its main goals are:
    1) Get through a well-behaved LaTeX2e file without crashing
    2) Translate a lot of that file.
    3) Localize the parts that can't be translated and copy them in TeX mode
It seems to achieve these main goals pretty well on most files.

There are many many improvements that can and WILL be made to reLyX in the
near future. However, we wanted to get reLyX out there early on, because
LaTeXers are often unwilling to use LyX if they can't read old TeX files into
it. LyX 0.14 (1.0?) will read in (almost) regular old LaTeX, so reLyX is
intended as an interim measure.

reLyX uses the Perl TeX parser Text::TeX package written by Ilya Zakharevich
(ilya@math.ohio-state.edu), available on CPAN.

********************************************************************************

USAGE

In a nutshell:
    reLyX.pl [-f] file.tex

Here's a more lengthy description of the translation process:

1. If you don't have Perl, go get it at www.perl.com/perl.
    You ought to have it anyway.  You'll need Perl version 5, since lots of
object-oriented stuff is used. I'm not an expert on perl versions, but it seems
like 5.001 is too old and 5.002 works.  5.003 definitely works.

2. Run reLyX.pl. You should be able to say simply 'reLyX.pl foo.tex'.
    reLyX will create a LyX file 'dir/foo.lyx' from a LaTeX file 'dir/foo.tex'
--- or .ltx or .latex --- as well as some temporary files along the way.
    NOTE that reLyX must be run from its own directory. You can't say something
like 'foo/bar/reLyX.pl a.tex' (yet). You either need to copy the TeX file to
the reLyX directory, or use 'reLyX.pl /foo/bar/a.tex'. The LyX file (and the
temporary files) generated by reLyX will be created in the same directory that
the TeX file resides in. I.e., in the latter case, /foo/bar/a.lyx would be
created.
    In order to avoid accidental clobbering, reLyX will not run if the .lyx file
already exists. This could happen if you exported a LyX file as TeX, then (you
or someone else) edited it, and then you wanted to translate it back to LyX.
Use 'reLyX.pl -f foo.tex' to clobber the existing .lyx file
    reLyX.pl will spew out lots of garbage to stdout, so you should NOT redirect
the output to foo.lyx.  If you don't want all that garbage on your screen,
redirect the output to a dummy file (or /dev/null). In that case, all you'll
get on your screen are a few lines telling you about reLyX' progress, as well
as any warnings or errors from Perl. To reiterate:
    'reLyX.pl foo.tex > foo.lyx' is BAD (cf. "Ghostbusters"),
    'reLyX-pl foo.tex > bar' is GOOD.

3. Run LyX v0.12 on the resulting .lyx file.
   In theory, most of the file will have been translated, and anything that's
untranslatable will be highlighted in red (TeX mode or LaTeX layout).  In
theory, LyX will be able to read the file, and to create printed documents
from it, because anything in TeX mode will be passed directly to LyX (so
that, if you had well-behaved LaTeX, it will still compile). If reLyX crashes,
or LyX cannot read the generated LyX file, see the next item, or BUGS below.

4. Use "skip" blocks.
    Theory does not always coincide with reality. There's a lot that reLyX
can't do, so it may get confused. If reLyX is choking on something, or LyX
can't read it after reLyX translates it, the best thing to do is to put
"\begin{reLyXskip}" before the offending text, and "\end{reLyXskip}" after
it. I call this a "skip" block. When reLyX finds such an environment, it
copies it verbatim from the TeX file until the end of the environment. reLyX
should then just copy everything in LaTeX layout; then once you open the file
in LyX you can delete the \begin{reLyXskip} and \end{reLyXskip} commands
(which would otherwise confuse LaTeX when you try to print the document).

Note: In fact, you currently don't need to use the "reLyXskip" environment.
You can put any unknown word in there. However, in future versions, you may be
required to use that specific name to force reLyX to avoid translation. It's
probably safer to use something which is obviously reLyX-specific, anyway.

5. Change things that are highlighted in red (LaTeX layout or TeX mode) by hand.
    As mentioned above, you should be able to print out the LyX file, but
changing a '\begin{tabular} ... \end{tabular}' in LaTeX layout to a regular
LyX table will allow you to take advantage of LyX' WYSIWYM editing.
    As reLyX gets smarter, hopefully the amount of by-hand editing will shrink.
However, in most LaTeX files, most of the information will be regular text or
Math, which reLyX should handle just fine.
    Unfortunately, newlines may be lost in untranslated TeX (see BUGS)

6. PROOFREAD THE DOCUMENT!! I'm sure you were planning on doing this anyway,
but it's particularly important after translating reLyX. reLyX is, at least
now, better at "macro-translating" (translating the whole document) than
"micro-translating" (translating every little detail). For example, you may
see extra spaces or deleted spaces. Of course, we'll make every effort to
get rid of these inaccuracies as time goes on...

********************************************************************************

WHAT RELYX CAN HANDLE
reLyX knows about many basic latex commands. It will translate:
 - text including mini-commands like ~, '', \@, \TeX
 - title commands like \author, \date, \abstract, \title
 - heading commands like \section including starred commands (\section*)
 - quote, quotation, verse, itemize, enumerate, description environments
 - \item commands in the above list environments (but see BUGS)
 - well-behaved nested environments (complicated nesting may break things)
 - cross-referencing commands like \ref, \pageref, \label
 - \footnote and \margin
 - font-changing commands including \em, \emph and corresponding commands to
      change family, size, series, and shape.

Some of this support may not be 100% yet. See below for details

    reLyX copies math (almost) verbatim from your TeX file. Luckily, LyX reads 
in TeX math, so any math which is supported by LyX should work just fine.

    reLyX will also copy any preamble commands you have (anything before
"\begin{document}") verbatim, so fancy stuff you've got in your preamble
should be conserved in dvi and printed documents, although it will not of
course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.


WHAT RELYX CAN'T HANDLE --- But it's OK
 - included figures and tables
 - included documents
 - minipages
 - spacing commands (\vspace, \pagebreak)
 - bibliography stuff
 - unknown environments and commands (e.g., style-specific ones)

    reLyX copies unknown commands, along with their arguments, verbatim into the
.lyx file. Also, if it sees a "\begin{foo}" where it doesn't recognize the
"foo" environment, it will copy verbatim until it sees "\end foo". Hopefully,
then, most of these unknown commands won't cause reLyX to break; they'll
merely require you to do some editing once you've loaded the file up in LyX.
That should be less painful than editing either the .tex or the .lyx
file using a text editor.

    By the way, if you've got a huge unknown environment with lots of stuff
in it that you *do* want translated, you might want to comment out the \begin
and \end commands, and let reLyX translate everything within the environment.
Then you can either select the right layout (if LyX knows it: e.g., AMS'
"Proof" layout) or put the \begin and \end commands back in, in TeX mode.

    It IS safe to ignore messages saying that a given variable is used only
once; they're just due to using Perl's debugging switch. There may also be 
non-fatal complaints of "Use of uninitialized value at Text/TeX.pm line ...". If
they're not fatal, you can probably ignore them. They are to be due to bugs
in TeX.pm which will be fixed soon.


WHAT RELYX HANDLES BADLY --- AKA BUGS
    Since reLyX is at best in alpha-release, it's got a number of problems.
The basic way to get rid of any big problems in the main document is to surround
offending text with a "skip" block as explained above in USAGE.

 - "Verbatim" copying of unknown environments isn't quite verbatim.
   Specifically, newlines and comments may be lost. This will yield ugly LyX,
   but in a large percentage of cases the output will be the same. It means,
   though, that even "skip" blocks won't allow a perfect LaTeX->LyX
   translation. This bug is first on the list of bugs to fix.
 - reLyX puts braces around unbraced arguments to ^ and _ in math mode.
   However, it will only work on simple arguments. x^\frac{1}{2} will confuse
   it. Shame on you for writing that. Fix it by adding the implicit braces.
 - If you've got an unknown environment which is nested (e.g.,
   "\begin{trivlist}...\begin{trivlist}...\end{trivlist}...\end{trivlist}")
   reLyX will stop copying at the first \end command. Fix this bug by
   surrounding the whole block with a "skip" block.
 - \item commands for description environments don't quite work. You need to
   change (within LyX) "[argument to item]" to "argument_to_item ", where the
   underscores represent protected spaces between words.
 - \verb, etc. will almost definitely not work, since reLyX won't recognize the
   delimiters unless they're braces. Surround with a skip block
 - as mentioned above, complicated nesting could confuse matters. Simple
   nesting, including nesting "Standard" paragraphs within lists, should work.
 - \normalfont is not supported and may confuse the font stacks
 - reLyX won't necessarily translate document options very well. You may need
   to fiddle with the Layout->Document menu a bit if you've got strange
   options.
 - font sizing commands *should* work. reLyX may complain about "font
   confusion" when several font sizing commands are given in close
   proximity. Even if it complains, it may get the sizes right.

    reLyX is hopefully rather robust. As mentioned above, it may not translate
your file perfectly, but it shouldn't crash. If it *does* crash, please run
reLyX *without* redirecting stdout. That will allow you to figure out where in
the reLyXing process it crashed. That will allow you to write a better bug
report, which will allow us to fix it more quickly and easily. (If you are
running reLyX on a huge file, it may not be worth sending all of the output in
your bug report, but you can include the last ten or twenty lines of output,
along with the piece of the TeX file it crashed on.)


RUNNING RELYX ON LYX-GENERATED FILES
You may want to run reLyX on a .tex document that was created by LyX. If so:

LyX actually adds some commands to the preamble when creating TeX files.
Look in the preamble for the sections headed by
"%%% LyX specific LaTeX commands" and
"%%% Textclass specific LaTeX commands"
(but NOT "%%% User specified LaTeX commands")
Using a text-editor, you should REMOVE the parts of the preamble that LyX
created. Otherwise, when you run LyX again, the preamble will have two
copies of the preamble commands, which will lead to LaTeXing errors.
    Consider this a feature that is lacking, rather than a bug. Either way, it
will probably be fixed soon.


THE FUTURE OF RELYX

In the future, many of the unsupported commands and environments will be
supported by reLyX. Bugs will be eradicated.  This will involve changes to
reLyX and CleanTeX, as well as (probably small) changes to the TeX.pm package.
Hopefully, these changes will be made quickly, so that reLyX.pl is useful
before LyX 0.14 makes it obsolete.

********************************************************************************

IMPLEMENTATION DETAILS:
reLyX makes several "passes" in order to translate a TeX file. On each pass,
it creates one or two files.

1) Split preamble (anything before a \begin{document} command) off the rest
   of the file. It saves the two pieces in separate files. This is necessary
   because there may be very strange stuff in a preamble
2) Translate the preamble
3) "Clean" the TeX file, generating slightly stricter LaTeX: e.g., put
   braces around the arguments to ^ and _, even if they are one character
4) Translate basic LaTeX text, commands, and environments to LyX
5) Translate class-specific commands and environments to LyX 
    - This pass is not yet implemented!
6) Put the pieces back together to generate the LyX file.

If an unknown command+arguments has no newlines in it, reLyX will output
TeX mode. This is for things like \date{\today}. Otherwise, it copies into a
paragraph in LaTeX layout.


Amir Karger
karger@voth.chem.utah.edu
