lyx_mirror/lib/reLyX/reLyX.pod

=head1 NAME

B<reLyX> - translate well-behaved LaTeX into LyX

=head1 SYNOPSIS

The simplest way to use B<reLyX> is via the File->Import command in LyX. (This
option is available starting with version 1.0.0.) That runs B<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.

B<reLyX> [ B<-c> I<textclass> ] [ B<-df> ] [ B<-o> I<outputdir> ] [B<-n>]
S<[ B<-r> I<renv1>[,I<renv2>...]]> S<[ B<-s> I<sfile1>[,I<sfile2>...]]>
F<inputfile>

B<reLyX> B<-p> B<-c> I<textclass> [ B<-df> ] [ B<-o> I<outputdir> ]
S<[ B<-r> I<renv1>[,I<renv2>...]]> S<[ B<-s> I<sfile1>[,I<sfile2>...]]>
F<inputfiles>

B<reLyX> B<-h>

=head1 OPTIONS

=over 4

=item B<-c>

Class. By default, when B<reLyX> sees a C<\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
B<HOME>/.lyx/layouts/foo.layout).  Use B<-c> to declare a different textclass
(and read a different layout file).

=item B<-d>

Debug. By default, B<reLyX> gives sparse output and deletes the temporary files
which were created during translation. Using the B<-d> flag will create much
more output (both to stdout and stderr) and leave the temporary files around.

=item B<-f>

Force. B<reLyX> will not run if the .lyx file it would generate already exists
Use the B<-f> option (carefully) to clobber any existing files.

=item B<-h>

Help. Print out usage information and quit.

=item B<-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 B<-c> option.

=item B<-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 B<-p> option) will be put into I<outputdir>. Otherwise, for
each file F<dir/foo.tex>, the temporary files and the LyX output file will be
created in F<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.

=item B<-p>

Partial file. The input files are LaTeX fragments, with no preamble matter or
C<\begin{document}> commands. This option requires the B<-c> option, since there
are no C<\documentclass> commands in the files B<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 B<reLyX> can be included in an
existing LyX file using the "Include LyX File" command from LyX's Insert menu.

=item B<-r>

