NAME¶
tex2lyx - translate well-behaved LaTeX into LyX
SYNOPSIS¶
The simplest way to use
tex2lyx is via the File->Import->LaTeX
(plain) menu item in LyX. That runs
tex2lyx 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.
tex2lyx [
-userdir userdir ] [
-systemdir
systemdir ] [
-n ] [
-c textclass ]
[
-s sfile1[,
sfile2...]] [
-roundtrip ]
inputfile [
outputfile ]
OPTIONS¶
- -c
- Class. By default, when tex2lyx 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).
-
- This option is needed if the input file is a LaTeX
fragment, with no preamble matter or \begin{document} command. LyX files
created by tex2lyx from partial files can be included in an
existing LyX file using the “Include LyX File” command from
LyX's Insert menu.
- -f
- Force. tex2lyx will not run if the .lyx file it
would generate already exists. Use the -f option (carefully) to
clobber any existing files.
- -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.
- -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).
- -sysdir
- Specify a system directory. Normally, you shouldn't need
this. Your LyX system directory is chosen. Cf. the section FILES for
details.
- -userdir
- Specify a user directory. Normally, you shouldn't need
this. Your LyX user directory is chosen. Cf. the section FILES for
details.
- -roundtrip
- Call LyX to re-export the created output file to LaTeX. The
output file name is always determined automatically to avoid over-writing
the input file by accident: If the input file is named foo.tex the
output file will be named foo.lyx.lyx, and the re-exported file
will be named foo.lyx.tex.
- -help
- Help. Print out usage information and quit.
- -version
- Print out the version number and build information and
quit.
DESCRIPTION¶
Introduction¶
tex2lyx will create a LyX file with the specified name (or
dir/foo.lyx if no name was given) from the LaTeX file
dir/foo.tex.
Suffixes .tex, .ltx and .latex are supported. If
inputfile does not exist
and does not have one of these suffixes,
tex2lyx will try to translate
inputfile.tex. (This is similar to the behavior of LaTeX.)
The purpose of
tex2lyx 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.
tex2lyx lacks a few features. However, its main goals are:
- •
- Get through a well-behaved LaTeX2e file without
crashing
- •
- Translate a lot of that file.
- •
- Localize the parts that can't be translated and copy them
in TeX mode
It achieves these main goals pretty well on most files.
Usage¶
Here's a more lengthy description of what you should do to translate a LaTeX
document into LyX.
- •
- Run tex2lyx.
-
- tex2lyx 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)
`tex2lyx foo.tex >& /dev/null'. You should NOT redirect standard
output to foo.lyx.
- •
- Run LyX (version 2.1 or later) on the resulting .lyx
file.
-
- In theory, most of the file will have been translated, and
anything that's 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 tex2lyx crashes, or LyX
cannot read the generated LyX file, see the BUGS section below.
- •
- Transform things have been inserted as TeX code manually to
LyX features, if possible.
-
- As mentioned above, you should be able to print out the LyX
file even without doing this. However, changing a command in TeX code to
the corresponding LyX object will allow you to take advantage of LyX's
WYSIWYM editing.
-
- tex2lyx is not guaranteed to create a LyX file which
generates exactly the same output as the LaTeX file, although its goal is
to achieve this. tex2lyx 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 WYSIWYM.
- •
- PROOFREAD THE DOCUMENT!!
-
- I'm sure you were planning on doing this anyway, but it's
particularly important after translating a LaTeX document. tex2lyx
is 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 tex2lyx Can Handle¶
tex2lyx understands many LaTeX commands. It will translate:
- •
- regular text, including mini-commands like ~, `', \@, \TeX,
as well as accented characters like \'{a}, and the special cases ?` and
!`
- •
- title commands like \author, \date, \title, \thanks and the
abstract environment
- •
- heading commands like \section including starred commands
(\section*)
- •
- Environments: quote, quotation, and verse; center,
flushright, and flushleft
- •
- itemize, enumerate, and description environments, and their
\item commands. Also, well-behaved nested lists
- •
- cross-referencing commands: \ref, \pageref, \label, and
\cite
- •
- \footnote and \margin
- •
- font-changing commands including \em, \emph, \textit, and
corresponding commands to change family, size, series, and shape
- •
- \input{foo} (or \input{foo.blah}) and \include{foo}. Plain
TeX \input command “\input foo.tex” is also supported.
- •
- tabular environment, and commands that go inside it like
\hline, \cline, and \multicolumn (but see below)
- •
- float environments table and table*, as well as \caption
commands within them
- •
- 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.
- •
- thebibliography environment and \bibitem command, as well
as BibTeX's \bibliography and \bibliographystyle commands
- •
- miscellaneous commands: \hfill, \\, \noindent,
\ldots...
- •
- documentclass-specific environments (and some commands)
which can be translated to LyX layouts
- •
- arguments to certain untranslatable commands (e.g.
\mbox)
Some of this support may not be 100% yet. See below for details
tex2lyx 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.
tex2lyx will copy any preamble commands (i.e., anything before
\begin{document}) 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.
What tex2lyx Can't Handle --- But it's OK¶
- •
- some spacing commands (\hspace, \pagebreak and
\linebreak)
- •
- \centering, \raggedleft, \raggedright
- •
- \verb and verbatim environment. tex2lyx is careful
to copy exactly in this case, including comments and
whitespace.
- •
- unknown (e.g., user-defined) environments and commands
tex2lyx 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). Most of these unknown
commands won't cause
tex2lyx 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 tex2lyx Handles Badly --- aka BUGS¶
Since
tex2lyx is relatively new, it's got a number of problems. As it
matures, these bugs will be squished.
- •
- “Exact” copying of unknown environments and
commands isn't quite exact. 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 \verb commands, and skip
blocks.
- •
- tex2lyx translates only a subset of the document
class options to native features. Other options are placed in the
“options” field in the Document->Settings popup.
-
- More importantly, tex2lyx doesn't translate
\newcommands, unknown \usepackage 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.
- •
- The foil document class has a couple of bugs.
tex2lyx 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).
All known bugs of
tex2lyx can be found on
http://www.lyx.org/trac/wiki/BugTrackerHome.
tex2lyx 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
http://www.lyx.org/trac/wiki/BugTrackerHome---please report the issue
as described in the section on
Bug Reports.
What LyX Can't Handle¶
LyX itself is missing a couple of features, such that even if
tex2lyx
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.
- •
- For a number of commands (such as \\), LyX does not support
the optional argument. tex2lyx will automatically discard the
optional arguments with a warning to stdout. LyX also ignores the width
argument for the thebibliography environment.
- •
- LyX support for tables isn't perfect. For complicated
tables, use a “skip” block, so that they will be copied in TeX
mode.
- •
- LyX allows figures to have sizes in the units known to TeX,
such as in, cm, etc. It also translates percentages of \textwidth,
\textheight, \columnwidth, but no other lengths (e.g. if you wanted to
scale a figure to size \topmargin for some reason). tex2lyx will
copy figures with untranslatable sizes in TeX mode. Again, you might be
able to fix that within LyX.
EXAMPLES¶
tex2lyx
-f -r “myenv” foo.tex
The above will create a file 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.
tex2lyx
-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¶
Bugs should be reported to the LyX bug tracker at
http://www.lyx.org/trac/wiki/BugTrackerHome. Additionally, you can post a
message to the LyX developers' 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
tex2lyx 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.
Layout Files¶
tex2lyx 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 tex2lyx 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¶
tex2lyx always reads at least one syntax file, called the default syntax
file.
tex2lyx will read your personal syntax file if it exists;
otherwise it will read the system-wide file.
tex2lyx 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
tex2lyx 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
tex2lyx 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
tex2lyx
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
tex2lyx 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
tex2lyx 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
tex2lyx (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
tex2lyx 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
tex2lyx; 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{tex2lyxre} and \end{tex2lyxre} 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.)
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.)
ENVIRONMENT¶
- LYX_DIR_20x
- can be used to specify which system directory to use.
The system directory is determined by searching for the file
"chkconfig.ltx". Directories are searched in this order:
1) -sysdir command line parameter
2) LYX_DIR_20x environment variable
3) Maybe <path of binary>/TOP_SRCDIR/lib
4) <path of binary>/../share/<name of binary>/
5) hardcoded lyx_dir (at build time: /usr/share/lyx)
- LYX_USERDIR_20x
- can be used to specify which user directory to use.
The user directory is, in order of precedence:
1) -userdir command line parameter
2) LYX_USERDIR_20x environment variable
3) $HOME/.<name of binary> if no explicit setting is made
FILES¶
If
LIBDIR is the system-wide LyX directory and
MY_LYXDIR is your
personal LyX directory, then the following files are read by tex2lyx:
- MY_LYXDIR/layouts/*.layout
- User's personal layout files for document classes
- MY_LYXDIR/syntax.default
- User's personal syntax file
- LIBDIR/layouts/*.layout
- System-wide layout files for document classes
- LIBDIR/lib/syntax.default
- System-wide LaTeX syntax file
SEE ALSO¶
lyx(1),
latex(1)
AUTHORS¶
tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)