.SH "NAME"
\fBtex2lyx\fR \- translate well-behaved LaTeX into LyX
.SH "SYNOPSIS"
-The simplest way to use \fBtex2lyx\fR is via the File->Import command
+The simplest way to use \fBtex2lyx\fR is via the File->Import->LaTeX (plain) menu item
in LyX. That runs \fBtex2lyx\fR 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.
standard LaTeX commands---it may choke. LaTeX209 will often be translated
correctly, but it's not guaranteed.
.PP
-\fBtex2lyx\fR has some bugs and lacks a few features. However, its main goals are:
+\fBtex2lyx\fR lacks a few features. However, its main goals are:
.Ip "\(bu" 4
Get through a well-behaved LaTeX2e file without crashing
.Ip "\(bu" 4
Localize the parts that can't be translated and copy them in TeX mode
.PP
It achieves these main goals pretty well on most files.
-.PP
-There are many improvements that can and will be made to \fBtex2lyx\fR in the
-future. However, we wanted to get \fBtex2lyx\fR out there early on, to make
-it easier for new LyX users to read in their existing LaTeX files.
.Sh "Usage"
Here's a more lengthy description of what you should do to translate a LaTeX
document into LyX.
Run LyX (version 1.4 or later) on the resulting .lyx file.
.Sp
In theory, most of the file will have been translated, and anything that's
-untranslatable will be transferred to TeX mode (ERT in LyX-speak). In theory, LyX will be
+untranslatable will be transferred to TeX code (ERT in LyX-speak). In theory, LyX will be
able to read in the file, and to create printed documents from it, because all
that untranslated ERT stuff will be passed directly back to LaTeX, which LyX
uses as a backend. Unfortunately, reality doesn't always reflect theory. If
-\fBtex2lyx\fR crashes, or LyX cannot read the generated LyX file, see the \f(CWBUGS\fR entry elsewhere in this document or the \fI\s-1BUGS\s0\fR file.
+\fBtex2lyx\fR crashes, or LyX cannot read the generated LyX file, see the \f(CWBUGS\fR section below.
.Ip "\(bu" 4
-Change things that are highlighted in ERT (TeX mode) by hand in LyX.
+Transform things have been inserted as TeX code manually to LyX features, if possible.
.Sp
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
+doing this. However, changing a command in TeX code to the corresponding LyX
object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
.Sp
\fBtex2lyx\fR is not guaranteed to create a LyX file which generates exactly the same
-output as the LaTeX file, but it should come close. \fBtex2lyx\fR will generally err
-on the side of translating less to ensure that dvi or ps files are accurate,
-even though this leads to more \*(L"evil red text\*(R" and less \s-1WYSIWYM\s0.
+output as the LaTeX file, although its goal is to achieve this. \fBtex2lyx\fR will generally err
+on the side of translating less to ensure that the resulting output files are accurate,
+even though this leads to more TeX code and less \s-1WYSIWYM\s0.
.Ip "\(bu" 4
\s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
.Sp
I'm sure you were planning on doing this anyway, but it's particularly
-important after translating a LaTeX document. \fBtex2lyx\fR is, at least now, better
+important after translating a LaTeX document. \fBtex2lyx\fR is better
at \*(L"macro-translating\*(R" (translating the whole document) than
\*(L"micro-translating\*(R" (translating every little detail). For example, you may see
extra spaces or deleted spaces. Space handling has improved, but it's
float environments figure and figure*, as well as graphics inclusion commands
\eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
Both the graphics and graphicx forms of \eincludegraphics are supported.
-Note, however, that many figures will not be translatable into LyX. See
-the section on \*(L"What LyX Can't Handle\*(R" below.
.Ip "\(bu" 4
thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
\f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
.PP
\fBtex2lyx\fR 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., \f(CW\eto\fR is converted to \f(CW\erightarrow\fR. See
-the section on \fISyntax Files\fR for more details.
+fine.
.PP
-\fBtex2lyx\fR will also copy any preamble commands (i.e., anything before
-\f(CW\ebegin{document}\fR) 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.
+\fBtex2lyx\fR will copy any preamble commands (i.e., anything before
+\f(CW\ebegin{document}\fR) verbatim. Fancy stuff you've got in your preamble
+should thus be conserved in printed documents, although it will not of
+course show up in the LyX window. Check Document->Settings->LaTeX Preamble to see the result.
.Sh "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
.Ip "\(bu" 4
tabular* tables
.Ip "\(bu" 4
-spacing commands (\f(CW\evspace\fR, \f(CW\epagebreak\fR, \f(CW\epar\fR, ...)
+some spacing commands (\f(CW\ehspace\fR, \f(CW\epagebreak\fR and \f(CW\elinebreak\fR)
.Ip "\(bu" 4
\f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
.Ip "\(bu" 4
\f(CW\everb\fR and verbatim environment. \fBtex2lyx\fR is careful to copy \fIexactly\fR in
this case, including comments and whitespace.
.Ip "\(bu" 4
-some unknown (e.g., user-defined) environments and commands
+unknown (e.g., user-defined) environments and commands
.PP
\fBtex2lyx\fR copies unknown commands, along with their arguments, verbatim into the
LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
\*(L"foo\*(R" environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
-you use the \fB\-r\fR option). Hopefully, then, most of these unknown commands
+you use the \fB\-r\fR option). Most of these unknown commands
won't cause \fBtex2lyx\fR 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.
.PP
.Ip "\(bu" 4
\*(L"Exact\*(R" 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 \f(CW\everb\fR commands, and
-skip blocks.
-.Ip "\(bu" 4
-\fBtex2lyx\fR translates only a few options to the \f(CW\edocumentclass\fR 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 \*(L"options\*(R" field in the Layout->Document popup.
+This will yield ugly LyX, but in almost all cases the output will be the same.
+However, most parts of the file will be copied perfectly, including whitespace
+and comments. This includes: the LaTeX preamble, verbatim environments as well as
+\f(CW\everb\fR commands, and skip blocks.
+.Ip "\(bu" 4
+\fBtex2lyx\fR translates only a subset of the document class options to native features.
+Other options are placed in the \*(L"options\*(R" field in the Document->Settings popup.
.Sp
-More importantly, \fBtex2lyx\fR doesn't translate \f(CW\eusepackage\fR commands, margin
-commands, \f(CW\enewcommands\fR, 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 \f(CW\einputencoding\fR,
-\f(CW\epagestyle\fR, etc.
+More importantly, \fBtex2lyx\fR doesn't translate \f(CW\enewcommands\fR, unknown
+\f(CW\eusepackage\fR commands and other unknown code in the preamble. It
+simply copies that into the LaTeX preamble. If you use special commands, e.g. to
+specify the text layout in a way that that is not understood by LyX, tex2lyx won't
+recognize it. Note that these settings will be overwritten if you modify the text
+layout in LyX's document settings. Better remove these special options from the LaTeX
+preamble (Document->Settings->LaTeX Preamble) and use the corresponding LyX document
+settings, if possible.
.Ip "\(bu" 4
\fBtex2lyx\fR doesn't handle unicode yet. So if you have an utf8-encoded tex file, some
characters might not be (well) supported. Also, the output format of \fBtex2lyx\fR
-is that of LyX 1.4 until unicode support is implemented. Thus, newer features cannot be
-supported natively.
+remains that of LyX 1.4 until unicode support is implemented. This disallows us from
+supporting newer features natively, which is in fact the most severe issue in current
+\fBtex2lyx\fR.
.Ip "\(bu" 4
-The foil class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
+The foil document class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
incorrectly (although the stuff in the environment should translate normally).
.PP
-Less significant bugs can be found on \fI\s-1http://bugzilla.lyx.org\s0\fR.
+All known bugs of \fBtex2lyx\fR can be found on \fI\s-1http://bugzilla.lyx.org\s0\fR.
.PP
-\fBtex2lyx\fR 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 on \fI\s-1http://bugzilla.lyx.org\s0\fR---see
-the section on \fIBug Reports\fR.
+\fBtex2lyx\fR is rather robust. As mentioned above, it may not translate
+your file perfectly, but the result should be usable and it shouldn't crash. If you encounter
+problems---and the problem is not one of those mentioned above or on
+\fI\s-1http://bugzilla.lyx.org\s0\fR---please report the issue as described in the section
+on \fIBug Reports\fR.
.Sh "What LyX Can't Handle"
LyX itself is missing a couple of features, such that even if \fBtex2lyx\fR translates
things perfectly, LyX may still have trouble reading it. If you really need
stdout. LyX also ignores the width argument for the thebibliography
environment.
.Ip "\(bu" 4
-Centering (or right or left justifying) works on full paragraphs.
-.Ip "\(bu" 4
LyX support for tables isn't perfect. For complicated tables, use a \*(L"skip\*(R"
block, so that they will be copied in TeX mode.
.Ip "\(bu" 4
-The LyX math editor can't handle the \s-1AMS\s0\-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.
-.Ip "\(bu" 4
-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 allows figures to have sizes in the units known to TeX, such as in, cm, etc. It also
+translates percentages of \etextwidth, \etextheight, \ecolumnwidth, but no other lengths
+(e.g. if you wanted to scale a figure to size \etopmargin for some reason). \fBtex2lyx\fR
+will copy figures with untranslatable sizes in TeX mode. Again, you might be able to fix
+that within LyX.
.Sp
-LyX only allows figures to have sizes in in,cm, or percentages of \etextwidth
-or \etextheight (or \ecolumnwidth). \fBtex2lyx\fR 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 \etopmargin for some reason). \fBtex2lyx\fR will copy figures with
-untranslatable sizes in TeX mode. Again, you might be able to fix that within
-LyX.
.Sh "The Future of tex2lyx"
-In the future, more commands and environments will be supported by \fBtex2lyx\fR.
-Bugs will be eradicated.
-.PP
-See the \s-1TODO\s0 file for details.
+\fBtex2lyx\fR is actively maintained. Commands and environments will be added in the future.
+Bugs will be eradicated. The most important task will be to make \fBtex2lyx\fR unicode
+compliant.
.SH "EXAMPLES"
tex2lyx \fB\-df\fR \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
.PP
The above will create a file foo.lyx from foo.tex, overwriting if
necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
-commands in TeX mode. Finally, I'm going to keep the temporary files around
+commands in TeX mode. Finally, it's going to keep the temporary files around
and output lots of debugging information into the file foo.debug.
.PP
tex2lyx \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
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.
.PP
-Bug reports should either be posted to http://bugzilla.lyx.org or sent to the
-LyX developers\*(R' 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 \fBtex2lyx\fR on a huge file, please do not send all of the output in
+Bugs should be reported to the LyX bug tracker at http://bugzilla.lyx.org. Additionally,
+you can post a message to the LyX developers\*(R' mailing list. Its address is currently
+lyx-devel@lists.lyx.org. If your message bounces, you can check the LyX home page,
+http://www.lyx.org. If you are running \fBtex2lyx\fR 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.
re-export it, note that it will overwrite the original foo.tex. (LyX will ask
you if you want to overwrite it.)
.PP
-If you have the \euse_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 \*(L"view
-dvi\*(R" or print the LyX document.
+If you have the \euse_tempdir variable set to false in your lyxrc (or did not
+have defined a temporary directory path in LyX's preferences, respectively),
+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
+or export the LyX document.
.SH "FILES"
.Ip "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
User's personal layout files for document classes
projects / lyx.git / blobdiff