Regular environments (see L<"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.

=item B<-s>

Syntax files. Input (one or more quoted, comma-separated) syntax files to read
in addition to the default. (see L<"Syntax Files"> for details).

=back

=head1 DESCRIPTION

=head2 Introduction

B<reLyX> will create a LyX file F<dir/foo.lyx> from the LaTeX file
F<dir/foo.tex> (unless the B<-o> option is used).

Suffixes .tex, .ltx and .latex are supported. If F<inputfile>
does not exist and does not have one of these suffixes, B<reLyX> will try to
translate F<inputfile.tex>. (This is similar to the behavior of LaTeX.)

The purpose of B<reLyX> is to translate I<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.

B<reLyX> has some bugs and lacks a few features. However, its main goals are:

=over 4

=item *

Get through a well-behaved LaTeX2e file without crashing

=item *

Translate a lot of that file.

=item *

Localize the parts that can't be translated and copy them in TeX mode

=back 4

It achieves these main goals pretty well on most files.

There are many improvements that can and will be made to B<reLyX> in the
future. However, we wanted to get B<reLyX> out there early on, to make
it easier for new LyX users to read in their existing LaTeX files.

=head2 Usage

Here's a more lengthy description of what you should do to translate a LaTeX
document into LyX.

=over 4

=item *

Run B<reLyX>.

B<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 F<foo.lyx>. 

=item *

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
B<reLyX> crashes, or LyX cannot read the generated LyX file, see L</BUGS>,
or the F<BUGS> file.

=item *

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.

B<reLyX> is not guaranteed to create a LyX file which generates exactly the same
output as the LaTeX file, but it should come close. B<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.

=item *

PROOFREAD THE DOCUMENT!!

I'm sure you were planning on doing this anyway, but it's particularly
important after translating a LaTeX document. B<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.

=back

=head2 What reLyX Can Handle

B<reLyX> understands many LaTeX commands. It will translate:

=over 4

=item *

regular text, including mini-commands like ~, '', C<\@>, C<\TeX>, as well as
accented characters like C<\'{a}>, and the special cases ?` and !`

=item *

title commands like C<\author>, C<\date>, C<\title>, C<\thanks> and the
abstract environment

=item *

heading commands like C<\section> including starred commands (C<\section*>)

=item *

Environments: quote, quotation, and verse; center, flushright, and flushleft

=item *

itemize, enumerate, and description environments, and their C<\item> commands.
Also, well-behaved nested lists

=item *

cross-referencing commands: C<\ref>, C<\pageref>, C<\label>, and C<\cite>

=item *

C<\footnote> and C<\margin>

=item *

font-changing commands including C<\em>, C<\emph>, C<\textit>, and
corresponding commands to change family, size, series, and shape

=item * 

C<\input{foo}> (or C<\input{foo.blah}>) and C<\include{foo}>. Plain TeX
C<\input> command "C<\input foo.tex>" is also supported.

=item *

tabular environment, and commands that go inside it like C<\hline>, C<\cline>,
and C<\multicolumn> (but see below)

=item *

float environments table and table*, as well as C<\caption> commands within
them

=item *

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.

=item *

thebibliography environment and C<\bibitem> command, as well as BibTeX's
C<\bibliography> and C<\bibliographystyle> commands

=item *

miscellaneous commands: C<\hfill>, C<\>C<\>, C<\noindent>, C<\ldots>...

=item *

documentclass-specific environments (and some commands) which can be 
translated to LyX layouts

=item *

arguments to certain untranslatable commands (e.g. C<\mbox>)

=back

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

B<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., C<\to> is converted to C<\rightarrow>. See
L<"Syntax Files"> for more details.

B<reLyX> will also copy any preamble commands (i.e., anything before
C<\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.

=head2 What reLyX Can't Handle --- But it's OK

=over 4

=item *

tabular* tables

=item *

minipages

=item *

spacing commands (C<\vspace>, C<\pagebreak>, C<\par>, ...)

=item *

C<\centering>, C<\raggedleft>, C<\raggedright>

=item *

C<\verb> and verbatim environment. B<reLyX> is careful to copy I<exactly> in
this case, including comments and whitespace.

=item *

some unknown (e.g., user-defined) environments and commands

=back

B<reLyX> copies unknown commands, along with their arguments, verbatim into the
LyX file. Also, if it sees a C<\begin{foo}> where it doesn't recognize the
"foo" environment, it will copy verbatim until it sees C<\end{foo}> (unless
you use the B<-r> option). Hopefully, then, most of these unknown commands
won't cause B<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.

=head2 What reLyX Handles Badly --- aka BUGS

Since B<reLyX> is relatively new, it's got a number of problems.  As it
matures, these bugs will be squished.

If B<reLyX> is choking on something, or LyX can't read it after B<reLyX>
translates it, the best thing to do is to put C<\begin{reLyXskip}> before the
offending text, and C<\end{reLyXskip}> after it. I call this a "skip" block.
B<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 C<\begin> and C<\end> commands will not be put into the LyX
file.

=over 4

=item *

"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 C<\verb> commands, and
skip blocks.

=item *

B<reLyX> translates only a few options to the C<\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, B<reLyX> doesn't translate C<\usepackage> commands, margin 
commands, C<\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, C<\inputencoding>, C<\pagestyle>, etc.

=item *

The foil class has a couple bugs. B<reLyX> may do weird things with optional
arguments to C<\foilhead> commands. Also, it may handle C<\begin{dinglist}>
incorrectly (although the stuff in the environment should translate normally).

=back

Less significant bugs can be found in the F<BUGS> file.

B<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 F<BUGS> file---see
L<"Bug Reports">.

=head2 What LyX Can't Handle

LyX itself is missing a couple features, such that even if B<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 F<BUGS> for more details on these bugs.

=over 4

=item *

For a number of commands, LyX does not support the optional argument. Examples
include C<\chapter> (and other sectioning commands), and C<\\>.
B<reLyX> will automatically discard the optional arguments with a warning to
stdout.  LyX also ignores the width argument for the thebibliography
environment.

=item *

Centering (or right or left justifying) works on full paragraphs.

=item *

LyX support for tables isn't perfect. For complicated tables, use a "skip"
block, so that they will be copied in TeX mode.

=item *

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.

=item *

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). B<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). B<reLyX> will copy figures with
untranslatable sizes in TeX mode. Again, you might be able to fix that within
LyX.

=back

=head2 The Future of reLyX

In the future, more commands and environments will be supported by B<reLyX>.
Bugs will be eradicated.

