<< | Page list | >>
This page is obsolete, tex2lyx is part of regular LyX releases now.
|' Converting |
|The LyX Team|
We all know that LyX produces LaTeX files, but often it's necessary to go the other way and convert a LaTeX file to LyX. Two tools are available to help:
- the traditional (but unmaintained)
reLyX Perl script and
- the brand new and shiny
tex2lyx C++ code.
tex2lyx is part of the 1.4 release of LyX. This page describes its use with older LyXes (such as LyX 1.3.x) and provides some ready-to-use packages.
Note that the command line syntax has been changed (25 July 2005) in order to be compatible with
reLyX. See the usage example below.
tex2lyx has not yet been released formally. Nonetheless, it is in a useable state now and is far more powerful than the old
reLyX. Here, therefore, are some snapshots for various platforms. Feel free to upload one compiled on your own OS. (Recipes to create such a package are provided below.) Remember, however, that this is pre-release software. Always back up your files. Caveat emptor.
The package will expand to a directory tree:
(LyX is packaged slightly differently on different OSes. The tree above is that of the Windows package. In the Unix package the
Resources directory is named
share.) Here, I installed the package as
J:\Programs\LyX. It'd be interesting to hear if all works as expected if it's installed as
The tree above highlights the three tools that are bundled in the package:
reLyX is the old, deprecated Perl script to convert a LaTeX file to LyX. It's unmaintained but it might just work for you.
tex2lyx.exe is the replacement for
reLyX. It's written in C++, so must be compiled for your particular OS. It is based on a formally-correct TeX parser and so should be able to handle almost any LaTeX file that's thrown at it. Those LaTeX constructs that it does not know about or which LyX does not support natively will become ERT insets in the LyX file. I.e., nothing will be lost but LyX will display the raw LaTeX.
lyx2lyx is a Python script to convert a LyX file in one format to a LyX file in another format. The LyX file format evolves from one release to the next, so this tool enables the LyX executable that you're using to read the LyX file that you've produced.
tex2lyx produces a LyX file in a format understandable to LyX 1.4.0. The
lyx2lyx script packaged here (unlike the version packaged with LyX 1.3.x) is able to revert this to a format understandable to LyX 1.3.x because it refers to
*.py files shipped with LyX 1.4.
- You may safely copy the
*.py files located in
Resources/LyX/lyx2lyx} (but NOT the
lyx2lyx script istelf) in your 1.3.x (for x >= 6)
Resources/lyx/lyx2lyx} directory: if you have multipart documents, you should do it to reread the
lyx files without using the
lyx-1.4 lyx2lyx script on each files created.
- You should not mix the other files coming with this package (e.g. layouts) with the files already present in your LyX installation.
These tools have no graphical interface and so must be invoked from the command line (alternatively, you can invoke
tex2lyx directly from LyX as explained in Tex2Lyx invoked from Lyx). In the example below I assume that the name of the LyX 1.3.x expectable is
lyx-13x and that it,
tex2lyx are in the
PATH. The location of the
lyx2lyx script is dependent on how the package above was installed. Change to suit, but you will not need to run it on the imported files if you have patched the
LyX-1.4/share|resources/lyx/lyx2lyx/*.py files in the
$ indicates a command input at the command line whilst the prefix
# indicates a comment.
# Export the LyX User Guide in LyX 1.3.x format (format number 221) to LaTeX.
# This will create a file
$ lyx-13x --export latex UserGuide_13x.lyx
# Convert this LaTeX file back to LyX using
# This creates a file
UserGuide_14x.lyx in a format
# understandable to LyX 1.4.0 but not to LyX 1.3.x.
$ tex2lyx UserGuide_13x.tex UserGuide_14x.lyx
# Note that tex2lyx versions older than 2005-07-25 wrote the file
# to standard output, and therefore needed the following command line:
# tex2lyx UserGuide_13x.tex > UserGuide_14x.lyx
# Convert this LyX file to one understandable to LyX 1.3.x.
$ python J:/Programs/LyX/Resources/lyx/lyx2lyx/lyx2lyx \
--to 221 --output UserGuide_13x_2.lyx UserGuide_14x.lyx
The resulting LyX file
UserGuide_13x_2.lyx is clearly different to the original
UserGuide_13x.lyx. Much of this difference is simply formatting, however. Loading and saving the file with
lyx-13x will remove the noise leaving only substantive changes. These changes can be classified in four groups:
- Default values for fields which need not be stored in the LyX file. The converted file does not contain these.
- Constructs that are not exported by LyX to LaTeX. That's the contents of any Note insets.
- LaTeX constructs that are not (yet) recognized by
tex2lyx as translatable to an appropriate LyX inset. Until 2005-03-05 the footnote inset in the Author field at the top of the User Guide fell into this category. The footnote inset became an ERT inset in
UserGuide_13x_2.lyx containing the raw LaTeX.
- Things that have been translated incorrectly. The test for this is a comparison of the
.dvi files generated from the two LyX files.
At the time of writing, the two
.dvi files are almost, but not quite, identical:
$ ls -l *.dvi
-rw-rw-r-- 1 angus angus 496736 Feb 15 22:33 UserGuide_13x.dvi
-rw-rw-r-- 1 angus angus 496940 Feb 15 22:33 UserGuide_13x_2.dvi
Preliminary investigations suggest that the primary problem here lies with the
\includegraphics LaTeX construct. If the
.eps files are not found (as was the case here), then LyX exports a LaTeX file containing the pretty-printing output 'mobius.eps not found!'.
tex2lyx imports this back as the file
mobius.eps not found!!
How to make it better
The best way to make the code better is to use it and to report any problems that it has to the LyX developers mailing list. Please report the problem using bugzilla if you are familiar with it. Please included a minimal LaTeX file that exhibits the problem. Examples in decreasing order of severity might be:
- Translation to a mal-formed LyX file (one that cannot be loaded by LyX);
- Translation to a valid LyX file but one which outputs different LaTeX to the original. The real test is presumably a difference in the content of the generated
- A special case of the previous one are constructs that are translated to native LyX formatting but which are only partially supported in LyX. One example is the environment
thebibliography, which takes one parameter. This parameter is computed automatically in LyX, so tex2lyx discards it on translation.
- Translation to a formally-correct LyX file but one which contains ERT insets of things that should be supported natively by LyX.
The following shortcomings of
tex2lyx are known, so please don't report them again:
- minipages and parboxes may be converted incorrectly. This depends on the options.
\bibliographystyle command may be converted to ERT and native LyX format. LaTeX will not run in this case. Simply remove the generated ERT to make it work.
- tables may be imported incorrectly. Until 2005-03-10 the set of supported column specifications was rather limited. Convert all columns to
c if you have a tex2lyx from that date or older and the columns are recognized incorrectly. Then you can set the column style from LyX.
- longtables may be imported incorrectly.
- Nested tables make
tex2lyx versions before 2005-03-14 crash
\vspace between paragraphs is sometimes not recognized as paragraph skip but converted to ERT.
- Many fancy preamble constructs are not supported, and can confuse tex2lyx, so that it creates a broken .lyx file. If you have a complex preamble, move its contents to a file (say
preamble.tex) and include it in the preamble of your main document with
tex2lyx will then leave the file
preamble.tex alone. You should however leave all
\usepackage commands in the main document, since
tex2lyx recognizes many of them and converts them to suitable LyX document settings.
Creating your own package
It's possible that the packages attached above won't run on your platform or that they have become out of date. Remember, we're talking about pre-release software here, so things evolve. In either case, you should consider building your own package. That's probably quite easy for Linux users, used to having a functional compiler environment on their machines, but also something that sounds quite scary to most Windows bods. Don't worry: the process of setting up the environment is mechanical, although it also requires some stamina. Thereafter, building the package itself takes only a few minutes.
If you do build a package, then please upload it to this page.
Setting up the build environment on a Windows machine
Setting up the build environment on an Linux distribution
You should be fine, if you have chosen "Development" or something similar in the Task selection on installing your system.
- You need a new automake (and dependencies). Debian/testing defaults to automake 1.4 which is too old. The package automake1.7 works fine, however.
Grabbing the sources from the CVS repository
See the LyX Developer Page for instructions on how to get hold of the LyX sources. Using a command-line interface, it should be as simple as:
# You'll be prompted for a password. It is
$ cvs -d:pserver:firstname.lastname@example.org:/var/cvs/lyx login
# Install the LyX sources in a directory
$ cvs -d:pserver:email@example.com:/var/cvs/lyx checkout -d devel lyx-devel
Thereafter, you'll be able to keep your sources up to date by typing:
$ cvs update -dP
devel directory. You won't need to specify the
anoncvs.us.lyx.org server anymore; that information is stored safely in the
Windows users tend to use a GUI tool such as TortoiseCVS. Use is straightforward.
Building the package
Having set up the build environment and grabbed the LyX 1.4.x sources from the CVS repository, building the
tex2lyx distribution is as simple as using the make_tex2lyx_dist shell script from the top level of the LyX source distribution:
$ sh make_tex2lyx_dist.sh .
Thereafter, it takes 3:30 minutes on a 2.8GHz machine running Fedora Core 3 and somewhat longer (10 minutes) on the same machine running Windows XP. The result of these builds were files
tex2lyx_linux_16Feb05.tar.gz. This latter was renamed as
tex2lyx_FC3_16Feb05.tar.gz before it was uploaded to enable other Linux distributions to be uploaded and retrieved also.