3 B<reLyX> - translate well-behaved LaTeX into LyX
7 The simplest way to use B<reLyX> is via the File->Import command in LyX. (This
8 option is available starting with version 1.0.0.) That runs B<reLyX> on
9 the given file and loads the resulting file into LyX. You should try that
10 first, and call it from the command line only if you need to use more
13 B<reLyX> [ B<-c> I<textclass> ] [ B<-df> ] [ B<-o> I<outputdir> ] [B<-n>]
14 S<[ B<-r> I<renv1>[,I<renv2>...]]> S<[ B<-s> I<sfile1>[,I<sfile2>...]]>
17 B<reLyX> B<-p> B<-c> I<textclass> [ B<-df> ] [ B<-o> I<outputdir> ]
18 S<[ B<-r> I<renv1>[,I<renv2>...]]> S<[ B<-s> I<sfile1>[,I<sfile2>...]]>
29 Class. By default, when B<reLyX> sees a C<\documentclass{foo}> command, it
30 creates a file of textclass "foo" and reads the LyX layout file for that class
31 (something like /usr/local/share/lyx/layouts/foo.layout OR
32 B<HOME>/.lyx/layouts/foo.layout). Use B<-c> to declare a different textclass
33 (and read a different layout file).
37 Debug. By default, B<reLyX> gives sparse output and deletes the temporary files
38 which were created during translation. Using the B<-d> flag will create much
39 more output (both to stdout and stderr) and leave the temporary files around.
43 Force. B<reLyX> will not run if the .lyx file it would generate already exists
44 Use the B<-f> option (carefully) to clobber any existing files.
48 Help. Print out usage information and quit.
52 Noweb. Translate a noweb (aka literate programming) file. This should be
53 (almost?) equivalent to running "noweb2lyx foo.tex foo.lyx". This option
54 requires the B<-c> option.
58 Output directory. With this option, all temporary files and LyX output files
59 (for the given input file, for any included files, or for any file fragments
60 given with the B<-p> option) will be put into I<outputdir>. Otherwise, for
61 each file F<dir/foo.tex>, the temporary files and the LyX output file will be
62 created in F<dir>. This can be useful if a file includes files from other
63 directories which you want to consolidate in one directory, or if you don't
64 have write permission on the directory the LaTeX files are in.
68 Partial file. The input files are LaTeX fragments, with no preamble matter or
69 C<\begin{document}> commands. This option requires the B<-c> option, since there
70 are no C<\documentclass> commands in the files B<reLyX> is translating. When
71 using this option, you can translate more than one file, as long as all files
72 are the same class. The LyX file created by B<reLyX> can be included in an
73 existing LyX file using the "Include LyX File" command from LyX's Insert menu.
77 Regular environments (see L<"Syntax Files">). If you give more than one
78 environment, separate them with commas (not spaces). You'll probably need to
79 quote the environment list, especially if it has asterisk environments (foo*)
80 in it. If you use this command often, considering creating a personal syntax
85 Syntax files. Input (one or more quoted, comma-separated) syntax files to read
86 in addition to the default. (see L<"Syntax Files"> for details).
94 B<reLyX> will create a LyX file F<dir/foo.lyx> from the LaTeX file
95 F<dir/foo.tex> (unless the B<-o> option is used).
97 Suffixes .tex, .ltx and .latex are supported. If F<inputfile>
98 does not exist and does not have one of these suffixes, B<reLyX> will try to
99 translate F<inputfile.tex>. (This is similar to the behavior of LaTeX.)
101 The purpose of B<reLyX> is to translate I<well-behaved> LaTeX2e into LyX. If
102 your LaTeX file doesn't compile---or if you do weird things, like redefining
103 standard LaTex commands---it may choke. LaTeX209 will often be translated
104 correctly, but it's not guaranteed.
106 B<reLyX> has some bugs and lacks a few features. However, its main goals are:
112 Get through a well-behaved LaTeX2e file without crashing
116 Translate a lot of that file.
120 Localize the parts that can't be translated and copy them in TeX mode
124 It achieves these main goals pretty well on most files.
126 There are many improvements that can and will be made to B<reLyX> in the
127 future. However, we wanted to get B<reLyX> out there early on, to make
128 it easier for new LyX users to read in their existing LaTeX files.
132 Here's a more lengthy description of what you should do to translate a LaTeX
141 B<reLyX> will inform you of its progress and give any warnings to stderr, so if
142 you don't want any output at all, try (in csh) 'reLyX foo.tex >& /dev/null'.
143 You should NOT redirect standard output to F<foo.lyx>.
147 Run LyX (version 0.12 or 1.0 or later) on the resulting .lyx file.
149 In theory, most of the file will have been translated, and anything that's
150 untranslatable will be highlighted in red (TeX mode). In theory, LyX will be
151 able to read in the file, and to create printed documents from it, because all
152 that untranslated red stuff will be passed directly back to LaTeX, which LyX
153 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
154 B<reLyX> crashes, or LyX cannot read the generated LyX file, see L</BUGS>,
159 Change things that are highlighted in red (TeX mode) by hand in LyX.
161 As mentioned above, you should be able to print out the LyX file even without
162 doing this. However, changing a command in TeX mode to the corresponding LyX
163 object will allow you to take advantage of LyX's WYSIWYM editing.
165 B<reLyX> is not guaranteed to create a LyX file which generates exactly the same
166 output as the LaTeX file, but it should come close. B<relyX> will generally err
167 on the side of translating less to ensure that dvi or ps files are accurate,
168 even though this leads to more "evil red text" and less WYSIWYM.
172 PROOFREAD THE DOCUMENT!!
174 I'm sure you were planning on doing this anyway, but it's particularly
175 important after translating a LaTeX document. B<reLyX> is, at least now, better
176 at "macro-translating" (translating the whole document) than
177 "micro-translating" (translating every little detail). For example, you may see
178 extra spaces or deleted spaces. Space handling has improved, but it's
183 =head2 What reLyX Can Handle
185 B<reLyX> understands many LaTeX commands. It will translate:
191 regular text, including mini-commands like ~, '', C<\@>, C<\TeX>, as well as
192 accented characters like C<\'{a}>, and the special cases ?` and !`
196 title commands like C<\author>, C<\date>, C<\title>, C<\thanks> and the
201 heading commands like C<\section> including starred commands (C<\section*>)
205 Environments: quote, quotation, and verse; center, flushright, and flushleft
209 itemize, enumerate, and description environments, and their C<\item> commands.
210 Also, well-behaved nested lists
214 cross-referencing commands: C<\ref>, C<\pageref>, C<\label>, and C<\cite>
218 C<\footnote> and C<\margin>
222 font-changing commands including C<\em>, C<\emph>, C<\textit>, and
223 corresponding commands to change family, size, series, and shape
227 C<\input{foo}> (or C<\input{foo.blah}>) and C<\include{foo}>. Plain TeX
228 C<\input> command "C<\input foo.tex>" is also supported.
232 tabular environment, and commands that go inside it like C<\hline>, C<\cline>,
233 and C<\multicolumn> (but see below)
237 float environments table and table*, as well as C<\caption> commands within
242 float environments figure and figure*, as well as graphics inclusion commands
243 \epsf, \epsffile, \epsfbox, \epsfxsize, \epsfig, \psfig, and \includegraphics.
244 Both the graphics and graphicx forms of \includegraphics are supported.
245 Note, however, that many figures will not be translatable into LyX. See
246 the section on "What LyX Can't Handle" below.
250 thebibliography environment and C<\bibitem> command, as well as BibTeX's
251 C<\bibliography> and C<\bibliographystyle> commands
255 miscellaneous commands: C<\hfill>, C<\>C<\>, C<\noindent>, C<\ldots>...
259 documentclass-specific environments (and some commands) which can be
260 translated to LyX layouts
264 arguments to certain untranslatable commands (e.g. C<\mbox>)
268 Some of this support may not be 100% yet. See below for details
270 B<reLyX> copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
271 in LaTeX math, so (almost) any math which is supported by LyX should work just
272 fine. A few math commands which are not supported by LyX will be replaced with
273 their equivalents, e.g., C<\to> is converted to C<\rightarrow>. See
274 L<"Syntax Files"> for more details.
276 B<reLyX> will also copy any preamble commands (i.e., anything before
277 C<\begin{document}>) verbatim, so fancy stuff you've got in your preamble
278 should be conserved in dvi and printed documents, although it will not of
279 course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.
281 =head2 What reLyX Can't Handle --- But it's OK
295 spacing commands (C<\vspace>, C<\pagebreak>, C<\par>, ...)
299 C<\centering>, C<\raggedleft>, C<\raggedright>
303 C<\verb> and verbatim environment. B<reLyX> is careful to copy I<exactly> in
304 this case, including comments and whitespace.
308 some unknown (e.g., user-defined) environments and commands
312 B<reLyX> copies unknown commands, along with their arguments, verbatim into the
313 LyX file. Also, if it sees a C<\begin{foo}> where it doesn't recognize the
314 "foo" environment, it will copy verbatim until it sees C<\end{foo}> (unless
315 you use the B<-r> option). Hopefully, then, most of these unknown commands
316 won't cause B<reLyX> to break; they'll merely require you to do some editing
317 once you've loaded the file up in LyX. That should be less painful than
318 editing either the .tex or the .lyx file using a text editor.
320 =head2 What reLyX Handles Badly --- aka BUGS
322 Since B<reLyX> is relatively new, it's got a number of problems. As it
323 matures, these bugs will be squished.
325 If B<reLyX> is choking on something, or LyX can't read it after B<reLyX>
326 translates it, the best thing to do is to put C<\begin{reLyXskip}> before the
327 offending text, and C<\end{reLyXskip}> after it. I call this a "skip" block.
328 B<reLyX> will copy this block exactly, in TeX mode. Then edit the resulting
329 LyX file, and translate the unknown stuff by hand. The reLyXskip environment
330 is magical; the C<\begin> and C<\end> commands will not be put into the LyX
337 "Exact" copying of unknown environments and commands isn't quite exact.
338 Specifically, newlines and comments may be lost. This will yield ugly LyX, but
339 in almost all cases the output will be the same. However, certain parts of the
340 file will be copied perfectly, including whitespace and comments. This
341 includes: the LaTeX preamble, verbatim environments and C<\verb> commands, and
346 B<reLyX> translates only a few options to the C<\documentclass> command.
347 (Specifically 1[012]pt, [letter|legal|executive|a4|a5|b5]paper,
348 [one|two]side, landscape, and [one|two]column.) Other options are placed in
349 the "options" field in the Layout->Document popup.
351 More importantly, B<reLyX> doesn't translate C<\usepackage> commands, margin
352 commands, C<\newcommands>, or, in fact, anything else from the preamble. It
353 simply copies them into the LaTeX preamble. If you have margin commands in
354 your preamble, then the LyX file will generate the right margins. However,
355 these margins will override any margins you set in the LyX Layout->Paper
356 popup. So you should remove the options from the preamble
357 (Layout->Latex Preamble) to be safe. The same goes for setting your language
358 with babel, C<\inputencoding>, C<\pagestyle>, etc.
362 The foil class has a couple bugs. B<reLyX> may do weird things with optional
363 arguments to C<\foilhead> commands. Also, it may handle C<\begin{dinglist}>
364 incorrectly (although the stuff in the environment should translate normally).
368 Less significant bugs can be found in the F<BUGS> file.
370 B<reLyX> is hopefully rather robust. As mentioned above, it may not translate
371 your file perfectly, but it shouldn't crash. If it does crash---and the
372 problem is not one of those mentioned above or in the F<BUGS> file---see
375 =head2 What LyX Can't Handle
377 LyX itself is missing a couple features, such that even if B<reLyX> translates
378 things perfectly, LyX may still have trouble reading it. If you really need
379 these features, you can export your final document as LaTeX, and put them
380 back in. See F<BUGS> for more details on these bugs.
386 For a number of commands, LyX does not support the optional argument. Examples
387 include C<\chapter> (and other sectioning commands), and C<\\>.
388 B<reLyX> will automatically discard the optional arguments with a warning to
389 stdout. LyX also ignores the width argument for the thebibliography
394 Centering (or right or left justifying) works on full paragraphs.
398 LyX support for tables isn't perfect. For complicated tables, use a "skip"
399 block, so that they will be copied in TeX mode.
403 The LyX math editor can't handle the AMS-LaTeX math environments align, split,
404 etc. So those environments will be copied in TeX mode. You can change
405 equation* environments to the exactly equivalent displaymath, and then they
406 will be translated correctly.
410 Lyx does not support clipping or bounding boxes for included graphics files.
411 Therefore, many graphics inclusion commands will be untranslatable, and
412 copied in TeX mode. In certain cases, you might be able to translate the
413 command by hand within LyX---for example, if you included a bounding box but
414 the bounding box is already in the .eps file.
416 LyX only allows figures to have sizes in in,cm, or percentages of \textwidth
417 or \textheight (or \columnwidth). B<reLyX> will translate from other units, like
418 pt or mm, but it cannot translate other lengths (e.g. if you wanted to scale a
419 figure to size \topmargin for some reason). B<reLyX> will copy figures with
420 untranslatable sizes in TeX mode. Again, you might be able to fix that within
425 =head2 The Future of reLyX
427 In the future, more commands and environments will be supported by B<reLyX>.
428 Bugs will be eradicated.
430 See the TODO file for details.
434 reLyX B<-df> B<-o> "my/dir" B<-r> "myenv" foo.tex > foo.debug
436 The above will create a file my/dir/foo.lyx from foo.tex, overwriting if
437 necessary. When it finds a C<\begin{myenv} ... \end{myenv}> block, it will
438 translate the stuff within the block, but copy the C<\begin> and C<\end>
439 commands in TeX mode. Finally, I'm going to keep the temporary files around
440 (they will also be in my/dir/) and output lots of debugging information into
443 reLyX B<-n> B<-c> "literate-article" foo.tex
445 The above will change a noweb document into a LyX literate-article
446 document. A user would do this if the noweb document had documentclass
453 If B<reLyX> is crashing or otherwise acting strangely---in ways
454 other than those described in L<"BUGS"> or the F<BUGS> file---then please run
455 B<reLyX -d>. That will allow you to figure out where in the reLyXing process
456 it crashed. That, in turn, will allow you to write a better bug report, which
457 will allow the developers to fix it more quickly and easily.
459 Bug reports should be sent to the LyX developers' mailing list. Its address
460 is currently lyx-devel@lists.lyx.org, but you can check the LyX home page,
461 http://www.lyx.org if that bounces. If you are running B<reLyX> on a huge file,
462 please do not send all of the output in your bug report. Just include the last
463 ten or twenty lines of output, along with the piece of the LaTeX file it
464 crashed on. Or, even better, attach a small but complete file which causes
465 the same problem as your original file.
467 =head2 Implementation Details:
469 B<reLyX> makes several "passes" in order to translate a TeX file. On each pass,
470 it creates one or two files.
476 Before doing anything, read the syntax file (or files).
480 Split preamble (anything before a C<\begin{document}> command) off the rest
481 of the file. It saves the two pieces in separate files. This is necessary
482 because there may be very strange stuff in a preamble. It also ignores
483 anything after the C<\end{document}>, on the assumption that it isn't LaTeX.
487 Translate the preamble. Currently, that just means translating the
488 C<\documentclass> command and copying the rest exactly into the LyX preamble.
490 Once you know what class the document is, read the LyX layout file for that
495 "Clean" the TeX file, generating slightly stricter LaTeX. This includes:
501 Change, e.g., x^2 to the equivalent but clearer x^{2}
505 Removing optional arguments that LyX can't handle (e.g., from C<\chapter>)
509 Changing C<{\em foo}> to C<\emph{foo}>, etc. This is necessary because LyX
510 always writes out the non-local forms anyway. This should very rarely make a
517 Translate LaTeX text, commands, and environments to LyX.
521 Put the two pieces back together, and do some final tweaking, to generate the
526 If there are any C<\input> or C<\include> commands, B<reLyX> will loop back to
527 the beginning and translate those. It assumes that the included files are the
528 same class as the main file, and that they have no preamble matter. (If you
529 have an C<\input> command in the preamble of a file, the command will be
530 copied exactly into the LaTeX preamble portion of the LyX file, so the
531 included file won't be translated.) So when translating included files, it
532 skips passes 0 and 1.
534 If B<reLyX> doesn't find a file you wanted to include, it will give a warning,
535 but will continue to translate any files it does find.
539 B<reLyX> reads a LyX layout file to know how to handle LaTeX environments and
540 commands which get translated to LyX layouts. This file will include all
541 "normal" non-math environments (i.e., including quote and itemize, but not
542 tabular, minipage, and some other fancy environments), and commands like
543 C<\section> and C<\title>. If you want to reLyX a class that doesn't have an
544 existing layout file, then you'll have to create a layout file. But you have
545 to do this anyway, in order to LyX the file, since LyX depends on layout files
546 to know how to display and process its files. Check the LyX documentation for
547 help with this task (which can be hard or easy, depending on the class you
548 want to create a layout file for.) If your class is quite similar to a class
549 that has a layout file, then consider using the B<-c> option.
553 B<reLyX> always reads at least one syntax file, called the default syntax file.
554 B<reLyX> will read your personal syntax file if it exists; otherwise it will
555 read the system-wide file. B<reLyX> will read additional syntax files if you
556 specify them with the B<-s> option. (These extra files should have the same
557 format as the default file, but will tend to be shorter, since they only have
558 to specify extra commands not found in the default file.) A syntax file tells
559 B<reLyX> a few things.
561 First, it describes the syntax of each command, that is, how many required
562 arguments and how many optional arguments the command takes. Knowing this
563 makes it easier for B<reLyX> to copy (in TeX mode) commands that it doesn't
564 know how to translate. The syntax file simply has a command, followed by
565 braces or brackets describing its arguments in the correct order. For example,
566 a syntax file entry C<\bibitem[]{}> means that the C<\bibitem> command takes
567 an optional argument followed by a required one, while the entry C<\bf>
568 means that the C<\bf> command takes no arguments at all. When B<reLyX>
569 encounters a token that it doesn't know how to translate into LyX, it will
570 copy the token---along with the correct number of arguments---exactly. If the
571 token is not in the syntax file, then B<reLyX> just copies as many arguments
572 as it finds. This means that it may copy too much. But since the user can
573 specify additional syntax files, that shouldn't happen often.
575 Some commands that cannot be translated to LyX, like C<\mbox>, have as one of
576 their arguments regular LaTeX text. If the string "translate" is put into an
577 argument of an (untranslatable) command in the syntax file, then B<reLyX> will
578 translate that argument instead of copying it verbatim. So, for example, the
579 default syntax file has C<\raisebox{}[][]{translate}>. This means that the
580 C<\raisebox> command and the first argument (and optional arguments if they
581 exist) are copied in TeX mode, but the last argument (which may contain math,
582 complicated LaTeX, other untranslatable commands, etc.) will be translated
583 into LyX. You can't use "translate" on optional arguments.
585 User-defined syntax files are allowed to define new commands and
586 their syntax, or override the number of arguments for a command given in the
587 default syntax file. (E.g., if you're using a style that gives an extra
588 argument to some command...) However, this will only be useful for commands
589 copied in TeX mode. Commands which are actually translated by B<reLyX> (like
590 C<\item>) have their argument syntax hard-coded. The hard-coded commands are
591 identified in the default syntax file.
593 Second, the syntax file describes any "regular environments". Usually, an
594 entire unknown environment will be copied in TeX mode. If you define a regular
595 environment "foo", though, then only the C<\begin{foo}> and C<\end{foo}>
596 commands will be copied in TeX mode; the text within the environment will be
597 treated (i.e., translated) by B<reLyX> as regular LaTeX, rather than being
598 copied into TeX mode. Don't try to declare "tabbing" and "picture" as regular
599 environments, as the text within those environments will confuse B<reLyX>; use
600 this capability for new environments you create that have plain text or math
601 or simple commands in them. You also can't declare unknown math environments
602 (like equation*) as regular environments, either, since the LyX math editor
603 won't understand them. The names of regular environments appear,
604 whitespace-separated, between C<\begin{reLyXre}> and C<\end{reLyXre}>
605 statements in the syntax file. (If you have a regular environment which you
606 won't use very often, you can use the B<-r> option rather than writing a
609 Third, the syntax file describes a math translation table. The LyX math editor
610 doesn't support a few commands. For example, C<_> is supported, but the
611 equivalent C<\sb> is not. Put any commands you'd like translate between
612 C<\begin{reLyXmt}> and C<\end{reLyXmt}> statements. The statement
613 "C<\| {\Vert}>" means that any C<\|> in math mode will be converted to
614 "C<\Vert >" (in cases where a token made up of a backslash and a non-letter is
615 translated to something with letters at the end, a space is added by B<reLyX>.
616 That way, "C<\|a>" is correctly translated to "C<\Vert a>").
620 You need Perl version 5.002 or later to run B<reLyX>. <plug> If you don't have
621 Perl, you should get it anyway (at http://www.perl.com), because it's a really
622 useful tool for pretty much anything. </plug>
626 B<reLyX> should always explain why it crashes, if it crashes. Some diagnostics
627 may be very technical, though, if they come from the guts of the code.
628 B<reLyX> gives much more information while running if you use the B<-d> option,
629 but you shouldn't need that unless something goes wrong.
631 When it's finished, B<reLyX> will tell you if it finished successfully or
632 died due to some error.
636 Always keep a copy of your original LaTeX files either under a different
637 name or in a different directory. There are a couple ways in which using LyX
638 could lead to overwriting the original LaTeX file.
640 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
641 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
642 you if you want to overwrite it.)
644 If you have the \use_tempdir variable set to false in your lyxrc, then LyX
645 will create its temporary files in your current directory, which means your
646 LaTeX original may be overwritten (without a warning from LyX) when you "view
647 dvi" or print the LyX document.
653 =item F<MY_LYXDIR>/layouts/*.layout
655 User's personal layout files for document classes
657 =item F<MY_LYXDIR>/reLyX/syntax.default
659 User's personal syntax file
661 =item F<LIBDIR>/layouts/*.layout
663 System-wide layout files for document classes
665 =item F<LIBDIR>/reLyX/syntax.default
667 System-wide LaTeX syntax file
672 F<LIBDIR> is the system-wide LyX directory, usually something like
673 /usr/local/share/lyx/. F<MY_LYXDIR> is your personal LyX directory, something
674 like .lyx/ in your home directory.
682 Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
690 John Weiss wrote the original CleanTeX pass.
698 JosE<eacute> AbE<iacute>lio Oliveira Matos
706 Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx
716 Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug
717 reports, advice, and feature suggestions.
721 Asger K. Alstrup Nielsen and Marc Pavese provided advice.
725 Various members of the LyX developers' and users' lists provided bug reports
726 and feature suggestions.
730 B<reLyX> uses a modified version the Perl TeX parser Text::TeX package written
731 by Ilya Zakharevich (ilya@math.ohio-state.edu), available on CPAN.