anne/lyx_mirror
1
0
Fork 0
mirror of https://git.lyx.org/repos/lyx.git synced 2024-11-09 18:31:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

* update tex2lyx man page, mostly done bei Uwe (bug 2770).

Browse Source 
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@25929 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Jürgen Spitzmüller 2008-07-28 07:52:27 +00:00
parent 523a077704
commit 63ca4f8caa
1 changed files with 60 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
src/tex2lyx/tex2lyx.man
View File

@ -193,7 +193,7 @@
.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.
@ -263,7 +263,7 @@ 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.
.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
@ -272,10 +272,6 @@ Translate a lot of that file.
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.
@ -289,27 +285,27 @@ You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
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
@ -349,8 +345,6 @@ them
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
@ -366,31 +360,29 @@ Some of this support may not be 100% yet. See below for details
.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.
@ -400,41 +392,40 @@ matures, these bugs will be squished.
.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.
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 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.
\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
@ -446,40 +437,26 @@ For a number of commands (such as \f(CW\e\e\fR), LyX does not support the option
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
@ -496,10 +473,10 @@ other than those described in the section on \fI\s-1BUGS\s0\fR or on
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.
@ -630,10 +607,11 @@ 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.)
.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