TEX2LYX(1)tex2lyx 2.1.4 TEX2LYX(1)NAMEtex2lyx - 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 ] [ -f ] [ -n ] [
-c textclass ] [ -e encoding ] [ -fixedenc encoding ] [ -m mod‐
ule1[,module2...]] [ -s sfile1[,sfile2...]] [ -skipchildren ] [
-roundtrip ] [ -copyfiles ] inputfile [ outputfile ]
OPTIONS-c Class. By default, when tex2lyx sees a \documentclass{foo} com‐
mand, 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/lay‐
outs/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.
-m Module. Load the given modules. This is useful if tex2lyx does
not automatically detect a given module, but you know the mod‐
ules that provide some commands or environments that are used in
the imported file. The modules are loaded in the given order. If
a module foo depends on a module bar, bar must be given before
foo.
-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.
-e Specify the default encoding using the LaTeX name as defined in
the encodings file. tex2lyx will use this encoding, but switch
if it finds any encoding changing commands in the input.
-fixedenc
Specify the encoding using the LaTeX name as defined in the
encodings file. tex2lyx will ignore any encoding changing com‐
mands in the input.
-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.
-skipchildren
Do not translate child documents included via \include and
\input. This option is useful if the child documents are gener‐
ated files and/or contain many commands that tex2lyx does not
understand yet.
-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. If the
output file name is not given it is 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.
-copyfiles
Copy all included files tex2lyx is aware of to the output direc‐
tory if the output file is located in a different directory than
the input file. This is useful if you want to ensure that no
included file is overwritten (either in roundtrip mode or by a
later export from LyX). Please note that the resulting document
may be uncompilable. This happens if it needs files that tex2lyx
does not know about and therefore does not copy to the output
directory.
-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 particu‐
larly important after translating a LaTeX document. tex2lyx is bet‐
ter 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 (\sec‐
tion*)
· 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 corre‐
sponding 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 inclu‐
sion 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 Bib‐
TeX'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 Pre‐
amble 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 rec‐
ognize the “foo” environment, it will copy verbatim until it sees
\end{foo} (unless you use the -r option). Most of these unknown com‐
mands 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 out‐
put 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 com‐
mands, 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 com‐
mands, 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 set‐
tings 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 men‐
tioned 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, \tex‐
theight, \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.
EXAMPLEStex2lyx-f -r “myenv” foo.tex
The above will create a file foo.lyx from foo.tex, overwriting if nec‐
essary. When it finds a \begin{myenv} ... \end{myenv} block, it will
translate the stuff within the block, but copy the \begin and \end com‐
mands in TeX mode.
tex2lyx-n -c “literate-article” foo.tex
The above will change a noweb document into a LyX literate-article doc‐
ument. 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 com‐
plete file which causes the same problem as your original file.
Layout Files
tex2lyx reads a LyX layout file to know how to handle LaTeX environ‐
ments 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 syn‐
tax file. tex2lyx will read your personal syntax file if it exists;
otherwise it will read the system-wide file. tex2lyx will read addi‐
tional 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 verba‐
tim. So, for example, the default syntax file has \raise‐
box{}[][]{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 com‐
mands 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 equa‐
tion*) 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 differ‐
ent 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_21x
can be used to specify which system directory to use.
The system directory is determined by searching for the file "chkcon‐
fig.ltx". Directories are searched in this order:
1) -sysdir command line parameter
2) LYX_DIR_21x 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/local/share/lyx)
LYX_USERDIR_21x
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_21x 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 per‐
sonal 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
MY_LYXDIR/encodings
User's personal encoding definition file
LIBDIR/layouts/*.layout
System-wide layout files for document classes
LIBDIR/lib/syntax.default
System-wide LaTeX syntax file
LIBDIR/lib/encodings
System-wide encoding definition file
SEE ALSOlyx(1), latex(1)AUTHORStex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-
devel@lists.lyx.org)
Version 2.1.4 2015-07-24 TEX2LYX(1)
