RELYX(1) User Contributed Perl Documentation RELYX(1)NAMEreLyX - 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 ] [-n]
[ -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.
-n Noweb. Translate a noweb (aka literate programming)
file. This should be (almost?) equivalent to running
"noweb2lyx foo.tex foo.lyx". This option requires the
-c option.
-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 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:
Get through a well-behaved LaTeX2e file without
crashing
Translate a lot of that file.
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.
Usage
Here's a more lengthy description of what you should do to
translate a LaTeX document into LyX.
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.
Run LyX (version 0.12 or 1.0 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 document or
the BUGS file.
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.
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.
What reLyX Can Handle
reLyX understands many LaTeX commands. It will translate:
regular text, including mini-commands like ~, '', \@,
\TeX, as well as accented characters like \'{a}, and
the special cases ?` and !`
title commands like \author, \date, \title, \thanks
and the abstract environment
heading commands like \section including starred
commands (\section*)
Environments: quote, quotation, and verse; center,
flushright, and flushleft
itemize, enumerate, and description environments, and
their \item commands. Also, well-behaved nested lists
cross-referencing commands: \ref, \pageref, \label,
and \cite
\footnote and \margin
font-changing commands including \em, \emph, \textit,
and corresponding commands to change family, size,
series, and shape
\input{foo} (or \input{foo.blah}) and \include{foo}.
Plain TeX \input command "\input foo.tex" is also
supported.
tabular environment, and commands that go inside it
like \hline, \cline, and \multicolumn (but see below)
float environments table and table*, as well as
\caption commands within them
float environments figure and figure*, as well as
graphics inclusion commands \epsf, \epsffile,
\epsfbox, \epsfxsize, \epsfig, \psfig, and
\includegraphics. Both the graphics and graphicx
forms of \includegraphics are supported. Note,
however, that many figures will not be translatable
into LyX. See the section on "What LyX Can't Handle"
below.
thebibliography environment and \bibitem command, as
well as BibTeX's \bibliography and \bibliographystyle
commands
miscellaneous commands: \hfill, \\, \noindent,
\ldots...
documentclass-specific environments (and some
commands) which can be translated to LyX layouts
arguments to certain untranslatable commands (e.g.
\mbox)
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
tabular* tables
minipages
spacing commands (\vspace, \pagebreak, \par, ...)
\centering, \raggedleft, \raggedright
\verb and verbatim environment. reLyX is careful to
copy exactly in this case, including comments and
whitespace.
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 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.
"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.
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.
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
can export your final document as LaTeX, and put them back
in. See BUGS for more details on these bugs.
For a number of commands, LyX does not support the
optional argument. Examples include \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.
Centering (or right or left justifying) works on full
paragraphs.
LyX support for tables isn't perfect. For complicated
tables, use a "skip" block, so that they will be
copied in TeX mode.
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.
Lyx does not support clipping or bounding boxes for
included graphics files. Therefore, many graphics
inclusion commands will be untranslatable, and copied
in TeX mode. In certain cases, you might be able to
translate the command by hand within LyX---for
example, if you included a bounding box but the
bounding box is already in the .eps file.
LyX only allows figures to have sizes in in,cm, or
percentages of \textwidth or \textheight (or
\columnwidth). reLyX will translate from other units,
like pt or mm, but it cannot translate other lengths
(e.g. if you wanted to scale a figure to size
\topmargin for some reason). reLyX will copy figures
with untranslatable sizes in TeX mode. Again, you
might be able to fix that within LyX.
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.
EXAMPLESreLyX-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.
reLyX-n -c "literate-article" foo.tex
The above will change a noweb document into a LyX
literate-article document. A user would do this if the
noweb document had documentclass article.
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.
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:
Change, e.g., x^2 to the equivalent but
clearer x^{2}
Removing optional arguments that LyX can't
handle (e.g., from \chapter)
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.
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 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 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. <plug>
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. </plug>
DIAGNOSTICSreLyX 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
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 ALSOlyx(1), latex(1)AUTHORS
Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
Code contributors:
John Weiss wrote the original CleanTeX pass.
Etienne Grossmann
Jose Abilio Oliveira Matos
David Suarez de Lis
Kayvan Aghaiepour Sylvan added noweb stuff and wrote
noweb2lyx
Other contributors:
Jean-Marc Lasgouttes worked on the wrapper script and
offered lots of bug reports, advice, and feature
suggestions.
Asger K. Alstrup Nielsen and Marc Pavese provided
advice.
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.
11/Aug/99 Version 2.9.2.2 2.9.2.2 RELYX(1)
