1TEX2LYX(1)                       tex2lyx 2.3.7                      TEX2LYX(1)
2
3
4

NAME

6       tex2lyx - translate well-behaved LaTeX into LyX
7

SYNOPSIS

9       The  simplest way to use tex2lyx is via the File->Import->LaTeX (plain)
10       menu item in LyX. That runs tex2lyx on the given file and loads the re‐
11       sulting  file into LyX. You should try that first, and call it from the
12       command line only if you need to use more complicated options.
13
14       tex2lyx [ -userdir userdir ] [ -systemdir systemdir ] [ -f ] [ -n  ]  [
15       -c  textclass  ]  [  -e  encoding  ]  [  -fixedenc encoding ] [ -m mod‐
16       ule1[,module2...]]   [ -s sfile1[,sfile2...]]  [  -skipchildren   ]   [
17       -roundtrip ] [ -copyfiles ] inputfile [ outputfile ]
18

OPTIONS

20       -c     Class.  By default, when tex2lyx sees a \documentclass{foo} com‐
21              mand, it creates a file of textclass “foo”  and  reads  the  LyX
22              layout   file   for   that   class   (something   like  /usr/lo‐
23              cal/share/lyx/layouts/foo.layout  OR  HOME/.lyx/layouts/foo.lay‐
24              out).   Use -c to declare a different textclass (and read a dif‐
25              ferent layout file).
26
27              This option is needed if the input file  is  a  LaTeX  fragment,
28              with  no  preamble matter or \begin{document} command. LyX files
29              created by tex2lyx from partial files can be included in an  ex‐
30              isting  LyX file using the “Include LyX File” command from LyX's
31              Insert menu.
32
33       -m     Module. Load the given modules. This is useful if  tex2lyx  does
34              not  automatically  detect a given module, but you know the mod‐
35              ules that provide some commands or environments that are used in
36              the imported file. The modules are loaded in the given order. If
37              a module foo depends on a module bar, bar must be  given  before
38              foo.
39
40       -f     Force.  tex2lyx  will not run if the .lyx file it would generate
41              already exists.  Use the -f option (carefully)  to  clobber  any
42              existing files.
43
44       -e     Specify  the default encoding using the LaTeX name as defined in
45              the encodings file.  tex2lyx will use this encoding, but  switch
46              if it finds any encoding changing commands in the input.
47
48       -fixedenc
49              Specify  the encoding using the LaTeX name as defined in the en‐
50              codings file.  tex2lyx will ignore any  encoding  changing  com‐
51              mands in the input.
52
53       -n     Noweb.  Translate  a noweb (aka literate programming) file. This
54              should be (almost?) equivalent  to  running  “noweb2lyx  foo.tex
55              foo.lyx”. This option requires the -c option.
56
57       -skipchildren
58              Do  not translate child documents included via \include and \in‐
59              put.  This option is useful if the child documents are generated
60              files  and/or contain many commands that tex2lyx does not under‐
61              stand yet.
62
63       -s     Syntax files. Input (one or more quoted, comma-separated) syntax
64              files  to  read  in addition to the default. (see the section on
65              Syntax Files for details).
66
67       -sysdir
68              Specify a system directory. Normally, you shouldn't  need  this.
69              Your  LyX  system directory is chosen. Cf. the section FILES for
70              details.
71
72       -userdir
73              Specify a user directory. Normally,  you  shouldn't  need  this.
74              Your LyX user directory is chosen. Cf. the section FILES for de‐
75              tails.
76
77       -roundtrip
78              Call LyX to re-export the created output file to LaTeX.  If  the
79              output  file name is not given it is determined automatically to
80              avoid over-writing the input file by accident: If the input file
81              is  named foo.tex the output file will be named foo.lyx.lyx, and
82              the re-exported file will be named foo.lyx.tex.
83
84       -copyfiles
85              Copy all included files tex2lyx is aware of to the output direc‐
86              tory if the output file is located in a different directory than
87              the input file. This is useful if you want to ensure that no in‐
88              cluded  file  is  overwritten  (either in roundtrip mode or by a
89              later export from LyX). Please note that the resulting  document
90              may be uncompilable. This happens if it needs files that tex2lyx
91              does not know about and therefore does not copy  to  the  output
92              directory.
93
94       -help  Help. Print out usage information and quit.
95
96       -version
97              Print out the version number and build information and quit.
98

DESCRIPTION

