man pages for reLyX
24/Jan/99 Last change: Version 2.8.1.2
User Contributed Perl Documentation RELYX(1)
NAME
reLyX - translate well-behaved LaTeX into LyX
SYNOPSIS
The simplest way to use reLyX is via the File->Import
command in LyX. (This option is available starting with
version 1.0.0.) That runs reLyX on the given file and loads
the resulting file into LyX. You should try that first, and
call it from the command line only if you need to use more
complicated options.
reLyX [ -c textclass ] [ -df ] [ -o outputdir ]
[ -r renv1[,renv2...]] [ -s sfile1[,sfile2...]] inputfile
reLyX -p -c textclass [ -df ] [ -o outputdir ]
[ -r renv1[,renv2...]] [ -s sfile1[,sfile2...]] inputfiles
reLyX -h
OPTIONS
-c Class. By default, when reLyX sees a \documentclass{foo}
command, it creates a file of textclass "foo" and reads
the LyX layout file for that class (something like
/usr/local/share/lyx/layouts/foo.layout OR
HOME/.lyx/layouts/foo.layout). Use -c to declare a
different textclass (and read a different layout file).
-d Debug. By default, reLyX gives sparse output and deletes
the temporary files which were created during
translation. Using the -d flag will create much more
output (both to stdout and stderr) and leave the
temporary files around.
-f Force. reLyX will not run if the .lyx file it would
generate already exists Use the -f option (carefully) to
clobber any existing files.
-h Help. Print out usage information and quit
-o Output directory. With this option, all temporary files
and LyX output files (for the given input file, for any
included files, or for any file fragments given with the
-p option) will be put into outputdir. Otherwise, for
each file dir/foo.tex, the temporary files and the LyX
output file will be created in dir. This can be useful
if a file includes files from other directories which
you want to consolidate in one directory, or if you
don't have write permission on the directory the LaTeX
files are in.
-p Partial file. The input files are LaTeX fragments, with
no preamble matter or \begin{document} commands. This
User Contributed Perl Documentation RELYX(1)
option requires the -c option, since there are no
\documentclass commands in the files reLyX is
translating. When using this option, you can translate
more than one file, as long as all files are the same
class. The LyX file created by reLyX can be included in
an existing LyX file using the "Include LyX File"
command from LyX's Insert menu.
-r Regular environments (see the section on Syntax Files).
If you give more than one environment, separate them
with commas (not spaces). You'll probably need to quote
the environment list, especially if it has asterisk
environments (foo*) in it. If you use this command
often, considering creating a personal syntax file.
-s Syntax files. Input (one or more quoted, comma-
separated) syntax files to read in addition to the
default. (see the section on Syntax Files for details).
DESCRIPTION
Introduction
reLyX will create a LyX file dir/foo.lyx from the LaTeX file
dir/foo.tex (unless the -o option is used).
Suffixes .tex, .ltx and .latex are supported. If inputfile
does not exist and does not have one of these suffixes,
reLyX will try to translate inputfile.tex. (This is similar
to the behavior of LaTeX.)
The purpose of reLyX is to translate well-behaved LaTeX2e
into LyX. If your LaTeX file doesn't compile---or if you do
weird things, like redefining standard LaTex commands---it
may choke. LaTeX209 will often be translated correctly, but
it's not guaranteed.
reLyX has some bugs and lacks a few features. However, its
main goals are:
o Get through a well-behaved LaTeX2e file without crashing
o Translate a lot of that file.
o Localize the parts that can't be translated and copy
them in TeX mode
It achieves these main goals pretty well on most files.
There are many improvements that can and will be made to
reLyX in the future. However, we wanted to get reLyX out
there early on, to make it easier for new LyX users to read
in their existing LaTeX files.
User Contributed Perl Documentation RELYX(1)
Usage
Here's a more lengthy description of what you should do to
translate a LaTeX document into LyX.
o Run reLyX.
reLyX will inform you of its progress and give any
warnings to stderr, so if you don't want any output at
all, try (in csh) 'reLyX foo.tex >& /dev/null'. You
should NOT redirect standard output to foo.lyx.
o Run LyX (version 0.12 or later) 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). In theory, LyX will be able to read
in the file, and to create printed documents from it,
because all that untranslated red stuff will be passed
directly back to LaTeX, which LyX uses as a backend.
Unfortunately, reality doesn't always reflect theory. If
reLyX crashes, or LyX cannot read the generated LyX
file, see the BUGS entry elsewhere in this documentor
the BUGS file.
o Change things that are highlighted in red (TeX mode) by
hand in LyX.
As mentioned above, you should be able to print out the
LyX file even without doing this. However, changing a
command in TeX mode to the corresponding LyX object will
allow you to take advantage of LyX's WYSIWYM editing.
reLyX is not guaranteed to create a LyX file which
generates exactly the same output as the LaTeX file, but
it should come close. relyX will generally err on the
side of translating less to ensure that dvi or ps files
are accurate, even though this leads to more "evil red
text" and less WYSIWYM.
o PROOFREAD THE DOCUMENT!!
I'm sure you were planning on doing this anyway, but
it's particularly important after translating a LaTeX
document. 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.
Space handling has improved, but it's not perfect.
User Contributed Perl Documentation RELYX(1)
What reLyX Can Handle
reLyX understands many LaTeX commands. It will translate:
o regular text, including mini-commands like ~, '', \@,
\TeX, as well as accented characters like \'{a}, and the
special cases ?` and !`
o title commands like \author, \date, \title, \thanks and
the abstract environment
o heading commands like \section including starred
commands (\section*)
o Environments: quote, quotation, and verse; center,
flushright, and flushleft
o itemize, enumerate, and description environments, and
their \item commands. Also, well-behaved nested lists
o cross-referencing commands: \ref, \pageref, \label, and
\cite
o \footnote and \margin
o font-changing commands including \em, \emph, \textit,
and corresponding commands to change family, size,
series, and shape
o \input{foo} (or \input{foo.blah}) and \include{foo}.
Plain TeX \input command "\input foo.tex" is also
supported.
o tabular environment, and commands that go inside it like
\hline, \cline, and \multicolumn (but see below)
o float environments table and table*, as well as \caption
commands within them
o thebibliography environment and \bibitem command, as
well as BibTeX's \bibliography and \bibliographystyle
commands
o miscellaneous commands: \hfill, \\, \noindent, \ldots...
o documentclass-specific environments (and some commands)
which can be translated to LyX layouts
o arguments to certain untranslatable commands (e.g.
\mbox)
User Contributed Perl Documentation RELYX(1)
Some of this support may not be 100% yet. See below for
details
reLyX copies math (almost) verbatim from your LaTeX file.
Luckily, LyX reads in LaTeX math, so (almost) any math which
is supported by LyX should work just fine. A few math
commands which are not supported by LyX will be replaced
with their equivalents, e.g., \to is converted to
\rightarrow. See the section on Syntax Files for more
details.
reLyX will also copy any preamble commands (i.e., 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
o figures and tabular* tables
o minipages
o spacing commands (\vspace, \pagebreak, \par)
o \centering, \raggedleft, \raggedright
o \verb and verbatim environment. reLyX is careful to copy
exactly in this case, including comments and whitespace.
o some unknown (e.g., user-defined) environments and
commands
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} (unless you use the -r
option). 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.
What reLyX Handles Badly --- aka BUGS
Since reLyX is relatively new, it's got a number of
problems. As it matures, these bugs will be squished.
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. reLyX
User Contributed Perl Documentation RELYX(1)
will copy this block exactly, in TeX mode. Then edit the
resulting LyX file, and translate the unknown stuff by hand.
The reLyXskip environment is magical; the \begin and \end
commands will not be put into the LyX file.
o "Exact" copying of unknown environments and commands
isn't quite exact. Specifically, newlines and comments
may be lost. This will yield ugly LyX, but in almost all
cases the output will be the same. However, certain
parts of the file will be copied perfectly, including
whitespace and comments. This includes: the LaTeX
preamble, verbatim environments and \verb commands, and
skip blocks.
o reLyX translates only a few options to the
\documentclass command. (Specifically 1[012]pt,
[letter|legal|executive|a4|a5|b5]paper, [one|two]side,
landscape, and [one|two]column.) Other options are
placed in the "options" field in the Layout->Document
popup.
More importantly, reLyX doesn't translate \usepackage
commands, margin commands, \newcommands, or, in fact,
anything else from the preamble. It simply copies them
into the LaTeX preamble. If you have margin commands in
your preamble, then the LyX file will generate the right
margins. However, these margins will override any
margins you set in the LyX Layout->Paper popup. So you
should remove the options from the preamble (Layout-
>Latex Preamble) to be safe. The same goes for setting
your language with babel, \inputencoding, \pagestyle,
etc.
o The foil class has a couple bugs. reLyX may do weird
things with optional arguments to \foilhead commands.
Also, it may handle \begin{dinglist} incorrectly
(although the stuff in the environment should translate
normally).
Less significant bugs can be found in the BUGS file.
reLyX is hopefully rather robust. As mentioned above, it may
not translate your file perfectly, but it shouldn't crash.
If it does crash---and the problem is not one of those
mentioned above or in the BUGS file---see the section on Bug
Reports.
What LyX Can't Handle
LyX itself is missing a couple features, such that even if
reLyX translates things perfectly, LyX may still have
trouble reading it. If you really need these features, you
User Contributed Perl Documentation RELYX(1)
can export your final document as LaTeX, and put them back
in. See BUGS for more details on these bugs.
o For a number of commands, LyX does not support the
optional argument. Examples include \sqrt, \chapter (and
other sectioning commands), and \\. reLyX will
automatically discard the optional arguments with a
warning to stdout. LyX also ignores the width argument
for the thebibliography environment.
o Centering (or right or left justifying) works on full
paragraphs.
o LyX support for tables isn't perfect. For complicated
tables, use a "skip" block, so that they will be copied
in TeX mode.
o The LyX math editor can't handle the AMS-LaTeX math
environments align, split, etc. So those environments
will be copied in TeX mode. You can change equation*
environments to the exactly equivalent displaymath, and
then they will be translated correctly.
The Future of reLyX
In the future, more commands and environments will be
supported by reLyX. Bugs will be eradicated.
See the TODO file for details.
EXAMPLES
reLyX -df -o "my/dir" -r "myenv" foo.tex > foo.debug
The above will create a file my/dir/foo.lyx from foo.tex,
overwriting if necessary. When it finds a \begin{myenv} ...
\end{myenv} block, it will translate the stuff within the
block, but copy the \begin and \end commands in TeX mode.
Finally, I'm going to keep the temporary files around (they
will also be in my/dir/) and output lots of debugging
information into the file foo.debug.
NOTES
Bug Reports
If reLyX is crashing or otherwise acting strangely---in ways
other than those described in the section on BUGS or the
BUGS file---then please run reLyX -d. That will allow you
to figure out where in the reLyXing process it crashed.
That, in turn, will allow you to write a better bug report,
which will allow the developers to fix it more quickly and
easily.
User Contributed Perl Documentation RELYX(1)
Bug reports should be sent to the LyX developers' mailing
list. Its address is currently lyx-devel@lists.lyx.org, but
you can check the LyX home page, http://www.lyx.org if that
bounces. If you are running reLyX on a huge file, please do
not send all of the output in your bug report. Just include
the last ten or twenty lines of output, along with the piece
of the LaTeX file it crashed on. Or, even better, attach a
small but complete file which causes the same problem as
your original file.
Implementation Details:
reLyX makes several "passes" in order to translate a TeX
file. On each pass, it creates one or two files.
Pass 0
Before doing anything, read the syntax file (or files).
Pass 1a
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. It also
ignores anything after the \end{document}, on the
assumption that it isn't LaTeX.
Pass 1b
Translate the preamble. Currently, that just means
translating the \documentclass command and copying the
rest exactly into the LyX preamble.
Once you know what class the document is, read the LyX
layout file for that class.
Pass 2
"Clean" the TeX file, generating slightly stricter
LaTeX. This includes:
o Change, e.g., x^2 to the equivalent but clearer
x^{2}
o Removing optional arguments that LyX can't
handle (e.g., from \sqrt)
o Changing {\em foo} to \emph{foo}, etc. This is
necessary because LyX always writes out the
non-local forms anyway. This should very rarely
make a difference.
Pass 3
Translate LaTeX text, commands, and environments to LyX.
User Contributed Perl Documentation RELYX(1)
Pass 4
Put the two pieces back together, and do some final
tweaking, to generate the LyX file
If there are any \input or \include commands, reLyX will
loop back to the beginning and translate those. It assumes
that the included files are the same class as the main file,
and that they have no preamble matter. (If you have an
\input command in the preamble of a file, the command will
be copied exactly into the LaTeX preamble portion of the LyX
file, so the included file won't be translated.) So when
translating included files, it skips passes 0 and 1.
If reLyX doesn't find a file you wanted to include, it will
give a warning, but will continue to translate any files it
does find.
Layout Files
reLyX reads a LyX layout file to know how to handle LaTeX
environments and commands which get translated to LyX
layouts. This file will include all "normal" non-math
environments (i.e., including quote and itemize, but not
tabular, minipage, and some other fancy environments), and
commands like \section and \title. If you want to reLyX a
class that doesn't have an existing layout file, then you'll
have to create a layout file. But you have to do this
anyway, in order to LyX the file, since LyX depends on
layout files to know how to display and process its files.
Check the LyX documentation for help with this task (which
can be hard or easy, depending on the class you want to
create a layout file for.) If your class is quite similar to
a class that has a layout file, then consider using the -c
option.
Syntax Files
reLyX always reads at least one syntax file, called the
default syntax file. reLyX will read your personal syntax
file if it exists; otherwise it will read the system-wide
file. reLyX will read additional syntax files if you specify
them with the -s option. (These extra files should have the
same format as the default file, but will tend to be
shorter, since they only have to specify extra commands not
found in the default file.) A syntax file tells reLyX a few
things.
First, it describes the syntax of each command, that is, how
many required arguments and how many optional arguments the
command takes. Knowing this makes it easier for reLyX to
copy (in TeX mode) commands that it doesn't know how to
translate. The syntax file simply has a command, followed by
User Contributed Perl Documentation RELYX(1)
braces or brackets describing its arguments in the correct
order. For example, a syntax file entry \bibitem[]{} means
that the \bibitem command takes an optional argument
followed by a required one, while the entry \bf means that
the \bf command takes no arguments at all. When reLyX
encounters a token that it doesn't know how to translate
into LyX, it will copy the token---along with the correct
number of arguments---exactly. If the token is not in the
syntax file, then reLyX just copies as many arguments as it
finds. This means that it may copy too much. But since the
user can specify additional syntax files, that shouldn't
happen often.
Some commands that cannot be translated to LyX, like \mbox,
have as one of their arguments regular LaTeX text. If the
string "translate" is put into an argument of an
(untranslatable) command in the syntax file, then reLyX will
translate that argument instead of copying it verbatim. So,
for example, the default syntax file has
\raisebox{}[][]{translate}. This means that the \raisebox
command and the first argument (and optional arguments if
they exist) are copied in TeX mode, but the last argument
(which may contain math, complicated LaTeX, other
untranslatable commands, etc.) will be translated into LyX.
You can't use "translate" on optional arguments.
User-defined syntax files are allowed to define new commands
and their syntax, or override the number of arguments for a
command given in the default syntax file. (E.g., if you're
using a style that gives an extra argument to some
command...) However, this will only be useful for commands
copied in TeX mode. Commands which are actually translated
by reLyX (like \item) have their argument syntax hard-coded.
The hard-coded commands are identified in the default syntax
file.
Second, the syntax file describes any "regular
environments". Usually, an entire unknown environment will
be copied in TeX mode. If you define a regular environment
"foo", though, then only the \begin{foo} and \end{foo}
commands will be copied in TeX mode; the text within the
environment will be treated (i.e., translated) by reLyX as
regular LaTeX, rather than being copied into TeX mode. Don't
try to declare "tabbing" and "picture" as regular
environments, as the text within those environments will
confuse reLyX; use this capability for new environments you
create that have plain text or math or simple commands in
them. You also can't declare unknown math environments (like
equation*) as regular environments, either, since the LyX
math editor won't understand them. The names of regular
environments appear, whitespace-separated, between
\begin{reLyXre} and \end{reLyXre} statements in the syntax
User Contributed Perl Documentation RELYX(1)
file. (If you have a regular environment which you won't use
very often, you can use the -r option rather than writing a
syntax file.)
Third, the syntax file describes a math translation table.
The LyX math editor doesn't support a few commands. For
example, _ is supported, but the equivalent \sb is not. Put
any commands you'd like translate between \begin{reLyXmt}
and \end{reLyXmt} statements. The statement "\| {\Vert}"
means that any \| in math mode will be converted to "\Vert "
(in cases where a token made up of a backslash and a non-
letter is translated to something with letters at the end, a
space is added by reLyX. That way, "\|a" is correctly
translated to "\Vert a").
Miscellaneous
You need Perl version 5.002 or later to run reLyX. If
you don't have Perl, you should get it anyway (at
http://www.perl.com), because it's a really useful tool for
pretty much anything.
DIAGNOSTICS
reLyX should always explain why it crashes, if it crashes.
Some diagnostics may be very technical, though, if they come
from the guts of the code. reLyX gives much more
information while running if you use the -d option, but you
shouldn't need that unless something goes wrong.
When it's finished, reLyX will tell you if it finished
successfully or died due to some error.
WARNINGS
Always keep a copy of your original LaTeX files either under
a different name or in a different directory. There are a
couple ways in which using LyX could lead to overwriting the
original LaTeX file.
If you import foo.tex to create foo.lyx, then edit foo.lyx
and want to re-export it, note that it will overwrite the
original foo.tex. (LyX will ask you if you want to overwrite
it.)
If you have the \use_tempdir variable set to false in your
lyxrc, then LyX will create its temporary files in your
current directory, which means your LaTeX original may be
overwritten (without a warning from LyX) when you "view dvi"
or print the LyX document.
FILES
User Contributed Perl Documentation RELYX(1)
MY_LYXDIR/layouts/*.layout
User's personal layout files for document classes
MY_LYXDIR/reLyX/syntax.default
User's personal syntax file
LIBDIR/layouts/*.layout
System-wide layout files for document classes
LIBDIR/reLyX/syntax.default
System-wide LaTeX syntax file
LIBDIR is the system-wide LyX directory, usually something
like /usr/local/share/lyx/. MY_LYXDIR is your personal LyX
directory, something like .lyx/ in your home directory.
SEE ALSO
lyx(1), latex(1)
AUTHORS
Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
Code contributors:
o John Weiss wrote the original CleanTeX pass.
o Etienne Grossmann
o Jose Abilio Oliveira Matos
o David Suarez de Lis
Other contributors:
o Jean-Marc Lasgouttes worked on the wrapper script and
offered lots of bug reports, advice, and feature
suggestions.
o Asger K. Alstrup Nielsen and Marc Pavese provided
advice.
o Various members of the LyX developers' and users' lists
provided bug reports and feature suggestions.
reLyX uses a modified version the Perl TeX parser Text::TeX
package written by Ilya Zakharevich (ilya@math.ohio-
state.edu), available on CPAN.
User Contributed Perl Documentation RELYX(1)