1TEX2LYX(1) TEX2LYX(1)
2
6 tteexx22llyyxx - translate well-behaved LaTeX into LyX
7
9 The simplest way to use tteexx22llyyxx is via the File->Import command in LyX.
10 That runs tteexx22llyyxx on the given file and loads the resulting file into
11 LyX. You should try that first, and call it from the command line only
12 if you need to use more complicated options.
13 tteexx22llyyxx [ --ddff ] [ --uusseerrddiirr userdir ] [ --ssyysstteemmddiirr systemdir ] [--nn]
15 [ --rr renv1[,renv2...]] [ --ss sfile1[,sfile2...]] inputfile [ --cc
16 textclass ]
17 tteexx22llyyxx [ --ddff ] [ --uusseerrddiirr userdir ] [ --ssyysstteemmddiirr systemdir ]
19 [ --rr renv1[,renv2...]] [ --ss sfile1[,sfile2...]] inputfiles --pp --cc
20 textclass
21 tteexx22llyyxx --hheellpp
23
25 --cc Class. By default, when tteexx22llyyxx sees a \documentclass{foo} command,
26 it creates a file of textclass "foo" and reads the LyX layout file
27 for that class (something like
28 /usr/local/share/lyx/layouts/foo.layout OR
29 HHOOMMEE/.lyx/layouts/foo.layout). Use --cc to declare a different
30 textclass (and read a different layout file).
31 --dd Debug. By default, tteexx22llyyxx gives sparse output and deletes the
33 temporary files which were created during translation. Using the --dd
34 flag will create much more output (both to stdout and stderr) and
35 leave the temporary files around.
36 --ff Force. tteexx22llyyxx will not run if the .lyx file it would generate
38 already exists. Use the --ff option (carefully) to clobber any
39 existing files.
40 --hheellpp
42 Help. Print out usage information and quit.
43 --nn Noweb. Translate a noweb (aka literate programming) file. This
45 should be (almost?) equivalent to running "noweb2lyx foo.tex
46 foo.lyx". This option requires the --cc option.
47 --pp Partial file. The input files are LaTeX fragments, with no preamble
49 matter or \begin{document} commands. This option requires the --cc
50 option, since there are no \documentclass commands in the files
51 tteexx22llyyxx is translating. When using this option, you can translate
52 more than one file, as long as all files are the same class. The
53 LyX file created by tteexx22llyyxx can be included in an existing LyX file
54 using the "Include LyX File" command from LyX's Insert menu.
55 --rr Regular environments (see the section on Syntax Files). If you
57 give more than one environment, separate them with commas (not
58 spaces). You'll probably need to quote the environment list,
59 especially if it has asterisk environments (foo*) in it. If you use
60 this command often, considering creating a personal syntax file.
61 --ss Syntax files. Input (one or more quoted, comma-separated) syntax
63 files to read in addition to the default. (see the section on
64 Syntax Files for details).
65 --ssyyssddiirr
67 Specify a system directory. Normally, you shouldn't need this. Your
68 LyX system directory is chosen. Cf. the section FILES for details.
69 --uusseerrddiirr
71 Specify a user directory. Normally, you shouldn't need this. Your
72 LyX user directory is chosen. Cf. the section FILES for details.
73
75 IInnttrroodduuccttiioonn
76 tteexx22llyyxx will create a LyX file dir/foo.lyx from the LaTeX file
78 dir/foo.tex.
79 Suffixes .tex, .ltx and .latex are supported. If inputfile does not
81 exist and does not have one of these suffixes, tteexx22llyyxx will try to
82 translate inputfile.tex. (This is similar to the behavior of LaTeX.)
83 The purpose of tteexx22llyyxx is to translate well-behaved LaTeX2e into LyX.
85 If your LaTeX file doesn't compile---or if you do weird things, like
86 redefining standard LaTeX commands---it may choke. LaTeX209 will often
87 be translated correctly, but it's not guaranteed.
88 tteexx22llyyxx has some bugs and lacks a few features. However, its main goals
90 are:
91 · Get through a well-behaved LaTeX2e file without crashing
93 · Translate a lot of that file.
95 · Localize the parts that can't be translated and copy them in TeX
97 mode
98 It achieves these main goals pretty well on most files.
100 There are many improvements that can and will be made to tteexx22llyyxx in the
102 future. However, we wanted to get tteexx22llyyxx out there early on, to make
103 it easier for new LyX users to read in their existing LaTeX files.
104 UUssaaggee
106 Here's a more lengthy description of what you should do to translate a
108 LaTeX document into LyX.
109 · Run tteexx22llyyxx.
111 tteexx22llyyxx will inform you of its progress and give any warnings to
113 stderr, so if you don't want any output at all, try (in csh)
114 'tex2lyx foo.tex >& /dev/null'. You should NOT redirect standard
115 output to foo.lyx.
116 · Run LyX (version 1.4 or later) on the resulting .lyx file.
118 In theory, most of the file will have been translated, and anything
120 that's untranslatable will be transferred to TeX mode (ERT in LyX-
121 speak). In theory, LyX will be able to read in the file, and to
122 create printed documents from it, because all that untranslated ERT
123 stuff will be passed directly back to LaTeX, which LyX uses as a
124 backend. Unfortunately, reality doesn't always reflect theory. If
125 tteexx22llyyxx crashes, or LyX cannot read the generated LyX file, see the
126 BUGS entry elsewhere in this document or the BUGS file.
127 · Change things that are highlighted in ERT (TeX mode) by hand in
129 LyX.
130 As mentioned above, you should be able to print out the LyX file
132 even without doing this. However, changing a command in TeX mode to
133 the corresponding LyX object will allow you to take advantage of
134 LyX's WYSIWYM editing.
135 tteexx22llyyxx is not guaranteed to create a LyX file which generates
137 exactly the same output as the LaTeX file, but it should come
138 close. tteexx22llyyxx will generally err on the side of translating less
139 to ensure that dvi or ps files are accurate, even though this leads
140 to more "evil red text" and less WYSIWYM.
141 · PROOFREAD THE DOCUMENT!!
143 I'm sure you were planning on doing this anyway, but it's
145 particularly important after translating a LaTeX document. tteexx22llyyxx
146 is, at least now, better at "macro-translating" (translating the
147 whole document) than "micro-translating" (translating every little
148 detail). For example, you may see extra spaces or deleted spaces.
149 Space handling has improved, but it's not perfect.
150 WWhhaatt tteexx22llyyxx CCaann HHaannddllee
152 tteexx22llyyxx understands many LaTeX commands. It will translate:
154 · regular text, including mini-commands like ~, '', \@, \TeX, as well
156 as accented characters like \'{a}, and the special cases ?` and !`
157 · title commands like \author, \date, \title, \thanks and the
159 abstract environment
160 · heading commands like \section including starred commands
162 (\section*)
163 · Environments: quote, quotation, and verse; center, flushright, and
165 flushleft
166 · itemize, enumerate, and description environments, and their \item
168 commands. Also, well-behaved nested lists
169 · cross-referencing commands: \ref, \pageref, \label, and \cite
171 · \footnote and \margin
173 · font-changing commands including \em, \emph, \textit, and
175 corresponding commands to change family, size, series, and shape
176 · \input{foo} (or \input{foo.blah}) and \include{foo}. Plain TeX
178 \input command "\input foo.tex" is also supported.
179 · tabular environment, and commands that go inside it like \hline,
181 \cline, and \multicolumn (but see below)
182 · float environments table and table*, as well as \caption commands
184 within them
185 · float environments figure and figure*, as well as graphics
187 inclusion commands \epsf, \epsffile, \epsfbox, \epsfxsize, \epsfig,
188 \psfig, and \includegraphics. Both the graphics and graphicx forms
189 of \includegraphics are supported. Note, however, that many
190 figures will not be translatable into LyX. See the section on "What
191 LyX Can't Handle" below.
192 · thebibliography environment and \bibitem command, as well as
194 BibTeX's \bibliography and \bibliographystyle commands
195 · miscellaneous commands: \hfill, \\, \noindent, \ldots...
197 · documentclass-specific environments (and some commands) which can
199 be translated to LyX layouts
200 · arguments to certain untranslatable commands (e.g. \mbox)
202 Some of this support may not be 100% yet. See below for details
204 tteexx22llyyxx copies math (almost) verbatim from your LaTeX file. Luckily,
206 LyX reads in LaTeX math, so (almost) any math which is supported by LyX
207 should work just fine. A few math commands which are not supported by
208 LyX will be replaced with their equivalents, e.g., \to is converted to
209 \rightarrow. See the section on Syntax Files for more details.
210 tteexx22llyyxx will also copy any preamble commands (i.e., anything before
212 \begin{document}) verbatim, so fancy stuff you've got in your preamble
213 should be conserved in dvi and printed documents, although it will not
214 of course show up in the LyX window. Check Layout->LaTeX Preamble to
215 make sure.
216 WWhhaatt tteexx22llyyxx CCaann''tt HHaannddllee ------ BBuutt iitt''ss OOKK
218 · tabular* tables
220 · spacing commands (\vspace, \pagebreak, \par, ...)
222 · \centering, \raggedleft, \raggedright
224 · \verb and verbatim environment. tteexx22llyyxx is careful to copy exactly
226 in this case, including comments and whitespace.
227 · some unknown (e.g., user-defined) environments and commands
229 tteexx22llyyxx copies unknown commands, along with their arguments, verbatim
231 into the LyX file. Also, if it sees a \begin{foo} where it doesn't
232 recognize the "foo" environment, it will copy verbatim until it sees
233 \end{foo} (unless you use the --rr option). Hopefully, then, most of
234 these unknown commands won't cause tteexx22llyyxx to break; they'll merely
235 require you to do some editing once you've loaded the file up in LyX.
236 That should be less painful than editing either the .tex or the .lyx
237 file using a text editor.
238 WWhhaatt tteexx22llyyxx HHaannddlleess BBaaddllyy ------ aakkaa BBUUGGSS
240 Since tteexx22llyyxx is relatively new, it's got a number of problems. As it
242 matures, these bugs will be squished.
243 · "Exact" copying of unknown environments and commands isn't quite
245 exact. Specifically, newlines and comments may be lost. This will
246 yield ugly LyX, but in almost all cases the output will be the
247 same. However, certain parts of the file will be copied perfectly,
248 including whitespace and comments. This includes: the LaTeX
249 preamble, verbatim environments and \verb commands, and skip
250 blocks.
251 · tteexx22llyyxx translates only a few options to the \documentclass
253 command. (Specifically 1[012]pt,
254 [letter⎪legal⎪executive⎪a4⎪a5⎪b5]paper, [one⎪two]side, landscape,
255 and [one⎪two]column.) Other options are placed in the "options"
256 field in the Layout->Document popup.
257 More importantly, tteexx22llyyxx doesn't translate \usepackage commands,
259 margin commands, \newcommands, or, in fact, anything else from the
260 preamble. It simply copies them into the LaTeX preamble. If you
261 have margin commands in your preamble, then the LyX file will
262 generate the right margins. However, these margins will override
263 any margins you set in the LyX Layout->Paper popup. So you should
264 remove the options from the preamble (Layout->Latex Preamble) to be
265 safe. The same goes for \inputencoding, \pagestyle, etc.
266 · tteexx22llyyxx doesn't handle unicode yet. So if you have an utf8-encoded
268 tex file, some characters might not be (well) supported. Also, the
269 output format of tteexx22llyyxx is that of LyX 1.4 until unicode support
270 is implemented. Thus, newer features cannot be supported natively.
271 · The foil class has a couple of bugs. tteexx22llyyxx may do weird things
273 with optional arguments to \foilhead commands. Also, it may handle
274 \begin{dinglist} incorrectly (although the stuff in the environment
275 should translate normally).
276 Less significant bugs can be found on http://bugzilla.lyx.org.
278 tteexx22llyyxx is hopefully rather robust. As mentioned above, it may not
280 translate your file perfectly, but it shouldn't crash. If it does
281 crash---and the problem is not one of those mentioned above or on
282 http://bugzilla.lyx.org---see the section on Bug Reports.
283 WWhhaatt LLyyXX CCaann''tt HHaannddllee
285 LyX itself is missing a couple of features, such that even if tteexx22llyyxx
287 translates things perfectly, LyX may still have trouble reading it. If
288 you really need these features, you can export your final document as
289 LaTeX, and put them back in. See BUGS for more details on these bugs.
290 · For a number of commands (such as \\), LyX does not support the
292 optional argument. tteexx22llyyxx will automatically discard the optional
293 arguments with a warning to stdout. LyX also ignores the width
294 argument for the thebibliography environment.
295 · Centering (or right or left justifying) works on full paragraphs.
297 · LyX support for tables isn't perfect. For complicated tables, use a
299 "skip" block, so that they will be copied in TeX mode.
300 · The LyX math editor can't handle the AMS-LaTeX math environments
302 align, split, etc. So those environments will be copied in TeX
303 mode. You can change equation* environments to the exactly
304 equivalent displaymath, and then they will be translated correctly.
305 · Lyx does not support clipping or bounding boxes for included
307 graphics files. Therefore, many graphics inclusion commands will
308 be untranslatable, and copied in TeX mode. In certain cases, you
309 might be able to translate the command by hand within LyX---for
310 example, if you included a bounding box but the bounding box is
311 already in the .eps file.
312 LyX only allows figures to have sizes in in,cm, or percentages of
314 \textwidth or \textheight (or \columnwidth). tteexx22llyyxx will translate
315 from other units, like pt or mm, but it cannot translate other
316 lengths (e.g. if you wanted to scale a figure to size \topmargin
317 for some reason). tteexx22llyyxx will copy figures with untranslatable
318 sizes in TeX mode. Again, you might be able to fix that within LyX.
319 TThhee FFuuttuurree ooff tteexx22llyyxx
321 In the future, more commands and environments will be supported by
323 tteexx22llyyxx. Bugs will be eradicated.
324 See the TODO file for details.
326
328 tex2lyx --ddff --rr "myenv" foo.tex > foo.debug
329 The above will create a file foo.lyx from foo.tex, overwriting if
331 necessary. When it finds a \begin{myenv} ... \end{myenv} block, it
332 will translate the stuff within the block, but copy the \begin and \end
333 commands in TeX mode. Finally, I'm going to keep the temporary files
334 around and output lots of debugging information into the file
335 foo.debug.
336 tex2lyx --nn --cc "literate-article" foo.tex
338 The above will change a noweb document into a LyX literate-article
340 document. A user would do this if the noweb document had documentclass
341 article.
342
344 BBuugg RReeppoorrttss
345 If tteexx22llyyxx is crashing or otherwise acting strangely---in ways other
347 than those described in the section on BUGS or on
348 http://bugzilla.lyx.org---then please run tteexx22llyyxx --dd. That will allow
349 you to figure out where in the tex2lyxing process it crashed. That, in
350 turn, will allow you to write a better bug report, which will allow the
351 developers to fix it more quickly and easily.
352 Bug reports should either be posted to http://bugzilla.lyx.org or sent
354 to the LyX developers' mailing list. Its address is currently lyx-
355 devel@lists.lyx.org, but you can check the LyX home page,
356 http://www.lyx.org if that bounces. If you are running tteexx22llyyxx on a
357 huge file, please do not send all of the output in your bug report.
358 Just include the last ten or twenty lines of output, along with the
359 piece of the LaTeX file it crashed on. Or, even better, attach a small
360 but complete file which causes the same problem as your original file.
361 IImmpplleemmeennttaattiioonn DDeettaaiillss::
363 tteexx22llyyxx makes several "passes" in order to translate a TeX file. On
365 each pass, it creates one or two files.
366 Pass 0
368 Before doing anything, read the syntax file (or files).
369 Pass 1a
371 Split preamble (anything before a \begin{document} command) off the
372 rest of the file. It saves the two pieces in separate files. This
373 is necessary because there may be very strange stuff in a preamble.
374 It also ignores anything after the \end{document}, on the
375 assumption that it isn't LaTeX.
376 Pass 1b
378 Translate the preamble. Currently, that just means translating the
379 \documentclass command and copying the rest exactly into the LyX
380 preamble.
381 Once you know what class the document is, read the LyX layout file
383 for that class.
384 Pass 2
386 "Clean" the TeX file, generating slightly stricter LaTeX. This
387 includes:
388 · Change, e.g., x^2 to the equivalent but clearer x^{2}
390 · Removing optional arguments that LyX can't handle (e.g.,
392 from \chapter)
393 · Changing {\em foo} to \emph{foo}, etc. This is necessary
395 because LyX always writes out the non-local forms anyway.
396 This should very rarely make a difference.
397 Pass 3
399 Translate LaTeX text, commands, and environments to LyX.
400 Pass 4
402 Put the two pieces back together, and do some final tweaking, to
403 generate the LyX file
404 If there are any \input or \include commands, tteexx22llyyxx will loop back to
406 the beginning and translate those. It assumes that the included files
407 are the same class as the main file, and that they have no preamble
408 matter. (If you have an \input command in the preamble of a file, the
409 command will be copied exactly into the LaTeX preamble portion of the
410 LyX file, so the included file won't be translated.) So when
411 translating included files, it skips passes 0 and 1.
412 If tteexx22llyyxx doesn't find a file you wanted to include, it will give a
414 warning, but will continue to translate any files it does find.
415 LLaayyoouutt FFiilleess
417 tteexx22llyyxx reads a LyX layout file to know how to handle LaTeX
419 environments and commands which get translated to LyX layouts. This
420 file will include all "normal" non-math environments (i.e., including
421 quote and itemize, but not tabular, minipage, and some other fancy
422 environments), and commands like \section and \title. If you want to
423 tex2lyx a class that doesn't have an existing layout file, then you'll
424 have to create a layout file. But you have to do this anyway, in order
425 to LyX the file, since LyX depends on layout files to know how to
426 display and process its files. Check the LyX documentation for help
427 with this task (which can be hard or easy, depending on the class you
428 want to create a layout file for.) If your class is quite similar to a
429 class that has a layout file, then consider using the --cc option.
430 SSyynnttaaxx FFiilleess
432 tteexx22llyyxx always reads at least one syntax file, called the default
434 syntax file. tteexx22llyyxx will read your personal syntax file if it exists;
435 otherwise it will read the system-wide file. tteexx22llyyxx will read
436 additional syntax files if you specify them with the --ss option. (These
437 extra files should have the same format as the default file, but will
438 tend to be shorter, since they only have to specify extra commands not
439 found in the default file.) A syntax file tells tteexx22llyyxx a few things.
440 First, it describes the syntax of each command, that is, how many
442 required arguments and how many optional arguments the command takes.
443 Knowing this makes it easier for tteexx22llyyxx to copy (in TeX mode) commands
444 that it doesn't know how to translate. The syntax file simply has a
445 command, followed by braces or brackets describing its arguments in the
446 correct order. For example, a syntax file entry \bibitem[]{} means that
447 the \bibitem command takes an optional argument followed by a required
448 one, while the entry \bf means that the \bf command takes no arguments
449 at all. When tteexx22llyyxx encounters a token that it doesn't know how to
450 translate into LyX, it will copy the token---along with the correct
451 number of arguments---exactly. If the token is not in the syntax file,
452 then tteexx22llyyxx just copies as many arguments as it finds. This means
453 that it may copy too much. But since the user can specify additional
454 syntax files, that shouldn't happen often.
455 Some commands that cannot be translated to LyX, like \mbox, have as one
457 of their arguments regular LaTeX text. If the string "translate" is put
458 into an argument of an (untranslatable) command in the syntax file,
459 then tteexx22llyyxx will translate that argument instead of copying it
460 verbatim. So, for example, the default syntax file has
461 \raisebox{}[][]{translate}. This means that the \raisebox command and
462 the first argument (and optional arguments if they exist) are copied in
463 TeX mode, but the last argument (which may contain math, complicated
464 LaTeX, other untranslatable commands, etc.) will be translated into
465 LyX. You can't use "translate" on optional arguments.
466 User-defined syntax files are allowed to define new commands and their
468 syntax, or override the number of arguments for a command given in the
469 default syntax file. (E.g., if you're using a style that gives an extra
470 argument to some command...) However, this will only be useful for
471 commands copied in TeX mode. Commands which are actually translated by
472 tteexx22llyyxx (like \item) have their argument syntax hard-coded. The hard-
473 coded commands are identified in the default syntax file.
474 Second, the syntax file describes any "regular environments". Usually,
476 an entire unknown environment will be copied in TeX mode. If you define
477 a regular environment "foo", though, then only the \begin{foo} and
478 \end{foo} commands will be copied in TeX mode; the text within the
479 environment will be treated (i.e., translated) by tteexx22llyyxx as regular
480 LaTeX, rather than being copied into TeX mode. Don't try to declare
481 "tabbing" and "picture" as regular environments, as the text within
482 those environments will confuse tteexx22llyyxx; use this capability for new
483 environments you create that have plain text or math or simple commands
484 in them. You also can't declare unknown math environments (like
485 equation*) as regular environments, either, since the LyX math editor
486 won't understand them. The names of regular environments appear,
487 whitespace-separated, between \begin{tex2lyxre} and \end{tex2lyxre}
488 statements in the syntax file. (If you have a regular environment which
489 you won't use very often, you can use the --rr option rather than writing
490 a syntax file.)
491
493 tteexx22llyyxx should always explain why it crashes, if it crashes. Some
494 diagnostics may be very technical, though, if they come from the guts
495 of the code. tteexx22llyyxx gives much more information while running if you
496 use the --dd option, but you shouldn't need that unless something goes
497 wrong.
498 When it's finished, tteexx22llyyxx will tell you if it finished successfully
500 or died due to some error.
501
503 Always keep a copy of your original LaTeX files either under a
504 different name or in a different directory. There are a couple ways in
505 which using LyX could lead to overwriting the original LaTeX file.
506 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
508 re-export it, note that it will overwrite the original foo.tex. (LyX
509 will ask you if you want to overwrite it.)
510 If you have the \use_tempdir variable set to false in your lyxrc, then
512 LyX will create its temporary files in your current directory, which
513 means your LaTeX original may be overwritten (without a warning from
514 LyX) when you "view dvi" or print the LyX document.
515
517 MY_LYXDIR/layouts/*.layout
518 User's personal layout files for document classes
519 MY_LYXDIR/syntax.default
521 User's personal syntax file
522 LIBDIR/layouts/*.layout
524 System-wide layout files for document classes
525 LIBDIR/lib/syntax.default
527 System-wide LaTeX syntax file
528 LIBDIR is the system-wide LyX directory, usually something like
530 /usr/local/share/lyx/. MY_LYXDIR is your personal LyX directory,
531 something like .lyx/ in your home directory.
532
534 lyx(1), latex(1)
535
537 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-
538 devel@lists.lyx.org)
5393rd Berkeley Distribution Version 2.9.2.2 2.9.2.2 TEX2LYX(1)