100   Introduction
101       tex2lyx  will create a LyX file with the specified name (or dir/foo.lyx
102       if no name was given) from the LaTeX file dir/foo.tex.
103
104       Suffixes .tex, .ltx and .latex are supported. If inputfile does not ex‐
105       ist and does not have one of these suffixes, tex2lyx will try to trans‐
106       late inputfile.tex. (This is similar to the behavior of LaTeX.)
107
108       The purpose of tex2lyx is to translate well-behaved LaTeX2e  into  LyX.
109       If  your  LaTeX  file doesn't compile---or if you do weird things, like
110       redefining standard LaTeX commands---it may choke. LaTeX209 will  often
111       be translated correctly, but it's not guaranteed.
112
113       tex2lyx lacks a few features. However, its main goals are:
114
115       •   Get through a well-behaved LaTeX2e file without crashing
116
117       •   Translate a lot of that file.
118
119       •   Localize  the  parts  that can't be translated and copy them in TeX
120           mode
121
122       It achieves these main goals pretty well on most files.
123
124   Usage
125       Here's a more lengthy description of what you should do to translate  a
126       LaTeX document into LyX.
127
128       •   Run tex2lyx.
129
130           tex2lyx  will  inform  you of its progress and give any warnings to
131           stderr, so if you don't want  any  output  at  all,  try  (in  csh)
132           `tex2lyx  foo.tex  >& /dev/null'.  You should NOT redirect standard
133           output to foo.lyx.
134
135       •   Run LyX (version 2.1 or later) on the resulting .lyx file.
136
137           In theory, most of the file will have been translated, and anything
138           that's  untranslatable will be transferred to TeX code (ERT in LyX-
139           speak). In theory, LyX will be able to read in  the  file,  and  to
140           create printed documents from it, because all that untranslated ERT
141           stuff will be passed directly back to LaTeX, which LyX  uses  as  a
142           backend.  Unfortunately,  reality doesn't always reflect theory. If
143           tex2lyx crashes, or LyX cannot read the generated LyX file, see the
144           BUGS section below.
145
146       •   Transform  things  have  been  inserted as TeX code manually to LyX
147           features, if possible.
148
149           As mentioned above, you should be able to print out  the  LyX  file
150           even without doing this. However, changing a command in TeX code to
151           the corresponding LyX object will allow you to  take  advantage  of
152           LyX's WYSIWYM editing.
153
154           tex2lyx  is not guaranteed to create a LyX file which generates ex‐
155           actly the same output as the LaTeX file, although its  goal  is  to
156           achieve this. tex2lyx will generally err on the side of translating
157           less to ensure that the resulting output files are  accurate,  even
158           though this leads to more TeX code and less WYSIWYM.
159
160       •   PROOFREAD THE DOCUMENT!!
161
162           I'm  sure you were planning on doing this anyway, but it's particu‐
163           larly important after translating a LaTeX document. tex2lyx is bet‐
164           ter  at  “macro-translating”  (translating the whole document) than
165           “micro-translating” (translating every little detail). For example,
166           you  may see extra spaces or deleted spaces. Space handling has im‐
167           proved, but it's not perfect.
168
169   What tex2lyx Can Handle
170       tex2lyx understands many LaTeX commands. It will translate:
171
172       •   regular text, including mini-commands like ~, `', \@, \TeX, as well
173           as accented characters like \'{a}, and the special cases ?` and !`
174
175       •   title  commands  like  \author,  \date, \title, \thanks and the ab‐
176           stract environment
177
178       •   heading commands like \section including  starred  commands  (\sec‐
179           tion*)
180
181       •   Environments:  quote, quotation, and verse; center, flushright, and
182           flushleft
183
184       •   itemize, enumerate, and description environments, and  their  \item
185           commands.  Also, well-behaved nested lists
186
187       •   cross-referencing commands: \ref, \pageref, \label, and \cite
188
189       •   \footnote and \margin
190
191       •   font-changing  commands  including  \em, \emph, \textit, and corre‐
192           sponding commands to change family, size, series, and shape
193
194       •   \input{foo} (or \input{foo.blah}) and \include{foo}. Plain TeX \in‐
195           put command “\input foo.tex” is also supported.
196
197       •   tabular  environment,  and  commands that go inside it like \hline,
198           \cline, and \multicolumn (but see below)
199
200       •   float environments table and table*, as well as  \caption  commands
201           within them
202
203       •   float  environments  figure and figure*, as well as graphics inclu‐
204           sion commands \epsf, \epsffile, \epsfbox, \epsfxsize, \epsfig, \ps‐
205           fig, and \includegraphics.  Both the graphics and graphicx forms of
206           \includegraphics are supported.
207
208       •   thebibliography environment and \bibitem command, as well  as  Bib‐
209           TeX's \bibliography and \bibliographystyle commands
210
211       •   miscellaneous commands: \hfill, \\, \noindent, \ldots...
212
213       •   documentclass-specific  environments  (and some commands) which can
214           be translated to LyX layouts
215
216       •   arguments to certain untranslatable commands (e.g. \mbox)
217
218       Some of this support may not be 100% yet. See below for details
219
220       tex2lyx copies math (almost) verbatim from your  LaTeX  file.  Luckily,
221       LyX reads in LaTeX math, so (almost) any math which is supported by LyX
222       should work just fine.
223
224       tex2lyx will copy any preamble commands  (i.e.,  anything  before  \be‐
225       gin{document}) verbatim. Fancy stuff you've got in your preamble should
226       thus be conserved in printed documents, although it will not of  course
227       show  up in the LyX window. Check Document->Settings->LaTeX Preamble to
228       see the result.
229
230   What tex2lyx Can't Handle --- But it's OK
231       •   some spacing commands (\hspace, \pagebreak and \linebreak)
232
233       •   \centering, \raggedleft, \raggedright
234
235       •   \verb and verbatim environment. tex2lyx is careful to copy  exactly
236           in this case, including comments and whitespace.
237
238       •   unknown (e.g., user-defined) environments and commands
239
240       tex2lyx  copies  unknown commands, along with their arguments, verbatim
241       into the LyX file. Also, if it sees a \begin{foo} where it doesn't rec‐
242       ognize  the  “foo”  environment,  it  will  copy verbatim until it sees
243       \end{foo} (unless you use the -r option). Most of  these  unknown  com‐
244       mands  won't  cause  tex2lyx to break; they'll merely require you to do
245       some editing once you've loaded the file up in  LyX.   That  should  be
246       less painful than editing either the .tex or the .lyx file using a text
247       editor.
248
249   What tex2lyx Handles Badly --- aka BUGS
250       Since tex2lyx is relatively new, it's got a number of problems.  As  it
251       matures, these bugs will be squished.
252
253       •   “Exact”  copying  of  unknown environments and commands isn't quite
254           exact.  This will yield ugly LyX, but in almost all cases the  out‐
255           put  will  be  the  same.   However, most parts of the file will be
256           copied perfectly, including whitespace and comments. This includes:
257           the  LaTeX  preamble,  verbatim  environments as well as \verb com‐
258           mands, and skip blocks.
259
260tex2lyx translates only a subset of the document class  options  to
261           native  features.   Other options are placed in the “options” field
262           in the Document->Settings popup.
263
264           More importantly, tex2lyx doesn't translate  \newcommands,  unknown
265           \usepackage  commands  and  other  unknown code in the preamble. It
266           simply copies that into the LaTeX preamble. If you use special com‐
267           mands,  e.g.  to  specify the text layout in a way that that is not
268           understood by LyX, tex2lyx won't recognize it. Note that these set‐
269           tings  will  be  overwritten if you modify the text layout in LyX's
270           document settings. Better remove these special options from the La‐
271           TeX  preamble (Document->Settings->LaTeX Preamble) and use the cor‐
272           responding LyX document settings, if possible.
273
274       •   The foil document class has a couple of bugs. tex2lyx may do  weird
275           things  with optional arguments to \foilhead commands. Also, it may
276           handle \begin{dinglist} incorrectly (although the stuff in the  en‐
277           vironment should translate normally).
278
279       All     known     bugs     of     tex2lyx     can     be    found    on
280       http://www.lyx.org/trac/wiki/BugTrackerHome.
281
282       tex2lyx is rather robust. As mentioned above, it may not translate your
283       file perfectly, but the result should be usable and it shouldn't crash.
284       If you encounter problems---and the problem is not one  of  those  men‐
285       tioned above or on http://www.lyx.org/trac/wiki/BugTrackerHome---please
286       report the issue as described in the section on Bug Reports.
287
288   What LyX Can't Handle
289       LyX itself is missing a couple of features, such that even  if  tex2lyx
290       translates  things perfectly, LyX may still have trouble reading it. If
291       you really need these features, you can export your final  document  as
292       LaTeX, and put them back in. See BUGS for more details on these bugs.
293
294       •   For a number of commands (such as \\), LyX does not support the op‐
295           tional argument.  tex2lyx will automatically discard  the  optional
296           arguments with a warning to stdout.  LyX also ignores the width ar‐
297           gument for the thebibliography environment.
298
299       •   LyX support for tables isn't perfect. For complicated tables, use a
300           “skip” block, so that they will be copied in TeX mode.
301
302       •   LyX allows figures to have sizes in the units known to TeX, such as
303           in, cm, etc. It also translates percentages of  \textwidth,  \text‐
304           height,  \columnwidth,  but no other lengths (e.g. if you wanted to
305           scale a figure to size \topmargin for some  reason).  tex2lyx  will
306           copy  figures  with  untranslatable  sizes  in TeX mode. Again, you
307           might be able to fix that within LyX.
308