See the TODO file for details.

=head1 EXAMPLES

reLyX B<-df> B<-o> "my/dir" B<-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 C<\begin{myenv} ... \end{myenv}> block, it will
translate the stuff within the block, but copy the C<\begin> and C<\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 B<-n> B<-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.

=head1 NOTES

=head2 Bug Reports

If B<reLyX> is crashing or otherwise acting strangely---in ways
other than those described in L<"BUGS"> or the F<BUGS> file---then please run
B<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 B<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.

=head2 Implementation Details:

B<reLyX> makes several "passes" in order to translate a TeX file. On each pass,
it creates one or two files.

=over 4

=item Pass 0

Before doing anything, read the syntax file (or files).

=item Pass 1a

Split preamble (anything before a C<\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 C<\end{document}>, on the assumption that it isn't LaTeX.

=item Pass 1b

Translate the preamble. Currently, that just means translating the
C<\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.

=item Pass 2

"Clean" the TeX file, generating slightly stricter LaTeX. This includes:

=over 8

=item *

Change, e.g., x^2 to the equivalent but clearer x^{2}

=item *

Removing optional arguments that LyX can't handle (e.g., from C<\chapter>)

=item *

Changing C<{\em foo}> to C<\emph{foo}>, etc. This is necessary because LyX
always writes out the non-local forms anyway. This should very rarely make a
difference.

=back

=item Pass 3

Translate LaTeX text, commands, and environments to LyX.

=item Pass 4

Put the two pieces back together, and do some final tweaking, to generate the
LyX file

=back

If there are any C<\input> or C<\include> commands, B<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 C<\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 B<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.

=head2 Layout Files

B<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
C<\section> and C<\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 B<-c> option.

=head2 Syntax Files

B<reLyX> always reads at least one syntax file, called the default syntax file.
B<reLyX> will read your personal syntax file if it exists; otherwise it will
read the system-wide file. B<reLyX> will read additional syntax files if you
specify them with the B<-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
B<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 B<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 C<\bibitem[]{}> means that the C<\bibitem> command takes
an optional argument followed by a required one, while the entry C<\bf>
means that the C<\bf> command takes no arguments at all.  When B<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 B<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 C<\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 B<reLyX> will
translate that argument instead of copying it verbatim. So, for example, the
default syntax file has C<\raisebox{}[][]{translate}>. This means that the
C<\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 B<reLyX> (like
C<\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 C<\begin{foo}> and C<\end{foo}>
commands will be copied in TeX mode; the text within the environment will be
treated (i.e., translated) by B<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 B<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 C<\begin{reLyXre}> and C<\end{reLyXre}>
statements in the syntax file. (If you have a regular environment which you
won't use very often, you can use the B<-r> option rather than writing a
syntax file.)

=head2 Miscellaneous

You need Perl version 5.002 or later to run B<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>

=head1 DIAGNOSTICS

B<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.
B<reLyX> gives much more information while running if you use the B<-d> option,
but you shouldn't need that unless something goes wrong.

When it's finished, B<reLyX> will tell you if it finished successfully or
died due to some error.

=head1 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.

=head1 FILES

=over 4

=item F<MY_LYXDIR>/layouts/*.layout

User's personal layout files for document classes

=item F<MY_LYXDIR>/reLyX/syntax.default

User's personal syntax file

=item F<LIBDIR>/layouts/*.layout

System-wide layout files for document classes

=item F<LIBDIR>/reLyX/syntax.default

System-wide LaTeX syntax file

=back


F<LIBDIR> is the system-wide LyX directory, usually something like
/usr/local/share/lyx/. F<MY_LYXDIR> is your personal LyX directory, something
like .lyx/ in your home directory.

=head1 SEE ALSO

lyx(1), latex(1)

=head1 AUTHORS

Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)

Code contributors:

=over 4

=item *

John Weiss wrote the original CleanTeX pass.

=item *

Etienne Grossmann

=item *

JosE<eacute> AbE<iacute>lio Oliveira Matos

=item *

David Suarez de Lis

=item *

Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx

=back

Other contributors:

=over 4

=item *

Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug
reports, advice, and feature suggestions.

=item *

Asger K. Alstrup Nielsen and Marc Pavese provided advice.

=item *

Various members of the LyX developers' and users' lists provided bug reports
and feature suggestions.

=back

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