1 .\" Man page for tex2lyx.
2 .\" Use the following command to view man page:
4 .\" tbl tex2lyx.1 | nroff -man | less
6 .TH TEX2LYX 1 "@LYX_DATE@" "Version @VERSION@" "tex2lyx @VERSION@"
8 tex2lyx@version_suffix@ \- translate well-behaved LaTeX into LyX
16 The simplest way to use \fBtex2lyx\fR is via the File->Import->LaTeX
17 (plain) menu item in LyX. That runs \fBtex2lyx\fR on the given file
18 and loads the resulting file into LyX. You should try that first, and
19 call it from the command line only if you need to use more complicated
22 \fBtex2lyx\fR [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
23 [ \fB\-f\fR ] [ \fB\-n\fR ] [ \fB\-c\fR \fItextclass\fR ]
24 [ \fB\-e\fR \fIencoding\fR ]
25 [ \fB\-fixedenc\fR \fIencoding\fR ]
26 [\ \fB\-m\fR \fImodule1\fR[,\fImodule2\fR...]]
27 [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]] [ \fB\-skipchildren\fR ] [
28 \fB\-roundtrip\fR ] [ \fB\-copyfiles\fR ] \fIinputfile\fR [ \fIoutputfile\fR ]
30 .\" \fBtex2lyx\fR [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
31 .\" [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
32 .\" \fIinputfiles\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR
36 Class. By default, when \fBtex2lyx\fR sees a \f(CW\edocumentclass{foo}\fR command, it
37 creates a file of textclass \*[lq]foo\*[rq] and reads the LyX layout file for that class
38 (something like /usr/local/share/lyx/layouts/foo.layout \s-1OR\s0
39 \fB\s-1HOME\s0\fR/.lyx/layouts/foo.layout). Use \fB\-c\fR to declare a different textclass
40 (and read a different layout file).
42 This option is needed if the input file is a LaTeX fragment, with no preamble
43 matter or \f(CW\ebegin{document}\fR command. LyX files created by
44 \fBtex2lyx\fR from partial files can be included in an existing LyX file using
45 the \*[lq]Include LyX File\*[rq] command from LyX's Insert menu.
48 Module. Load the given modules. This is useful if \fBtex2lyx\fR does not
49 automatically detect a given module, but you know the modules that provide
50 some commands or environments that are used in the imported file. The modules
51 are loaded in the given order. If a module \fIfoo\fR depends on a module
52 \fIbar\fR, \fIbar\fR must be given before \fIfoo\fR.
55 Force. \fBtex2lyx\fR will not run if the .lyx file it would generate already exists.
56 Use the \fB\-f\fR option (carefully) to clobber any existing files.
59 Specify the default encoding using the LaTeX name as defined in the encodings
60 file. \fBtex2lyx\fR will use this encoding, but switch if it finds any encoding
61 changing commands in the input.
64 Specify the encoding using the LaTeX name as defined in the encodings file.
65 \fBtex2lyx\fR will ignore any encoding changing commands in the input.
68 Quite mode. \fBtex2lyx\fR will not output any warning messages.
71 Noweb. Translate a noweb (aka literate programming) file. This should be
72 (almost?) equivalent to running \*[lq]noweb2lyx foo.tex foo.lyx\*[rq]. This option
73 requires the \fB\-c\fR option.
76 Do not translate child documents included via \f(CW\einclude\fR and \f(CW\einput\fR.
77 This option is useful if the child documents are generated files and/or contain many
78 commands that \fBtex2lyx\fR does not understand yet.
81 Syntax files. Input (one or more quoted, comma-separated) syntax files to read
82 in addition to the default. (see the section on \fISyntax Files\fR for details).
85 Specify a system directory. Normally, you shouldn't need this. Your LyX system directory is
86 chosen. Cf. the section \f(CWFILES\fR for details.
89 Specify a user directory. Normally, you shouldn't need this. Your LyX user directory is
90 chosen. Cf. the section \f(CWFILES\fR for details.
93 Call LyX to re-export the created output file to LaTeX. If the output file name
94 is not given it is determined automatically to avoid over-writing the input file
95 by accident: If the input file is named \fIfoo.tex\fR the output file will be
96 named \fIfoo.lyx.lyx\fR, and the re-exported file will be named
100 Copy all included files \fBtex2lyx\fR is
101 aware of to the output directory if the output file is located in a different
102 directory than the input file. This is useful if you want to ensure that no
103 included file is overwritten (either in roundtrip mode or by a later export
104 from LyX). Please note that the resulting document may be uncompilable. This
105 happens if it needs files that \fBtex2lyx\fR does not know about and therefore
106 does not copy to the output directory.
109 Help. Print out usage information and quit.
112 Print out the version number and build information and quit.
115 \fBtex2lyx\fR will create a LyX file with the specified name (or
116 \fIdir/foo.lyx\fR if no name was given) from the LaTeX file
119 Suffixes .tex, .ltx and .latex are supported. If \fIinputfile\fR
120 does not exist and does not have one of these suffixes, \fBtex2lyx\fR will try to
121 translate \fIinputfile.tex\fR. (This is similar to the behavior of LaTeX.)
123 The purpose of \fBtex2lyx\fR is to translate \fIwell-behaved\fR LaTeX2e into LyX. If
124 your LaTeX file doesn't compile---or if you do weird things, like redefining
125 standard LaTeX commands---it may choke. LaTeX209 will often be translated
126 correctly, but it's not guaranteed.
128 \fBtex2lyx\fR lacks a few features. However, its main goals are:
130 Get through a well-behaved LaTeX2e file without crashing
132 Translate a lot of that file.
134 Localize the parts that can't be translated and copy them in TeX mode
136 It achieves these main goals pretty well on most files.
138 Here's a more lengthy description of what you should do to translate a LaTeX
143 \fBtex2lyx\fR will inform you of its progress and give any warnings to stderr, so if
144 you don't want any output at all, try (in csh) `tex2lyx foo.tex >& /dev/null'.
145 You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
147 Run LyX (version 2.1 or later) on the resulting .lyx file.
149 In theory, most of the file will have been translated, and anything that's
150 untranslatable will be transferred to TeX code (ERT in LyX-speak). In theory, LyX will be
151 able to read in the file, and to create printed documents from it, because all
152 that untranslated ERT stuff will be passed directly back to LaTeX, which LyX
153 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
154 \fBtex2lyx\fR crashes, or LyX cannot read the generated LyX file, see the \f(CWBUGS\fR section below.
156 Transform things have been inserted as TeX code manually to LyX features, if possible.
158 As mentioned above, you should be able to print out the LyX file even without
159 doing this. However, changing a command in TeX code to the corresponding LyX
160 object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
162 \fBtex2lyx\fR is not guaranteed to create a LyX file which generates exactly the same
163 output as the LaTeX file, although its goal is to achieve this. \fBtex2lyx\fR will generally err
164 on the side of translating less to ensure that the resulting output files are accurate,
165 even though this leads to more TeX code and less \s-1WYSIWYM\s0.
167 \s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
169 I'm sure you were planning on doing this anyway, but it's particularly
170 important after translating a LaTeX document. \fBtex2lyx\fR is better
171 at \*[lq]macro-translating\*[rq] (translating the whole document) than
172 \*[lq]micro-translating\*[rq] (translating every little detail). For example, you may see
173 extra spaces or deleted spaces. Space handling has improved, but it's
175 .SS "What tex2lyx Can Handle"
176 \fBtex2lyx\fR understands many LaTeX commands. It will translate:
178 regular text, including mini-commands like ~, `', \f(CW\e@\fR, \f(CW\eTeX\fR, as well as
179 accented characters like \f(CW\e'{a}\fR, and the special cases ?` and !`
181 title commands like \f(CW\eauthor\fR, \f(CW\edate\fR, \f(CW\etitle\fR, \f(CW\ethanks\fR and the
184 heading commands like \f(CW\esection\fR including starred commands (\f(CW\esection*\fR)
186 Environments: quote, quotation, and verse; center, flushright, and flushleft
188 itemize, enumerate, and description environments, and their \f(CW\eitem\fR commands.
189 Also, well-behaved nested lists
191 cross-referencing commands: \f(CW\eref\fR, \f(CW\epageref\fR, \f(CW\elabel\fR, and \f(CW\ecite\fR
193 \f(CW\efootnote\fR and \f(CW\emargin\fR
195 font-changing commands including \f(CW\eem\fR, \f(CW\eemph\fR, \f(CW\etextit\fR, and
196 corresponding commands to change family, size, series, and shape
198 \f(CW\einput{foo}\fR (or \f(CW\einput{foo.blah}\fR) and \f(CW\einclude{foo}\fR. Plain TeX
199 \f(CW\einput\fR command \*[lq]\f(CW\einput foo.tex\fR\*[rq] is also supported.
201 tabular environment, and commands that go inside it like \f(CW\ehline\fR, \f(CW\ecline\fR,
202 and \f(CW\emulticolumn\fR (but see below)
204 float environments table and table*, as well as \f(CW\ecaption\fR commands within
207 float environments figure and figure*, as well as graphics inclusion commands
208 \eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
209 Both the graphics and graphicx forms of \eincludegraphics are supported.
211 thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
212 \f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
214 miscellaneous commands: \f(CW\ehfill\fR, \f(CW\e\fR\f(CW\e\fR, \f(CW\enoindent\fR, \f(CW\eldots\fR...
216 documentclass-specific environments (and some commands) which can be
217 translated to LyX layouts
219 arguments to certain untranslatable commands (e.g. \f(CW\embox\fR)
221 Some of this support may not be 100% yet. See below for details
223 \fBtex2lyx\fR copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
224 in LaTeX math, so (almost) any math which is supported by LyX should work just
227 \fBtex2lyx\fR will copy any preamble commands (i.e., anything before
228 \f(CW\ebegin{document}\fR) verbatim. Fancy stuff you've got in your preamble
229 should thus be conserved in printed documents, although it will not of
230 course show up in the LyX window. Check Document->Settings->LaTeX Preamble to see the result.
231 .SS "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
233 some spacing commands (\f(CW\ehspace\fR, \f(CW\epagebreak\fR and \f(CW\elinebreak\fR)
235 \f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
237 \f(CW\everb\fR and verbatim environment. \fBtex2lyx\fR is careful to copy \fIexactly\fR in
238 this case, including comments and whitespace.
240 unknown (e.g., user-defined) environments and commands
242 \fBtex2lyx\fR copies unknown commands, along with their arguments, verbatim into the
243 LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
244 \*[lq]foo\*[rq] environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
245 you use the \fB\-r\fR option). Most of these unknown commands
246 won't cause \fBtex2lyx\fR to break; they'll merely require you to do some editing
247 once you've loaded the file up in LyX. That should be less painful than
248 editing either the .tex or the .lyx file using a text editor.
249 .SS "What tex2lyx Handles Badly --- aka \s-1BUGS\s0"
250 Since \fBtex2lyx\fR is relatively new, it's got a number of problems. As it
251 matures, these bugs will be squished.
253 \*[lq]Exact\*[rq] copying of unknown environments and commands isn't quite exact.
254 This will yield ugly LyX, but in almost all cases the output will be the same.
255 However, most parts of the file will be copied perfectly, including whitespace
256 and comments. This includes: the LaTeX preamble, verbatim environments as well as
257 \f(CW\everb\fR commands, and skip blocks.
259 \fBtex2lyx\fR translates only a subset of the document class options to native features.
260 Other options are placed in the \*[lq]options\*[rq] field in the Document->Settings popup.
262 More importantly, \fBtex2lyx\fR doesn't translate \f(CW\enewcommands\fR, unknown
263 \f(CW\eusepackage\fR commands and other unknown code in the preamble. It
264 simply copies that into the LaTeX preamble. If you use special commands, e.g. to
265 specify the text layout in a way that that is not understood by LyX, tex2lyx won't
266 recognize it. Note that these settings will be overwritten if you modify the text
267 layout in LyX's document settings. Better remove these special options from the LaTeX
268 preamble (Document->Settings->LaTeX Preamble) and use the corresponding LyX document
269 settings, if possible.
271 The foil document class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
272 arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
273 incorrectly (although the stuff in the environment should translate normally).
275 All known bugs of \fBtex2lyx\fR can be found on \fI\s-1http://www.lyx.org/trac/wiki/BugTrackerHome\s0\fR.
277 \fBtex2lyx\fR is rather robust. As mentioned above, it may not translate
278 your file perfectly, but the result should be usable and it shouldn't crash. If you encounter
279 problems---and the problem is not one of those mentioned above or on
280 \fI\s-1http://www.lyx.org/trac/wiki/BugTrackerHome\s0\fR---please report the issue as described in the section
281 on \fIBug Reports\fR.
282 .SS "What LyX Can't Handle"
283 LyX itself is missing a couple of features, such that even if \fBtex2lyx\fR translates
284 things perfectly, LyX may still have trouble reading it. If you really need
285 these features, you can export your final document as LaTeX, and put them
286 back in. See \fI\s-1BUGS\s0\fR for more details on these bugs.
288 For a number of commands (such as \f(CW\e\e\fR), LyX does not support the optional argument.
289 \fBtex2lyx\fR will automatically discard the optional arguments with a warning to
290 stdout. LyX also ignores the width argument for the thebibliography
293 LyX support for tables isn't perfect. For complicated tables, use a \*[lq]skip\*[rq]
294 block, so that they will be copied in TeX mode.
296 LyX allows figures to have sizes in the units known to TeX, such as in, cm, etc. It also
297 translates percentages of \etextwidth, \etextheight, \ecolumnwidth, but no other lengths
298 (e.g. if you wanted to scale a figure to size \etopmargin for some reason). \fBtex2lyx\fR
299 will copy figures with untranslatable sizes in TeX mode. Again, you might be able to fix
302 tex2lyx \fB\-f\fR \fB\-r\fR \*[lq]myenv\*[rq] foo.tex
304 The above will create a file foo.lyx from foo.tex, overwriting if
305 necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
306 translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
307 commands in TeX mode.
309 tex2lyx \fB\-n\fR \fB\-c\fR \*[lq]literate-article\*[rq] foo.tex
311 The above will change a noweb document into a LyX literate-article
312 document. A user would do this if the noweb document had documentclass
316 Bugs should be reported to the LyX bug tracker at http://www.lyx.org/trac/wiki/BugTrackerHome. Additionally,
317 you can post a message to the LyX developers' mailing list. Its address is currently
318 lyx-devel@lists.lyx.org. If your message bounces, you can check the LyX home page,
319 http://www.lyx.org/. If you are running \fBtex2lyx\fR on a huge file, please do not send all of the output in
320 your bug report. Just include the last ten or twenty lines of output, along with
321 the piece of the LaTeX file it crashed on. Or, even better, attach a small but
322 complete file which causes the same problem as your original file.
324 \fBtex2lyx\fR reads a LyX layout file to know how to handle LaTeX environments and
325 commands which get translated to LyX layouts. This file will include all
326 \*[lq]normal\*[rq] non-math environments (i.e., including quote and itemize, but not
327 tabular, minipage, and some other fancy environments), and commands like
328 \f(CW\esection\fR and \f(CW\etitle\fR. If you want to tex2lyx a class that doesn't have an
329 existing layout file, then you'll have to create a layout file. But you have
330 to do this anyway, in order to LyX the file, since LyX depends on layout files
331 to know how to display and process its files. Check the LyX documentation for
332 help with this task (which can be hard or easy, depending on the class you
333 want to create a layout file for.) If your class is quite similar to a class
334 that has a layout file, then consider using the \fB\-c\fR option.
336 \fBtex2lyx\fR always reads at least one syntax file, called the default syntax file.
337 \fBtex2lyx\fR will read your personal syntax file if it exists; otherwise it will
338 read the system-wide file. \fBtex2lyx\fR will read additional syntax files if you
339 specify them with the \fB\-s\fR option. (These extra files should have the same
340 format as the default file, but will tend to be shorter, since they only have
341 to specify extra commands not found in the default file.) A syntax file tells
342 \fBtex2lyx\fR a few things.
344 First, it describes the syntax of each command, that is, how many required
345 arguments and how many optional arguments the command takes. Knowing this
346 makes it easier for \fBtex2lyx\fR to copy (in TeX mode) commands that it doesn't
347 know how to translate. The syntax file simply has a command, followed by
348 braces or brackets describing its arguments in the correct order. For example,
349 a syntax file entry \f(CW\ebibitem[]{}\fR means that the \f(CW\ebibitem\fR command takes
350 an optional argument followed by a required one, while the entry \f(CW\ebf\fR
351 means that the \f(CW\ebf\fR command takes no arguments at all. When \fBtex2lyx\fR
352 encounters a token that it doesn't know how to translate into LyX, it will
353 copy the token---along with the correct number of arguments---exactly. If the
354 token is not in the syntax file, then \fBtex2lyx\fR just copies as many arguments
355 as it finds. This means that it may copy too much. But since the user can
356 specify additional syntax files, that shouldn't happen often.
358 Some commands that cannot be translated to LyX, like \f(CW\embox\fR, have as one of
359 their arguments regular LaTeX text. If the string \*[lq]translate\*[rq] is put into an
360 argument of an (untranslatable) command in the syntax file, then \fBtex2lyx\fR will
361 translate that argument instead of copying it verbatim. So, for example, the
362 default syntax file has \f(CW\eraisebox{}[][]{translate}\fR. This means that the
363 \f(CW\eraisebox\fR command and the first argument (and optional arguments if they
364 exist) are copied in TeX mode, but the last argument (which may contain math,
365 complicated LaTeX, other untranslatable commands, etc.) will be translated
366 into LyX. You can't use \*[lq]translate\*[rq] on optional arguments.
368 User-defined syntax files are allowed to define new commands and
369 their syntax, or override the number of arguments for a command given in the
370 default syntax file. (E.g., if you're using a style that gives an extra
371 argument to some command...) However, this will only be useful for commands
372 copied in TeX mode. Commands which are actually translated by \fBtex2lyx\fR (like
373 \f(CW\eitem\fR) have their argument syntax hard-coded. The hard-coded commands are
374 identified in the default syntax file.
376 Second, the syntax file describes any \*[lq]regular environments\*[rq]. Usually, an
377 entire unknown environment will be copied in TeX mode. If you define a regular
378 environment \*[lq]foo\*[rq], though, then only the \f(CW\ebegin{foo}\fR and \f(CW\eend{foo}\fR
379 commands will be copied in TeX mode; the text within the environment will be
380 treated (i.e., translated) by \fBtex2lyx\fR as regular LaTeX, rather than being
381 copied into TeX mode. Don't try to declare \*[lq]tabbing\*[rq] and \*[lq]picture\*[rq] as regular
382 environments, as the text within those environments will confuse \fBtex2lyx\fR; use
383 this capability for new environments you create that have plain text or math
384 or simple commands in them. You also can't declare unknown math environments
385 (like equation*) as regular environments, either, since the LyX math editor
386 won't understand them. The names of regular environments appear,
387 whitespace-separated, between \f(CW\ebegin{tex2lyxre}\fR and \f(CW\eend{tex2lyxre}\fR
388 statements in the syntax file. (If you have a regular environment which you
389 won't use very often, you can use the \fB\-r\fR option rather than writing a
392 Always keep a copy of your original LaTeX files either under a different
393 name or in a different directory. There are a couple ways in which using LyX
394 could lead to overwriting the original LaTeX file.
396 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
397 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
398 you if you want to overwrite it.)
402 can be used to specify which system directory to use.
404 The system directory is determined by searching for the file
405 "chkconfig.ltx". Directories are searched in this order:
407 1) \-sysdir command line parameter
409 2) @LYX_DIR_VER@ environment variable
411 3) Maybe <path of binary>/TOP_SRCDIR/lib
413 4) <path of binary>/../share/<name of binary>/
415 5) hardcoded lyx_dir (at build time: @real_pkgdatadir@)
418 can be used to specify which user directory to use.
420 The user directory is, in order of precedence:
422 1) \-userdir command line parameter
424 2) @LYX_USERDIR_VER@ environment variable
426 3) $HOME/.<name of binary> if no explicit setting is made
429 If \fI\s-1LIBDIR\s0\fR is the system-wide LyX directory and
430 \fI\s-1MY_LYXDIR\s0\fR
431 is your personal LyX directory, then the following files are read by tex2lyx:
432 .IP "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
433 User's personal layout files for document classes
434 .IP "\fI\s-1MY_LYXDIR\s0\fR/syntax.default" 4
435 User's personal syntax file
436 .IP "\fI\s-1MY_LYXDIR\s0\fR/encodings" 4
437 User's personal encoding definition file
438 .IP "\fI\s-1LIBDIR\s0\fR/layouts/*.layout" 4
439 System-wide layout files for document classes
440 .IP "\fI\s-1LIBDIR\s0\fR/lib/syntax.default" 4
441 System-wide LaTeX syntax file
442 .IP "\fI\s-1LIBDIR\s0\fR/lib/encodings" 4
443 System-wide encoding definition file
445 \fIlyx@version_suffix@\fR\|(1), \fIlatex\fR\|(1)
447 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)
projects / lyx.git / blob