EXAMPLES

310       tex2lyx -f -r “myenv” foo.tex
311
312       The above will create a file foo.lyx from foo.tex, overwriting if  nec‐
313       essary.   When  it finds a \begin{myenv} ... \end{myenv} block, it will
314       translate the stuff within the block, but copy the \begin and \end com‐
315       mands in TeX mode.
316
317       tex2lyx -n -c “literate-article” foo.tex
318
319       The above will change a noweb document into a LyX literate-article doc‐
320       ument. A user would do this if the noweb document had documentclass ar‐
321       ticle.
322

NOTES

324   Bug Reports
325       Bugs    should    be    reported    to   the   LyX   bug   tracker   at
326       http://www.lyx.org/trac/wiki/BugTrackerHome. Additionally, you can post
327       a message to the LyX developers' mailing list. Its address is currently
328       lyx-devel@lists.lyx.org. If your message bounces, you can check the LyX
329       home  page,  http://www.lyx.org/.  If you are running tex2lyx on a huge
330       file, please do not send all of the output in your bug report. Just in‐
331       clude  the  last ten or twenty lines of output, along with the piece of
332       the LaTeX file it crashed on.  Or, even better, attach a small but com‐
333       plete file which causes the same problem as your original file.
334
335   Layout Files
336       tex2lyx  reads  a  LyX layout file to know how to handle LaTeX environ‐
337       ments and commands which get translated to LyX layouts. This file  will
338       include  all  “normal” non-math environments (i.e., including quote and
339       itemize, but not tabular, minipage, and some other fancy environments),
340       and  commands  like \section and \title. If you want to tex2lyx a class
341       that doesn't have an existing layout file, then you'll have to create a
342       layout  file. But you have to do this anyway, in order to LyX the file,
343       since LyX depends on layout files to know how to  display  and  process
344       its  files.  Check the LyX documentation for help with this task (which
345       can be hard or easy, depending on the class you want to create a layout
346       file  for.) If your class is quite similar to a class that has a layout
347       file, then consider using the -c option.
348
349   Syntax Files
350       tex2lyx always reads at least one syntax file, called the default  syn‐
351       tax  file.   tex2lyx  will read your personal syntax file if it exists;
352       otherwise it will read the system-wide file. tex2lyx  will  read  addi‐
353       tional  syntax files if you specify them with the -s option. (These ex‐
354       tra files should have the same format as the  default  file,  but  will
355       tend  to be shorter, since they only have to specify extra commands not
356       found in the default file.) A syntax file tells tex2lyx a few things.
357
358       First, it describes the syntax of each command, that is, how  many  re‐
359       quired  arguments  and  how  many optional arguments the command takes.
360       Knowing this makes it easier for tex2lyx to copy (in TeX mode) commands
361       that  it  doesn't  know  how to translate. The syntax file simply has a
362       command, followed by braces or brackets describing its arguments in the
363       correct order. For example, a syntax file entry \bibitem[]{} means that
364       the \bibitem command takes an optional argument followed by a  required
365       one,  while the entry \bf means that the \bf command takes no arguments
366       at all.  When tex2lyx encounters a token that it doesn't  know  how  to
367       translate  into  LyX,  it  will copy the token---along with the correct
368       number of arguments---exactly.  If the token is not in the syntax file,
369       then  tex2lyx  just  copies  as many arguments as it finds.  This means
370       that it may copy too much. But since the user  can  specify  additional
371       syntax files, that shouldn't happen often.
372
373       Some commands that cannot be translated to LyX, like \mbox, have as one
374       of their arguments regular LaTeX text. If the string “translate” is put
375       into  an  argument  of  an (untranslatable) command in the syntax file,
376       then tex2lyx will translate that argument instead of copying it  verba‐
377       tim.   So,   for   example,   the   default  syntax  file  has  \raise‐
378       box{}[][]{translate}. This means that the  \raisebox  command  and  the
379       first argument (and optional arguments if they exist) are copied in TeX
380       mode, but the last argument (which may contain math, complicated LaTeX,
381       other  untranslatable  commands, etc.) will be translated into LyX. You
382       can't use “translate” on optional arguments.
383
384       User-defined syntax files are allowed to define new commands and  their
385       syntax,  or override the number of arguments for a command given in the
386       default syntax file. (E.g., if you're using a style that gives an extra
387       argument to some command...) However, this will only be useful for com‐
388       mands copied in TeX mode. Commands which  are  actually  translated  by
389       tex2lyx  (like  \item) have their argument syntax hard-coded. The hard-
390       coded commands are identified in the default syntax file.
391
392       Second, the syntax file describes any “regular environments”.  Usually,
393       an entire unknown environment will be copied in TeX mode. If you define
394       a regular environment “foo”, though,  then  only  the  \begin{foo}  and
395       \end{foo}  commands will be copied in TeX mode; the text within the en‐
396       vironment will be treated (i.e., translated) by tex2lyx as regular  La‐
397       TeX, rather than being copied into TeX mode. Don't try to declare “tab‐
398       bing” and “picture” as regular environments, as the text  within  those
399       environments will confuse tex2lyx; use this capability for new environ‐
400       ments you create that have plain text or math  or  simple  commands  in
401       them. You also can't declare unknown math environments (like equation*)
402       as regular environments, either, since the LyX math editor won't under‐
403       stand  them. The names of regular environments appear, whitespace-sepa‐
404       rated, between \begin{tex2lyxre} and \end{tex2lyxre} statements in  the
405       syntax  file.  (If  you  have a regular environment which you won't use
406       very often, you can use the -r option  rather  than  writing  a  syntax
407       file.)
408

