1TEX2LYX(1) tex2lyx 2.3.7 TEX2LYX(1)
2
6 tex2lyx - translate well-behaved LaTeX into LyX
7
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 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
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 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -help Help. Print out usage information and quit.
95 -version
97 Print out the version number and build information and quit.
98
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 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 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 tex2lyx lacks a few features. However, its main goals are:
114 • Get through a well-behaved LaTeX2e file without crashing
116 • Translate a lot of that file.
118 • Localize the parts that can't be translated and copy them in TeX
120 mode
121 It achieves these main goals pretty well on most files.
123 Usage
125 Here's a more lengthy description of what you should do to translate a
126 LaTeX document into LyX.
127 • Run tex2lyx.
129 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 • Run LyX (version 2.1 or later) on the resulting .lyx file.
136 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 • Transform things have been inserted as TeX code manually to LyX
147 features, if possible.
148 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 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 • PROOFREAD THE DOCUMENT!!
161 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 What tex2lyx Can Handle
170 tex2lyx understands many LaTeX commands. It will translate:
171 • regular text, including mini-commands like ~, `', \@, \TeX, as well
173 as accented characters like \'{a}, and the special cases ?` and !`
174 • title commands like \author, \date, \title, \thanks and the ab‐
176 stract environment
177 • heading commands like \section including starred commands (\sec‐
179 tion*)
180 • Environments: quote, quotation, and verse; center, flushright, and
182 flushleft
183 • itemize, enumerate, and description environments, and their \item
185 commands. Also, well-behaved nested lists
186 • cross-referencing commands: \ref, \pageref, \label, and \cite
188 • \footnote and \margin
190 • font-changing commands including \em, \emph, \textit, and corre‐
192 sponding commands to change family, size, series, and shape
193 • \input{foo} (or \input{foo.blah}) and \include{foo}. Plain TeX \in‐
195 put command “\input foo.tex” is also supported.
196 • tabular environment, and commands that go inside it like \hline,
198 \cline, and \multicolumn (but see below)
199 • float environments table and table*, as well as \caption commands
201 within them
202 • 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 • thebibliography environment and \bibitem command, as well as Bib‐
209 TeX's \bibliography and \bibliographystyle commands
210 • miscellaneous commands: \hfill, \\, \noindent, \ldots...
212 • documentclass-specific environments (and some commands) which can
214 be translated to LyX layouts
215 • arguments to certain untranslatable commands (e.g. \mbox)
217 Some of this support may not be 100% yet. See below for details
219 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 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 What tex2lyx Can't Handle --- But it's OK
231 • some spacing commands (\hspace, \pagebreak and \linebreak)
232 • \centering, \raggedleft, \raggedright
234 • \verb and verbatim environment. tex2lyx is careful to copy exactly
236 in this case, including comments and whitespace.
237 • unknown (e.g., user-defined) environments and commands
239 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 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 • “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 • tex2lyx 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 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 • 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 All known bugs of tex2lyx can be found on
280 http://www.lyx.org/trac/wiki/BugTrackerHome.
281 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 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 • 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 • 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 • 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
310 tex2lyx -f -r “myenv” foo.tex
311 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 tex2lyx -n -c “literate-article” foo.tex
318 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
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 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 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 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 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 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 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
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 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
419 LYX_DIR_23x
420 can be used to specify which system directory to use.
421 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 LYX_USERDIR_23x
431 can be used to specify which user directory to use.
432 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
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 MY_LYXDIR/layouts/*.layout
443 User's personal layout files for document classes
444 MY_LYXDIR/syntax.default
446 User's personal syntax file
447 MY_LYXDIR/encodings
449 User's personal encoding definition file
450 LIBDIR/layouts/*.layout
452 System-wide layout files for document classes
453 LIBDIR/lib/syntax.default
455 System-wide LaTeX syntax file
456 LIBDIR/lib/encodings
458 System-wide encoding definition file
459
461 lyx(1), latex(1)
462
464 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-de‐
465 vel@lists.lyx.org)
466Version 2.3.7 2023-01-01 TEX2LYX(1)