man
1 reLyX
RELYX(1) 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 ] [-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:
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.
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 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.
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.
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 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.
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)
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 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 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 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 \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.
o 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.
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.
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:
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 \chapter)
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.
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.)
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>
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
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
o Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx
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.
3rd Berkeley Distribution Version 2.9.2.2 2.9.2.2 RELYX(1)