WARNINGS

410       Always  keep a copy of your original LaTeX files either under a differ‐
411       ent name or in a different directory. There are a couple ways in  which
412       using LyX could lead to overwriting the original LaTeX file.
413
414       If  you import foo.tex to create foo.lyx, then edit foo.lyx and want to
415       re-export it, note that it will overwrite the  original  foo.tex.  (LyX
416       will ask you if you want to overwrite it.)
417

ENVIRONMENT

419       LYX_DIR_23x
420             can be used to specify which system directory to use.
421
422       The  system  directory is determined by searching for the file "chkcon‐
423       fig.ltx". Directories are searched in this order:
424       1) -sysdir command line parameter
425       2) LYX_DIR_23x environment variable
426       3) Maybe <path of binary>/TOP_SRCDIR/lib
427       4) <path of binary>/../share/<name of binary>/
428       5) hardcoded lyx_dir (at build time: /usr/share/lyx)
429
430       LYX_USERDIR_23x
431              can be used to specify which user directory to use.
432
433       The user directory is, in order of precedence:
434       1) -userdir command line parameter
435       2) LYX_USERDIR_23x environment variable
436       3) $HOME/.<name of binary> if no explicit setting is made
437

FILES

439       If LIBDIR is the system-wide LyX directory and MY_LYXDIR is  your  per‐
440       sonal LyX directory, then the following files are read by tex2lyx:
441
442       MY_LYXDIR/layouts/*.layout
443           User's personal layout files for document classes
444
445       MY_LYXDIR/syntax.default
446           User's personal syntax file
447
448       MY_LYXDIR/encodings
449           User's personal encoding definition file
450
451       LIBDIR/layouts/*.layout
452           System-wide layout files for document classes
453
454       LIBDIR/lib/syntax.default
455           System-wide LaTeX syntax file
456
457       LIBDIR/lib/encodings
458           System-wide encoding definition file
459

SEE ALSO

461       lyx(1), latex(1)
462

AUTHORS

464       tex2lyx   is   Copyright   (c)   2003ff.   by  the  LyX  Team  (lyx-de‐
465       vel@lists.lyx.org)
466
467
468
469Version 2.3.7                     2023-01-01                        TEX2LYX(1)
Impressum