1TEX2LYX(1) tex2lyx 2.0.1 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
11 resulting file into LyX. You should try that first, and call it from
12 the command line only if you need to use more complicated options.
13 tex2lyx [ -userdir userdir ] [ -systemdir systemdir ] [ -n ] [ -c
15 textclass ] [ -s sfile1[,sfile2...]] [ -roundtrip ] inputfile [ output‐
16 file ]
17
19 -c Class. By default, when tex2lyx sees a \documentclass{foo} com‐
20 mand, it creates a file of textclass “foo” and reads the LyX
21 layout file for that class (something like
22 /usr/local/share/lyx/layouts/foo.layout OR HOME/.lyx/lay‐
23 outs/foo.layout). Use -c to declare a different textclass (and
24 read a different layout file).
25 -f Force. tex2lyx will not run if the .lyx file it would generate
27 already exists. Use the -f option (carefully) to clobber any
28 existing files.
29 -n Noweb. Translate a noweb (aka literate programming) file. This
31 should be (almost?) equivalent to running “noweb2lyx foo.tex
32 foo.lyx”. This option requires the -c option.
33 -s Syntax files. Input (one or more quoted, comma-separated) syntax
35 files to read in addition to the default. (see the section on
36 Syntax Files for details).
37 -sysdir
39 Specify a system directory. Normally, you shouldn't need this.
40 Your LyX system directory is chosen. Cf. the section FILES for
41 details.
42 -userdir
44 Specify a user directory. Normally, you shouldn't need this.
45 Your LyX user directory is chosen. Cf. the section FILES for
46 details.
47 -roundtrip
49 Call LyX to re-export the created output file to LaTeX. The out‐
50 put file name is always determined automatically to avoid over-
51 writing the input file by accident: If the input file is named
52 foo.tex the output file will be named foo.lyx.lyx, and the re-
53 exported file will be named foo.lyx.tex.
54 -help Help. Print out usage information and quit.
56
58 Introduction
59 tex2lyx will create a LyX file with the specified name (or dir/foo.lyx
60 if no name was given) from the LaTeX file dir/foo.tex.
61 Suffixes .tex, .ltx and .latex are supported. If inputfile does not
63 exist and does not have one of these suffixes, tex2lyx will try to
64 translate inputfile.tex. (This is similar to the behavior of LaTeX.)
65 The purpose of tex2lyx is to translate well-behaved LaTeX2e into LyX.
67 If your LaTeX file doesn't compile---or if you do weird things, like
68 redefining standard LaTeX commands---it may choke. LaTeX209 will often
69 be translated correctly, but it's not guaranteed.
70 tex2lyx lacks a few features. However, its main goals are:
72 · Get through a well-behaved LaTeX2e file without crashing
74 · Translate a lot of that file.
76 · Localize the parts that can't be translated and copy them in TeX
78 mode
79 It achieves these main goals pretty well on most files.
81 Usage
83 Here's a more lengthy description of what you should do to translate a
84 LaTeX document into LyX.
85 · Run tex2lyx.
87 tex2lyx will inform you of its progress and give any warnings to
89 stderr, so if you don't want any output at all, try (in csh)
90 `tex2lyx foo.tex >& /dev/null'. You should NOT redirect standard
91 output to foo.lyx.
92 · Run LyX (version 1.6 or later) on the resulting .lyx file.
94 In theory, most of the file will have been translated, and anything
96 that's untranslatable will be transferred to TeX code (ERT in LyX-
97 speak). In theory, LyX will be able to read in the file, and to
98 create printed documents from it, because all that untranslated ERT
99 stuff will be passed directly back to LaTeX, which LyX uses as a
100 backend. Unfortunately, reality doesn't always reflect theory. If
101 tex2lyx crashes, or LyX cannot read the generated LyX file, see the
102 BUGS section below.
103 · Transform things have been inserted as TeX code manually to LyX
105 features, if possible.
106 As mentioned above, you should be able to print out the LyX file
108 even without doing this. However, changing a command in TeX code to
109 the corresponding LyX object will allow you to take advantage of
110 LyX's WYSIWYM editing.
111 tex2lyx is not guaranteed to create a LyX file which generates
113 exactly the same output as the LaTeX file, although its goal is to
114 achieve this. tex2lyx will generally err on the side of translating
115 less to ensure that the resulting output files are accurate, even
116 though this leads to more TeX code and less WYSIWYM.
117 · PROOFREAD THE DOCUMENT!!
119 I'm sure you were planning on doing this anyway, but it's particu‐
121 larly important after translating a LaTeX document. tex2lyx is bet‐
122 ter at “macro-translating” (translating the whole document) than
123 “micro-translating” (translating every little detail). For example,
124 you may see extra spaces or deleted spaces. Space handling has
125 improved, but it's not perfect.
126 What tex2lyx Can Handle
128 tex2lyx understands many LaTeX commands. It will translate:
129 · regular text, including mini-commands like ~, `', \@, \TeX, as well
131 as accented characters like \'{a}, and the special cases ?` and !`
132 · title commands like \author, \date, \title, \thanks and the
134 abstract environment
135 · heading commands like \section including starred commands (\sec‐
137 tion*)
138 · Environments: quote, quotation, and verse; center, flushright, and
140 flushleft
141 · itemize, enumerate, and description environments, and their \item
143 commands. Also, well-behaved nested lists
144 · cross-referencing commands: \ref, \pageref, \label, and \cite
146 · \footnote and \margin
148 · font-changing commands including \em, \emph, \textit, and corre‐
150 sponding commands to change family, size, series, and shape
151 · \input{foo} (or \input{foo.blah}) and \include{foo}. Plain TeX
153 \input command “\input foo.tex” is also supported.
154 · tabular environment, and commands that go inside it like \hline,
156 \cline, and \multicolumn (but see below)
157 · float environments table and table*, as well as \caption commands
159 within them
160 · float environments figure and figure*, as well as graphics inclu‐
162 sion commands \epsf, \epsffile, \epsfbox, \epsfxsize, \epsfig,
163 \psfig, and \includegraphics. Both the graphics and graphicx forms
164 of \includegraphics are supported.
165 · thebibliography environment and \bibitem command, as well as Bib‐
167 TeX's \bibliography and \bibliographystyle commands
168 · miscellaneous commands: \hfill, \\, \noindent, \ldots...
170 · documentclass-specific environments (and some commands) which can
172 be translated to LyX layouts
173 · arguments to certain untranslatable commands (e.g. \mbox)
175 Some of this support may not be 100% yet. See below for details
177 tex2lyx copies math (almost) verbatim from your LaTeX file. Luckily,
179 LyX reads in LaTeX math, so (almost) any math which is supported by LyX
180 should work just fine.
181 tex2lyx will copy any preamble commands (i.e., anything before
183 \begin{document}) verbatim. Fancy stuff you've got in your preamble
184 should thus be conserved in printed documents, although it will not of
185 course show up in the LyX window. Check Document->Settings->LaTeX Pre‐
186 amble to see the result.
187 What tex2lyx Can't Handle --- But it's OK
189 · tabular* tables
190 · some spacing commands (\hspace, \pagebreak and \linebreak)
192 · \centering, \raggedleft, \raggedright
194 · \verb and verbatim environment. tex2lyx is careful to copy exactly
196 in this case, including comments and whitespace.
197 · unknown (e.g., user-defined) environments and commands
199 tex2lyx copies unknown commands, along with their arguments, verbatim
201 into the LyX file. Also, if it sees a \begin{foo} where it doesn't rec‐
202 ognize the “foo” environment, it will copy verbatim until it sees
203 \end{foo} (unless you use the -r option). Most of these unknown com‐
204 mands won't cause tex2lyx to break; they'll merely require you to do
205 some editing once you've loaded the file up in LyX. That should be
206 less painful than editing either the .tex or the .lyx file using a text
207 editor.
208 What tex2lyx Handles Badly --- aka BUGS
210 Since tex2lyx is relatively new, it's got a number of problems. As it
211 matures, these bugs will be squished.
212 · “Exact” copying of unknown environments and commands isn't quite
214 exact. This will yield ugly LyX, but in almost all cases the out‐
215 put will be the same. However, most parts of the file will be
216 copied perfectly, including whitespace and comments. This includes:
217 the LaTeX preamble, verbatim environments as well as \verb com‐
218 mands, and skip blocks.
219 · tex2lyx translates only a subset of the document class options to
221 native features. Other options are placed in the “options” field
222 in the Document->Settings popup.
223 More importantly, tex2lyx doesn't translate \newcommands, unknown
225 \usepackage commands and other unknown code in the preamble. It
226 simply copies that into the LaTeX preamble. If you use special com‐
227 mands, e.g. to specify the text layout in a way that that is not
228 understood by LyX, tex2lyx won't recognize it. Note that these set‐
229 tings will be overwritten if you modify the text layout in LyX's
230 document settings. Better remove these special options from the
231 LaTeX preamble (Document->Settings->LaTeX Preamble) and use the
232 corresponding LyX document settings, if possible.
233 · The foil document class has a couple of bugs. tex2lyx may do weird
235 things with optional arguments to \foilhead commands. Also, it may
236 handle \begin{dinglist} incorrectly (although the stuff in the
237 environment should translate normally).
238 All known bugs of tex2lyx can be found on
240 http://www.lyx.org/trac/wiki/BugTrackerHome.
241 tex2lyx is rather robust. As mentioned above, it may not translate your
243 file perfectly, but the result should be usable and it shouldn't crash.
244 If you encounter problems---and the problem is not one of those men‐
245 tioned above or on http://www.lyx.org/trac/wiki/BugTrackerHome---please
246 report the issue as described in the section on Bug Reports.
247 What LyX Can't Handle
249 LyX itself is missing a couple of features, such that even if tex2lyx
250 translates things perfectly, LyX may still have trouble reading it. If
251 you really need these features, you can export your final document as
252 LaTeX, and put them back in. See BUGS for more details on these bugs.
253 · For a number of commands (such as \\), LyX does not support the
255 optional argument. tex2lyx will automatically discard the optional
256 arguments with a warning to stdout. LyX also ignores the width
257 argument for the thebibliography environment.
258 · LyX support for tables isn't perfect. For complicated tables, use a
260 “skip” block, so that they will be copied in TeX mode.
261 · LyX allows figures to have sizes in the units known to TeX, such as
263 in, cm, etc. It also translates percentages of \textwidth, \tex‐
264 theight, \columnwidth, but no other lengths (e.g. if you wanted to
265 scale a figure to size \topmargin for some reason). tex2lyx will
266 copy figures with untranslatable sizes in TeX mode. Again, you
267 might be able to fix that within LyX.
268
270 tex2lyx -f -r “myenv” foo.tex
271 The above will create a file foo.lyx from foo.tex, overwriting if nec‐
273 essary. When it finds a \begin{myenv} ... \end{myenv} block, it will
274 translate the stuff within the block, but copy the \begin and \end com‐
275 mands in TeX mode.
276 tex2lyx -n -c “literate-article” foo.tex
278 The above will change a noweb document into a LyX literate-article doc‐
280 ument. A user would do this if the noweb document had documentclass
281 article.
282
284 Bug Reports
285 Bugs should be reported to the LyX bug tracker at
286 http://www.lyx.org/trac/wiki/BugTrackerHome. Additionally, you can post
287 a message to the LyX developers' mailing list. Its address is currently
288 lyx-devel@lists.lyx.org. If your message bounces, you can check the LyX
289 home page, http://www.lyx.org/. If you are running tex2lyx on a huge
290 file, please do not send all of the output in your bug report. Just
291 include the last ten or twenty lines of output, along with the piece of
292 the LaTeX file it crashed on. Or, even better, attach a small but com‐
293 plete file which causes the same problem as your original file.
294 Layout Files
296 tex2lyx reads a LyX layout file to know how to handle LaTeX environ‐
297 ments and commands which get translated to LyX layouts. This file will
298 include all “normal” non-math environments (i.e., including quote and
299 itemize, but not tabular, minipage, and some other fancy environments),
300 and commands like \section and \title. If you want to tex2lyx a class
301 that doesn't have an existing layout file, then you'll have to create a
302 layout file. But you have to do this anyway, in order to LyX the file,
303 since LyX depends on layout files to know how to display and process
304 its files. Check the LyX documentation for help with this task (which
305 can be hard or easy, depending on the class you want to create a layout
306 file for.) If your class is quite similar to a class that has a layout
307 file, then consider using the -c option.
308 Syntax Files
310 tex2lyx always reads at least one syntax file, called the default syn‐
311 tax file. tex2lyx will read your personal syntax file if it exists;
312 otherwise it will read the system-wide file. tex2lyx will read addi‐
313 tional syntax files if you specify them with the -s option. (These
314 extra files should have the same format as the default file, but will
315 tend to be shorter, since they only have to specify extra commands not
316 found in the default file.) A syntax file tells tex2lyx a few things.
317 First, it describes the syntax of each command, that is, how many
319 required arguments and how many optional arguments the command takes.
320 Knowing this makes it easier for tex2lyx to copy (in TeX mode) commands
321 that it doesn't know how to translate. The syntax file simply has a
322 command, followed by braces or brackets describing its arguments in the
323 correct order. For example, a syntax file entry \bibitem[]{} means that
324 the \bibitem command takes an optional argument followed by a required
325 one, while the entry \bf means that the \bf command takes no arguments
326 at all. When tex2lyx encounters a token that it doesn't know how to
327 translate into LyX, it will copy the token---along with the correct
328 number of arguments---exactly. If the token is not in the syntax file,
329 then tex2lyx just copies as many arguments as it finds. This means
330 that it may copy too much. But since the user can specify additional
331 syntax files, that shouldn't happen often.
332 Some commands that cannot be translated to LyX, like \mbox, have as one
334 of their arguments regular LaTeX text. If the string “translate” is put
335 into an argument of an (untranslatable) command in the syntax file,
336 then tex2lyx will translate that argument instead of copying it verba‐
337 tim. So, for example, the default syntax file has \raise‐
338 box{}[][]{translate}. This means that the \raisebox command and the
339 first argument (and optional arguments if they exist) are copied in TeX
340 mode, but the last argument (which may contain math, complicated LaTeX,
341 other untranslatable commands, etc.) will be translated into LyX. You
342 can't use “translate” on optional arguments.
343 User-defined syntax files are allowed to define new commands and their
345 syntax, or override the number of arguments for a command given in the
346 default syntax file. (E.g., if you're using a style that gives an extra
347 argument to some command...) However, this will only be useful for com‐
348 mands copied in TeX mode. Commands which are actually translated by
349 tex2lyx (like \item) have their argument syntax hard-coded. The hard-
350 coded commands are identified in the default syntax file.
351 Second, the syntax file describes any “regular environments”. Usually,
353 an entire unknown environment will be copied in TeX mode. If you define
354 a regular environment “foo”, though, then only the \begin{foo} and
355 \end{foo} commands will be copied in TeX mode; the text within the
356 environment will be treated (i.e., translated) by tex2lyx as regular
357 LaTeX, rather than being copied into TeX mode. Don't try to declare
358 “tabbing” and “picture” as regular environments, as the text within
359 those environments will confuse tex2lyx; use this capability for new
360 environments you create that have plain text or math or simple commands
361 in them. You also can't declare unknown math environments (like equa‐
362 tion*) as regular environments, either, since the LyX math editor won't
363 understand them. The names of regular environments appear, whitespace-
364 separated, between \begin{tex2lyxre} and \end{tex2lyxre} statements in
365 the syntax file. (If you have a regular environment which you won't use
366 very often, you can use the -r option rather than writing a syntax
367 file.)
368
370 Always keep a copy of your original LaTeX files either under a differ‐
371 ent name or in a different directory. There are a couple ways in which
372 using LyX could lead to overwriting the original LaTeX file.
373 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
375 re-export it, note that it will overwrite the original foo.tex. (LyX
376 will ask you if you want to overwrite it.)
377
379 LYX_DIR_20x
380 can be used to specify which system directory to use.
381 The system directory is determined by searching for the file "chkcon‐
383 fig.ltx". Directories are searched in this order:
384 1) -sysdir command line parameter
385 2) LYX_DIR_20x environment variable
386 3) Maybe <path of binary>/TOP_SRCDIR/lib
387 4) <path of binary>/../share/<name of binary>/
388 5) hardcoded lyx_dir (at build time: /usr/share/lyx)
389 LYX_USERDIR_20x
391 can be used to specify which user directory to use.
392 The user directory is, in order of precedence:
394 1) -userdir command line parameter
395 2) LYX_USERDIR_20x environment variable
396 3) $HOME/.<name of binary> if no explicit setting is made
397
399 If LIBDIR is the system-wide LyX directory and MY_LYXDIR is your per‐
400 sonal LyX directory, then the following files are read by tex2lyx:
401 MY_LYXDIR/layouts/*.layout
403 User's personal layout files for document classes
404 MY_LYXDIR/syntax.default
406 User's personal syntax file
407 LIBDIR/layouts/*.layout
409 System-wide layout files for document classes
410 LIBDIR/lib/syntax.default
412 System-wide LaTeX syntax file
413
415 lyx(1), latex(1)
416
418 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-
419 devel@lists.lyx.org)
420Version 2.0.1 2011-08-31 TEX2LYX(1)