2 ''' $RCSfile: tex2lyx.man,v $$Revision: 1.1 $$Date: 2005/07/16 15:18:14 $
4 ''' $Log: tex2lyx.man,v $
5 ''' Revision 1.1 2005/07/16 15:18:14 larsbj
6 ''' drop reLyX like it is hot, and setup to use tex2lyx instead (and remerged po files + no.po small update)
23 .ie \\n(.$>=3 .ne \\$3
39 ''' Set up \*(-- to give an unbreakable dash;
40 ''' string Tr holds user defined translation string.
41 ''' Bell System Logo is used as a dummy character.
47 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
48 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
52 ''' \*(L" and \*(R", except that they are used on ".xx" lines,
53 ''' such as .IP and .SH, which do another additional levels of
54 ''' double-quote interpretation
83 .\" If the F register is turned on, we'll generate
84 .\" index entries out stderr for the following things:
89 .\" X<> Xref (embedded
90 .\" Of course, you have to process the output yourself
91 .\" in some meaninful fashion.
94 .tm Index:\\$1\t\\n%\t"\\$2"
99 .TH TEX2LYX 1 "Version 2.9.2.2 2.9.2.2" "16/Jul/2005" ""
103 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
104 .de CQ \" put $1 in typewriter font
110 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
113 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
114 . \" AM - accent mark definitions
116 . \" fudge factors for nroff and troff
125 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
131 . \" simple accents for nroff and troff
144 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
145 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
146 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
147 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
148 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
149 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
150 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
151 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
152 . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
154 . \" troff and (daisy-wheel) nroff accents
155 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
156 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
157 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
158 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
159 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
160 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
161 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
162 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
163 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
164 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
165 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
166 .ds ae a\h'-(\w'a'u*4/10)'e
167 .ds Ae A\h'-(\w'A'u*4/10)'E
168 .ds oe o\h'-(\w'o'u*4/10)'e
169 .ds Oe O\h'-(\w'O'u*4/10)'E
170 . \" corrections for vroff
171 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
172 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
173 . \" for low resolution devices (crt and lpr)
174 .if \n(.H>23 .if \n(.V>19 \
178 . ds v \h'-1'\o'\(aa\(ga'
194 \fBtex2lyx\fR \- translate well-behaved LaTeX into LyX
196 The simplest way to use \fBtex2lyx\fR is via the File->Import command
197 in LyX. That runs \fBtex2lyx\fR on the given file and loads the
198 resulting file into LyX. You should try that first, and call it from
199 the command line only if you need to use more complicated options.
201 \fBtex2lyx\fR [ \fB\-df\fR ] [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
202 [\fB\-n\fR] [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
203 \fIinputfile\fR [ \fB\-c\fR \fItextclass\fR ]
205 \fBtex2lyx\fR [ \fB\-df\fR ] [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
206 [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
207 \fIinputfiles\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR
209 \fBtex2lyx\fR \fB\-help\fR
212 Class. By default, when \fBtex2lyx\fR sees a \f(CW\edocumentclass{foo}\fR command, it
213 creates a file of textclass \*(L"foo\*(R" and reads the LyX layout file for that class
214 (something like /usr/local/share/lyx/layouts/foo.layout \s-1OR\s0
215 \fB\s-1HOME\s0\fR/.lyx/layouts/foo.layout). Use \fB\-c\fR to declare a different textclass
216 (and read a different layout file).
218 Debug. By default, \fBtex2lyx\fR gives sparse output and deletes the temporary files
219 which were created during translation. Using the \fB\-d\fR flag will create much
220 more output (both to stdout and stderr) and leave the temporary files around.
222 Force. \fBtex2lyx\fR will not run if the .lyx file it would generate already exists.
223 Use the \fB\-f\fR option (carefully) to clobber any existing files.
225 Help. Print out usage information and quit.
227 Noweb. Translate a noweb (aka literate programming) file. This should be
228 (almost?) equivalent to running \*(L"noweb2lyx foo.tex foo.lyx\*(R". This option
229 requires the \fB\-c\fR option.
231 Partial file. The input files are LaTeX fragments, with no preamble matter or
232 \f(CW\ebegin{document}\fR commands. This option requires the \fB\-c\fR option, since there
233 are no \f(CW\edocumentclass\fR commands in the files \fBtex2lyx\fR is translating. When
234 using this option, you can translate more than one file, as long as all files
235 are the same class. The LyX file created by \fBtex2lyx\fR can be included in an
236 existing LyX file using the \*(L"Include LyX File\*(R" command from LyX's Insert menu.
238 Regular environments (see the section on \fISyntax Files\fR). If you give more than one
239 environment, separate them with commas (not spaces). You'll probably need to
240 quote the environment list, especially if it has asterisk environments (foo*)
241 in it. If you use this command often, considering creating a personal syntax
244 Syntax files. Input (one or more quoted, comma-separated) syntax files to read
245 in addition to the default. (see the section on \fISyntax Files\fR for details).
246 .Ip "\fB\-sysdir\fR" 4
247 Specify a system directory. Normally, you shouldn't need this. Your LyX system directory is
248 chosen. Cf. the section \f(CWFILES\fR for details.
249 .Ip "\fB\-userdir\fR" 4
250 Specify a user directory. Normally, you shouldn't need this. Your LyX user directory is
251 chosen. Cf. the section \f(CWFILES\fR for details.
254 \fBtex2lyx\fR will create a LyX file \fIdir/foo.lyx\fR from the LaTeX file
257 Suffixes .tex, .ltx and .latex are supported. If \fIinputfile\fR
258 does not exist and does not have one of these suffixes, \fBtex2lyx\fR will try to
259 translate \fIinputfile.tex\fR. (This is similar to the behavior of LaTeX.)
261 The purpose of \fBtex2lyx\fR is to translate \fIwell-behaved\fR LaTeX2e into LyX. If
262 your LaTeX file doesn't compile---or if you do weird things, like redefining
263 standard LaTeX commands---it may choke. LaTeX209 will often be translated
264 correctly, but it's not guaranteed.
266 \fBtex2lyx\fR has some bugs and lacks a few features. However, its main goals are:
268 Get through a well-behaved LaTeX2e file without crashing
270 Translate a lot of that file.
272 Localize the parts that can't be translated and copy them in TeX mode
274 It achieves these main goals pretty well on most files.
276 There are many improvements that can and will be made to \fBtex2lyx\fR in the
277 future. However, we wanted to get \fBtex2lyx\fR out there early on, to make
278 it easier for new LyX users to read in their existing LaTeX files.
280 Here's a more lengthy description of what you should do to translate a LaTeX
285 \fBtex2lyx\fR will inform you of its progress and give any warnings to stderr, so if
286 you don't want any output at all, try (in csh) \*(L'tex2lyx foo.tex >& /dev/null\*(R'.
287 You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
289 Run LyX (version 1.4 or later) on the resulting .lyx file.
291 In theory, most of the file will have been translated, and anything that's
292 untranslatable will be transferred to TeX mode (ERT in LyX-speak). In theory, LyX will be
293 able to read in the file, and to create printed documents from it, because all
294 that untranslated ERT stuff will be passed directly back to LaTeX, which LyX
295 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
296 \fBtex2lyx\fR crashes, or LyX cannot read the generated LyX file, see the \f(CWBUGS\fR entry elsewhere in this document or the \fI\s-1BUGS\s0\fR file.
298 Change things that are highlighted in ERT (TeX mode) by hand in LyX.
300 As mentioned above, you should be able to print out the LyX file even without
301 doing this. However, changing a command in TeX mode to the corresponding LyX
302 object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
304 \fBtex2lyx\fR is not guaranteed to create a LyX file which generates exactly the same
305 output as the LaTeX file, but it should come close. \fBtex2lyx\fR will generally err
306 on the side of translating less to ensure that dvi or ps files are accurate,
307 even though this leads to more \*(L"evil red text\*(R" and less \s-1WYSIWYM\s0.
309 \s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
311 I'm sure you were planning on doing this anyway, but it's particularly
312 important after translating a LaTeX document. \fBtex2lyx\fR is, at least now, better
313 at \*(L"macro-translating\*(R" (translating the whole document) than
314 \*(L"micro-translating\*(R" (translating every little detail). For example, you may see
315 extra spaces or deleted spaces. Space handling has improved, but it's
317 .Sh "What tex2lyx Can Handle"
318 \fBtex2lyx\fR understands many LaTeX commands. It will translate:
320 regular text, including mini-commands like ~, \*(L'\*(R', \f(CW\e@\fR, \f(CW\eTeX\fR, as well as
321 accented characters like \f(CW\e'{a}\fR, and the special cases ?` and !`
323 title commands like \f(CW\eauthor\fR, \f(CW\edate\fR, \f(CW\etitle\fR, \f(CW\ethanks\fR and the
326 heading commands like \f(CW\esection\fR including starred commands (\f(CW\esection*\fR)
328 Environments: quote, quotation, and verse; center, flushright, and flushleft
330 itemize, enumerate, and description environments, and their \f(CW\eitem\fR commands.
331 Also, well-behaved nested lists
333 cross-referencing commands: \f(CW\eref\fR, \f(CW\epageref\fR, \f(CW\elabel\fR, and \f(CW\ecite\fR
335 \f(CW\efootnote\fR and \f(CW\emargin\fR
337 font-changing commands including \f(CW\eem\fR, \f(CW\eemph\fR, \f(CW\etextit\fR, and
338 corresponding commands to change family, size, series, and shape
340 \f(CW\einput{foo}\fR (or \f(CW\einput{foo.blah}\fR) and \f(CW\einclude{foo}\fR. Plain TeX
341 \f(CW\einput\fR command \*(L"\f(CW\einput foo.tex\fR\*(R" is also supported.
343 tabular environment, and commands that go inside it like \f(CW\ehline\fR, \f(CW\ecline\fR,
344 and \f(CW\emulticolumn\fR (but see below)
346 float environments table and table*, as well as \f(CW\ecaption\fR commands within
349 float environments figure and figure*, as well as graphics inclusion commands
350 \eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
351 Both the graphics and graphicx forms of \eincludegraphics are supported.
352 Note, however, that many figures will not be translatable into LyX. See
353 the section on \*(L"What LyX Can't Handle\*(R" below.
355 thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
356 \f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
358 miscellaneous commands: \f(CW\ehfill\fR, \f(CW\e\fR\f(CW\e\fR, \f(CW\enoindent\fR, \f(CW\eldots\fR...
360 documentclass-specific environments (and some commands) which can be
361 translated to LyX layouts
363 arguments to certain untranslatable commands (e.g. \f(CW\embox\fR)
365 Some of this support may not be 100% yet. See below for details
367 \fBtex2lyx\fR copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
368 in LaTeX math, so (almost) any math which is supported by LyX should work just
369 fine. A few math commands which are not supported by LyX will be replaced with
370 their equivalents, e.g., \f(CW\eto\fR is converted to \f(CW\erightarrow\fR. See
371 the section on \fISyntax Files\fR for more details.
373 \fBtex2lyx\fR will also copy any preamble commands (i.e., anything before
374 \f(CW\ebegin{document}\fR) verbatim, so fancy stuff you've got in your preamble
375 should be conserved in dvi and printed documents, although it will not of
376 course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.
377 .Sh "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
381 spacing commands (\f(CW\evspace\fR, \f(CW\epagebreak\fR, \f(CW\epar\fR, ...)
383 \f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
385 \f(CW\everb\fR and verbatim environment. \fBtex2lyx\fR is careful to copy \fIexactly\fR in
386 this case, including comments and whitespace.
388 some unknown (e.g., user-defined) environments and commands
390 \fBtex2lyx\fR copies unknown commands, along with their arguments, verbatim into the
391 LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
392 \*(L"foo\*(R" environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
393 you use the \fB\-r\fR option). Hopefully, then, most of these unknown commands
394 won't cause \fBtex2lyx\fR to break; they'll merely require you to do some editing
395 once you've loaded the file up in LyX. That should be less painful than
396 editing either the .tex or the .lyx file using a text editor.
397 .Sh "What tex2lyx Handles Badly --- aka \s-1BUGS\s0"
398 Since \fBtex2lyx\fR is relatively new, it's got a number of problems. As it
399 matures, these bugs will be squished.
402 \*(L"Exact\*(R" copying of unknown environments and commands isn't quite exact.
403 Specifically, newlines and comments may be lost. This will yield ugly LyX, but
404 in almost all cases the output will be the same. However, certain parts of the
405 file will be copied perfectly, including whitespace and comments. This
406 includes: the LaTeX preamble, verbatim environments and \f(CW\everb\fR commands, and
409 \fBtex2lyx\fR translates only a few options to the \f(CW\edocumentclass\fR command.
410 (Specifically 1[012]pt, [letter|legal|executive|a4|a5|b5]paper,
411 [one|two]side, landscape, and [one|two]column.) Other options are placed in
412 the \*(L"options\*(R" field in the Layout->Document popup.
414 More importantly, \fBtex2lyx\fR doesn't translate \f(CW\eusepackage\fR commands, margin
415 commands, \f(CW\enewcommands\fR, or, in fact, anything else from the preamble. It
416 simply copies them into the LaTeX preamble. If you have margin commands in
417 your preamble, then the LyX file will generate the right margins. However,
418 these margins will override any margins you set in the LyX Layout->Paper
419 popup. So you should remove the options from the preamble
420 (Layout->Latex Preamble) to be safe. The same goes for \f(CW\einputencoding\fR,
421 \f(CW\epagestyle\fR, etc.
423 \fBtex2lyx\fR doesn't handle unicode yet. So if you have an utf8-encoded tex file, some
424 characters might not be (well) supported. Also, the output format of \fBtex2lyx\fR
425 is that of LyX 1.4 until unicode support is implemented. Thus, newer features cannot be
428 The foil class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
429 arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
430 incorrectly (although the stuff in the environment should translate normally).
432 Less significant bugs can be found on \fI\s-1http://bugzilla.lyx.org\s0\fR.
434 \fBtex2lyx\fR is hopefully rather robust. As mentioned above, it may not translate
435 your file perfectly, but it shouldn't crash. If it does crash---and the
436 problem is not one of those mentioned above or on \fI\s-1http://bugzilla.lyx.org\s0\fR---see
437 the section on \fIBug Reports\fR.
438 .Sh "What LyX Can't Handle"
439 LyX itself is missing a couple of features, such that even if \fBtex2lyx\fR translates
440 things perfectly, LyX may still have trouble reading it. If you really need
441 these features, you can export your final document as LaTeX, and put them
442 back in. See \fI\s-1BUGS\s0\fR for more details on these bugs.
444 For a number of commands (such as \f(CW\e\e\fR), LyX does not support the optional argument.
445 \fBtex2lyx\fR will automatically discard the optional arguments with a warning to
446 stdout. LyX also ignores the width argument for the thebibliography
449 Centering (or right or left justifying) works on full paragraphs.
451 LyX support for tables isn't perfect. For complicated tables, use a \*(L"skip\*(R"
452 block, so that they will be copied in TeX mode.
454 The LyX math editor can't handle the \s-1AMS\s0\-LaTeX math environments align, split,
455 etc. So those environments will be copied in TeX mode. You can change
456 equation* environments to the exactly equivalent displaymath, and then they
457 will be translated correctly.
459 Lyx does not support clipping or bounding boxes for included graphics files.
460 Therefore, many graphics inclusion commands will be untranslatable, and
461 copied in TeX mode. In certain cases, you might be able to translate the
462 command by hand within LyX---for example, if you included a bounding box but
463 the bounding box is already in the .eps file.
465 LyX only allows figures to have sizes in in,cm, or percentages of \etextwidth
466 or \etextheight (or \ecolumnwidth). \fBtex2lyx\fR will translate from other units, like
467 pt or mm, but it cannot translate other lengths (e.g. if you wanted to scale a
468 figure to size \etopmargin for some reason). \fBtex2lyx\fR will copy figures with
469 untranslatable sizes in TeX mode. Again, you might be able to fix that within
471 .Sh "The Future of tex2lyx"
472 In the future, more commands and environments will be supported by \fBtex2lyx\fR.
473 Bugs will be eradicated.
475 See the \s-1TODO\s0 file for details.
477 tex2lyx \fB\-df\fR \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
479 The above will create a file foo.lyx from foo.tex, overwriting if
480 necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
481 translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
482 commands in TeX mode. Finally, I'm going to keep the temporary files around
483 and output lots of debugging information into the file foo.debug.
485 tex2lyx \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
487 The above will change a noweb document into a LyX literate-article
488 document. A user would do this if the noweb document had documentclass
492 If \fBtex2lyx\fR is crashing or otherwise acting strangely---in ways
493 other than those described in the section on \fI\s-1BUGS\s0\fR or on
494 \fI\s-1http://bugzilla.lyx.org\s0\fR---then please run
495 \fBtex2lyx \-d\fR. That will allow you to figure out where in the tex2lyxing process
496 it crashed. That, in turn, will allow you to write a better bug report, which
497 will allow the developers to fix it more quickly and easily.
499 Bug reports should either be posted to http://bugzilla.lyx.org or sent to the
500 LyX developers\*(R' mailing list. Its address is currently lyx-devel@lists.lyx.org,
501 but you can check the LyX home page, http://www.lyx.org if that bounces. If you
502 are running \fBtex2lyx\fR on a huge file, please do not send all of the output in
503 your bug report. Just include the last ten or twenty lines of output, along with
504 the piece of the LaTeX file it crashed on. Or, even better, attach a small but
505 complete file which causes the same problem as your original file.
506 .Sh "Implementation Details:"
507 \fBtex2lyx\fR makes several \*(L"passes\*(R" in order to translate a TeX file. On each pass,
508 it creates one or two files.
510 Before doing anything, read the syntax file (or files).
512 Split preamble (anything before a \f(CW\ebegin{document}\fR command) off the rest
513 of the file. It saves the two pieces in separate files. This is necessary
514 because there may be very strange stuff in a preamble. It also ignores
515 anything after the \f(CW\eend{document}\fR, on the assumption that it isn't LaTeX.
517 Translate the preamble. Currently, that just means translating the
518 \f(CW\edocumentclass\fR command and copying the rest exactly into the LyX preamble.
520 Once you know what class the document is, read the LyX layout file for that
523 \*(L"Clean\*(R" the TeX file, generating slightly stricter LaTeX. This includes:
525 Change, e.g., x^2 to the equivalent but clearer x^{2}
527 Removing optional arguments that LyX can't handle (e.g., from \f(CW\echapter\fR)
529 Changing \f(CW{\eem foo}\fR to \f(CW\eemph{foo}\fR, etc. This is necessary because LyX
530 always writes out the non-local forms anyway. This should very rarely make a
533 Translate LaTeX text, commands, and environments to LyX.
535 Put the two pieces back together, and do some final tweaking, to generate the
538 If there are any \f(CW\einput\fR or \f(CW\einclude\fR commands, \fBtex2lyx\fR will loop back to
539 the beginning and translate those. It assumes that the included files are the
540 same class as the main file, and that they have no preamble matter. (If you
541 have an \f(CW\einput\fR command in the preamble of a file, the command will be
542 copied exactly into the LaTeX preamble portion of the LyX file, so the
543 included file won't be translated.) So when translating included files, it
544 skips passes 0 and 1.
546 If \fBtex2lyx\fR doesn't find a file you wanted to include, it will give a warning,
547 but will continue to translate any files it does find.
549 \fBtex2lyx\fR reads a LyX layout file to know how to handle LaTeX environments and
550 commands which get translated to LyX layouts. This file will include all
551 \*(L"normal\*(R" non-math environments (i.e., including quote and itemize, but not
552 tabular, minipage, and some other fancy environments), and commands like
553 \f(CW\esection\fR and \f(CW\etitle\fR. If you want to tex2lyx a class that doesn't have an
554 existing layout file, then you'll have to create a layout file. But you have
555 to do this anyway, in order to LyX the file, since LyX depends on layout files
556 to know how to display and process its files. Check the LyX documentation for
557 help with this task (which can be hard or easy, depending on the class you
558 want to create a layout file for.) If your class is quite similar to a class
559 that has a layout file, then consider using the \fB\-c\fR option.
561 \fBtex2lyx\fR always reads at least one syntax file, called the default syntax file.
562 \fBtex2lyx\fR will read your personal syntax file if it exists; otherwise it will
563 read the system-wide file. \fBtex2lyx\fR will read additional syntax files if you
564 specify them with the \fB\-s\fR option. (These extra files should have the same
565 format as the default file, but will tend to be shorter, since they only have
566 to specify extra commands not found in the default file.) A syntax file tells
567 \fBtex2lyx\fR a few things.
569 First, it describes the syntax of each command, that is, how many required
570 arguments and how many optional arguments the command takes. Knowing this
571 makes it easier for \fBtex2lyx\fR to copy (in TeX mode) commands that it doesn't
572 know how to translate. The syntax file simply has a command, followed by
573 braces or brackets describing its arguments in the correct order. For example,
574 a syntax file entry \f(CW\ebibitem[]{}\fR means that the \f(CW\ebibitem\fR command takes
575 an optional argument followed by a required one, while the entry \f(CW\ebf\fR
576 means that the \f(CW\ebf\fR command takes no arguments at all. When \fBtex2lyx\fR
577 encounters a token that it doesn't know how to translate into LyX, it will
578 copy the token---along with the correct number of arguments---exactly. If the
579 token is not in the syntax file, then \fBtex2lyx\fR just copies as many arguments
580 as it finds. This means that it may copy too much. But since the user can
581 specify additional syntax files, that shouldn't happen often.
583 Some commands that cannot be translated to LyX, like \f(CW\embox\fR, have as one of
584 their arguments regular LaTeX text. If the string \*(L"translate\*(R" is put into an
585 argument of an (untranslatable) command in the syntax file, then \fBtex2lyx\fR will
586 translate that argument instead of copying it verbatim. So, for example, the
587 default syntax file has \f(CW\eraisebox{}[][]{translate}\fR. This means that the
588 \f(CW\eraisebox\fR command and the first argument (and optional arguments if they
589 exist) are copied in TeX mode, but the last argument (which may contain math,
590 complicated LaTeX, other untranslatable commands, etc.) will be translated
591 into LyX. You can't use \*(L"translate\*(R" on optional arguments.
593 User-defined syntax files are allowed to define new commands and
594 their syntax, or override the number of arguments for a command given in the
595 default syntax file. (E.g., if you're using a style that gives an extra
596 argument to some command...) However, this will only be useful for commands
597 copied in TeX mode. Commands which are actually translated by \fBtex2lyx\fR (like
598 \f(CW\eitem\fR) have their argument syntax hard-coded. The hard-coded commands are
599 identified in the default syntax file.
601 Second, the syntax file describes any \*(L"regular environments\*(R". Usually, an
602 entire unknown environment will be copied in TeX mode. If you define a regular
603 environment \*(L"foo\*(R", though, then only the \f(CW\ebegin{foo}\fR and \f(CW\eend{foo}\fR
604 commands will be copied in TeX mode; the text within the environment will be
605 treated (i.e., translated) by \fBtex2lyx\fR as regular LaTeX, rather than being
606 copied into TeX mode. Don't try to declare \*(L"tabbing\*(R" and \*(L"picture\*(R" as regular
607 environments, as the text within those environments will confuse \fBtex2lyx\fR; use
608 this capability for new environments you create that have plain text or math
609 or simple commands in them. You also can't declare unknown math environments
610 (like equation*) as regular environments, either, since the LyX math editor
611 won't understand them. The names of regular environments appear,
612 whitespace-separated, between \f(CW\ebegin{tex2lyxre}\fR and \f(CW\eend{tex2lyxre}\fR
613 statements in the syntax file. (If you have a regular environment which you
614 won't use very often, you can use the \fB\-r\fR option rather than writing a
617 \fBtex2lyx\fR should always explain why it crashes, if it crashes. Some diagnostics
618 may be very technical, though, if they come from the guts of the code.
619 \fBtex2lyx\fR gives much more information while running if you use the \fB\-d\fR option,
620 but you shouldn't need that unless something goes wrong.
622 When it's finished, \fBtex2lyx\fR will tell you if it finished successfully or
623 died due to some error.
625 Always keep a copy of your original LaTeX files either under a different
626 name or in a different directory. There are a couple ways in which using LyX
627 could lead to overwriting the original LaTeX file.
629 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
630 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
631 you if you want to overwrite it.)
633 If you have the \euse_tempdir variable set to false in your lyxrc, then LyX
634 will create its temporary files in your current directory, which means your
635 LaTeX original may be overwritten (without a warning from LyX) when you \*(L"view
636 dvi\*(R" or print the LyX document.
638 .Ip "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
639 User's personal layout files for document classes
640 .Ip "\fI\s-1MY_LYXDIR\s0\fR/syntax.default" 4
641 User's personal syntax file
642 .Ip "\fI\s-1LIBDIR\s0\fR/layouts/*.layout" 4
643 System-wide layout files for document classes
644 .Ip "\fI\s-1LIBDIR\s0\fR/lib/syntax.default" 4
645 System-wide LaTeX syntax file
647 \fI\s-1LIBDIR\s0\fR is the system-wide LyX directory, usually something like
648 /usr/local/share/lyx/. \fI\s-1MY_LYXDIR\s0\fR is your personal LyX directory, something
649 like .lyx/ in your home directory.
651 \fIlyx\fR\|(1), \fIlatex\fR\|(1)
653 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)
656 .IX Title "TEX2LYX 1"
657 .IX Name "B<tex2lyx> - translate well-behaved LaTeX into LyX"
661 .IX Header "SYNOPSIS"
671 .IX Item "\fB\-help\fR"
683 .IX Header "DESCRIPTION"
685 .IX Subsection "Introduction"
693 .IX Subsection "Usage"
703 .IX Subsection "What tex2lyx Can Handle"
737 .IX Subsection "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
751 .IX Subsection "What tex2lyx Handles Badly --- aka \s-1BUGS\s0"
759 .IX Subsection "What LyX Can't Handle"
771 .IX Subsection "The Future of tex2lyx"
773 .IX Header "EXAMPLES"
777 .IX Subsection "Bug Reports"
779 .IX Subsection "Implementation Details:"
799 .IX Subsection "Layout Files"
801 .IX Subsection "Syntax Files"
803 .IX Subsection "Miscellaneous"
805 .IX Header "DIAGNOSTICS"
807 .IX Header "WARNINGS"
811 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout"
813 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/syntax.default"
815 .IX Item "\fI\s-1LIBDIR\s0\fR/layouts/*.layout"
817 .IX Item "\fI\s-1LIBDIR\s0\fR/lib/syntax.default"
819 .IX Header "SEE ALSO"
projects / lyx.git / blob