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->LaTeX (plain) menu item
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 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 Here's a more lengthy description of what you should do to translate a LaTeX
281 \fBtex2lyx\fR will inform you of its progress and give any warnings to stderr, so if
282 you don't want any output at all, try (in csh) \*(L'tex2lyx foo.tex >& /dev/null\*(R'.
283 You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
285 Run LyX (version 1.4 or later) on the resulting .lyx file.
287 In theory, most of the file will have been translated, and anything that's
288 untranslatable will be transferred to TeX code (ERT in LyX-speak). In theory, LyX will be
289 able to read in the file, and to create printed documents from it, because all
290 that untranslated ERT stuff will be passed directly back to LaTeX, which LyX
291 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
292 \fBtex2lyx\fR crashes, or LyX cannot read the generated LyX file, see the \f(CWBUGS\fR section below.
294 Transform things have been inserted as TeX code manually to LyX features, if possible.
296 As mentioned above, you should be able to print out the LyX file even without
297 doing this. However, changing a command in TeX code to the corresponding LyX
298 object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
300 \fBtex2lyx\fR is not guaranteed to create a LyX file which generates exactly the same
301 output as the LaTeX file, although its goal is to achieve this. \fBtex2lyx\fR will generally err
302 on the side of translating less to ensure that the resulting output files are accurate,
303 even though this leads to more TeX code and less \s-1WYSIWYM\s0.
305 \s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
307 I'm sure you were planning on doing this anyway, but it's particularly
308 important after translating a LaTeX document. \fBtex2lyx\fR is better
309 at \*(L"macro-translating\*(R" (translating the whole document) than
310 \*(L"micro-translating\*(R" (translating every little detail). For example, you may see
311 extra spaces or deleted spaces. Space handling has improved, but it's
313 .Sh "What tex2lyx Can Handle"
314 \fBtex2lyx\fR understands many LaTeX commands. It will translate:
316 regular text, including mini-commands like ~, \*(L'\*(R', \f(CW\e@\fR, \f(CW\eTeX\fR, as well as
317 accented characters like \f(CW\e'{a}\fR, and the special cases ?` and !`
319 title commands like \f(CW\eauthor\fR, \f(CW\edate\fR, \f(CW\etitle\fR, \f(CW\ethanks\fR and the
322 heading commands like \f(CW\esection\fR including starred commands (\f(CW\esection*\fR)
324 Environments: quote, quotation, and verse; center, flushright, and flushleft
326 itemize, enumerate, and description environments, and their \f(CW\eitem\fR commands.
327 Also, well-behaved nested lists
329 cross-referencing commands: \f(CW\eref\fR, \f(CW\epageref\fR, \f(CW\elabel\fR, and \f(CW\ecite\fR
331 \f(CW\efootnote\fR and \f(CW\emargin\fR
333 font-changing commands including \f(CW\eem\fR, \f(CW\eemph\fR, \f(CW\etextit\fR, and
334 corresponding commands to change family, size, series, and shape
336 \f(CW\einput{foo}\fR (or \f(CW\einput{foo.blah}\fR) and \f(CW\einclude{foo}\fR. Plain TeX
337 \f(CW\einput\fR command \*(L"\f(CW\einput foo.tex\fR\*(R" is also supported.
339 tabular environment, and commands that go inside it like \f(CW\ehline\fR, \f(CW\ecline\fR,
340 and \f(CW\emulticolumn\fR (but see below)
342 float environments table and table*, as well as \f(CW\ecaption\fR commands within
345 float environments figure and figure*, as well as graphics inclusion commands
346 \eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
347 Both the graphics and graphicx forms of \eincludegraphics are supported.
349 thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
350 \f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
352 miscellaneous commands: \f(CW\ehfill\fR, \f(CW\e\fR\f(CW\e\fR, \f(CW\enoindent\fR, \f(CW\eldots\fR...
354 documentclass-specific environments (and some commands) which can be
355 translated to LyX layouts
357 arguments to certain untranslatable commands (e.g. \f(CW\embox\fR)
359 Some of this support may not be 100% yet. See below for details
361 \fBtex2lyx\fR copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
362 in LaTeX math, so (almost) any math which is supported by LyX should work just
365 \fBtex2lyx\fR will copy any preamble commands (i.e., anything before
366 \f(CW\ebegin{document}\fR) verbatim. Fancy stuff you've got in your preamble
367 should thus be conserved in printed documents, although it will not of
368 course show up in the LyX window. Check Document->Settings->LaTeX Preamble to see the result.
369 .Sh "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
373 some spacing commands (\f(CW\ehspace\fR, \f(CW\epagebreak\fR and \f(CW\elinebreak\fR)
375 \f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
377 \f(CW\everb\fR and verbatim environment. \fBtex2lyx\fR is careful to copy \fIexactly\fR in
378 this case, including comments and whitespace.
380 unknown (e.g., user-defined) environments and commands
382 \fBtex2lyx\fR copies unknown commands, along with their arguments, verbatim into the
383 LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
384 \*(L"foo\*(R" environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
385 you use the \fB\-r\fR option). Most of these unknown commands
386 won't cause \fBtex2lyx\fR to break; they'll merely require you to do some editing
387 once you've loaded the file up in LyX. That should be less painful than
388 editing either the .tex or the .lyx file using a text editor.
389 .Sh "What tex2lyx Handles Badly --- aka \s-1BUGS\s0"
390 Since \fBtex2lyx\fR is relatively new, it's got a number of problems. As it
391 matures, these bugs will be squished.
394 \*(L"Exact\*(R" copying of unknown environments and commands isn't quite exact.
395 This will yield ugly LyX, but in almost all cases the output will be the same.
396 However, most parts of the file will be copied perfectly, including whitespace
397 and comments. This includes: the LaTeX preamble, verbatim environments as well as
398 \f(CW\everb\fR commands, and skip blocks.
400 \fBtex2lyx\fR translates only a subset of the document class options to native features.
401 Other options are placed in the \*(L"options\*(R" field in the Document->Settings popup.
403 More importantly, \fBtex2lyx\fR doesn't translate \f(CW\enewcommands\fR, unknown
404 \f(CW\eusepackage\fR commands and other unknown code in the preamble. It
405 simply copies that into the LaTeX preamble. If you use special commands, e.g. to
406 specify the text layout in a way that that is not understood by LyX, tex2lyx won't
407 recognize it. Note that these settings will be overwritten if you modify the text
408 layout in LyX's document settings. Better remove these special options from the LaTeX
409 preamble (Document->Settings->LaTeX Preamble) and use the corresponding LyX document
410 settings, if possible.
412 \fBtex2lyx\fR doesn't handle unicode yet. So if you have an utf8-encoded tex file, some
413 characters might not be (well) supported. Also, the output format of \fBtex2lyx\fR
414 remains that of LyX 1.4 until unicode support is implemented. This disallows us from
415 supporting newer features natively, which is in fact the most severe issue in current
418 The foil document class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
419 arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
420 incorrectly (although the stuff in the environment should translate normally).
422 All known bugs of \fBtex2lyx\fR can be found on \fI\s-1http://bugzilla.lyx.org\s0\fR.
424 \fBtex2lyx\fR is rather robust. As mentioned above, it may not translate
425 your file perfectly, but the result should be usable and it shouldn't crash. If you encounter
426 problems---and the problem is not one of those mentioned above or on
427 \fI\s-1http://bugzilla.lyx.org\s0\fR---please report the issue as described in the section
428 on \fIBug Reports\fR.
429 .Sh "What LyX Can't Handle"
430 LyX itself is missing a couple of features, such that even if \fBtex2lyx\fR translates
431 things perfectly, LyX may still have trouble reading it. If you really need
432 these features, you can export your final document as LaTeX, and put them
433 back in. See \fI\s-1BUGS\s0\fR for more details on these bugs.
435 For a number of commands (such as \f(CW\e\e\fR), LyX does not support the optional argument.
436 \fBtex2lyx\fR will automatically discard the optional arguments with a warning to
437 stdout. LyX also ignores the width argument for the thebibliography
440 LyX support for tables isn't perfect. For complicated tables, use a \*(L"skip\*(R"
441 block, so that they will be copied in TeX mode.
443 LyX allows figures to have sizes in the units known to TeX, such as in, cm, etc. It also
444 translates percentages of \etextwidth, \etextheight, \ecolumnwidth, but no other lengths
445 (e.g. if you wanted to scale a figure to size \etopmargin for some reason). \fBtex2lyx\fR
446 will copy figures with untranslatable sizes in TeX mode. Again, you might be able to fix
449 .Sh "The Future of tex2lyx"
450 \fBtex2lyx\fR is actively maintained. Commands and environments will be added in the future.
451 Bugs will be eradicated. The most important task will be to make \fBtex2lyx\fR unicode
454 tex2lyx \fB\-df\fR \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
456 The above will create a file foo.lyx from foo.tex, overwriting if
457 necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
458 translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
459 commands in TeX mode. Finally, it's going to keep the temporary files around
460 and output lots of debugging information into the file foo.debug.
462 tex2lyx \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
464 The above will change a noweb document into a LyX literate-article
465 document. A user would do this if the noweb document had documentclass
469 If \fBtex2lyx\fR is crashing or otherwise acting strangely---in ways
470 other than those described in the section on \fI\s-1BUGS\s0\fR or on
471 \fI\s-1http://bugzilla.lyx.org\s0\fR---then please run
472 \fBtex2lyx \-d\fR. That will allow you to figure out where in the tex2lyxing process
473 it crashed. That, in turn, will allow you to write a better bug report, which
474 will allow the developers to fix it more quickly and easily.
476 Bugs should be reported to the LyX bug tracker at http://bugzilla.lyx.org. Additionally,
477 you can post a message to the LyX developers\*(R' mailing list. Its address is currently
478 lyx-devel@lists.lyx.org. If your message bounces, you can check the LyX home page,
479 http://www.lyx.org. If you are running \fBtex2lyx\fR on a huge file, please do not send all of the output in
480 your bug report. Just include the last ten or twenty lines of output, along with
481 the piece of the LaTeX file it crashed on. Or, even better, attach a small but
482 complete file which causes the same problem as your original file.
483 .Sh "Implementation Details:"
484 \fBtex2lyx\fR makes several \*(L"passes\*(R" in order to translate a TeX file. On each pass,
485 it creates one or two files.
487 Before doing anything, read the syntax file (or files).
489 Split preamble (anything before a \f(CW\ebegin{document}\fR command) off the rest
490 of the file. It saves the two pieces in separate files. This is necessary
491 because there may be very strange stuff in a preamble. It also ignores
492 anything after the \f(CW\eend{document}\fR, on the assumption that it isn't LaTeX.
494 Translate the preamble. Currently, that just means translating the
495 \f(CW\edocumentclass\fR command and copying the rest exactly into the LyX preamble.
497 Once you know what class the document is, read the LyX layout file for that
500 \*(L"Clean\*(R" the TeX file, generating slightly stricter LaTeX. This includes:
502 Change, e.g., x^2 to the equivalent but clearer x^{2}
504 Removing optional arguments that LyX can't handle (e.g., from \f(CW\echapter\fR)
506 Changing \f(CW{\eem foo}\fR to \f(CW\eemph{foo}\fR, etc. This is necessary because LyX
507 always writes out the non-local forms anyway. This should very rarely make a
510 Translate LaTeX text, commands, and environments to LyX.
512 Put the two pieces back together, and do some final tweaking, to generate the
515 If there are any \f(CW\einput\fR or \f(CW\einclude\fR commands, \fBtex2lyx\fR will loop back to
516 the beginning and translate those. It assumes that the included files are the
517 same class as the main file, and that they have no preamble matter. (If you
518 have an \f(CW\einput\fR command in the preamble of a file, the command will be
519 copied exactly into the LaTeX preamble portion of the LyX file, so the
520 included file won't be translated.) So when translating included files, it
521 skips passes 0 and 1.
523 If \fBtex2lyx\fR doesn't find a file you wanted to include, it will give a warning,
524 but will continue to translate any files it does find.
526 \fBtex2lyx\fR reads a LyX layout file to know how to handle LaTeX environments and
527 commands which get translated to LyX layouts. This file will include all
528 \*(L"normal\*(R" non-math environments (i.e., including quote and itemize, but not
529 tabular, minipage, and some other fancy environments), and commands like
530 \f(CW\esection\fR and \f(CW\etitle\fR. If you want to tex2lyx a class that doesn't have an
531 existing layout file, then you'll have to create a layout file. But you have
532 to do this anyway, in order to LyX the file, since LyX depends on layout files
533 to know how to display and process its files. Check the LyX documentation for
534 help with this task (which can be hard or easy, depending on the class you
535 want to create a layout file for.) If your class is quite similar to a class
536 that has a layout file, then consider using the \fB\-c\fR option.
538 \fBtex2lyx\fR always reads at least one syntax file, called the default syntax file.
539 \fBtex2lyx\fR will read your personal syntax file if it exists; otherwise it will
540 read the system-wide file. \fBtex2lyx\fR will read additional syntax files if you
541 specify them with the \fB\-s\fR option. (These extra files should have the same
542 format as the default file, but will tend to be shorter, since they only have
543 to specify extra commands not found in the default file.) A syntax file tells
544 \fBtex2lyx\fR a few things.
546 First, it describes the syntax of each command, that is, how many required
547 arguments and how many optional arguments the command takes. Knowing this
548 makes it easier for \fBtex2lyx\fR to copy (in TeX mode) commands that it doesn't
549 know how to translate. The syntax file simply has a command, followed by
550 braces or brackets describing its arguments in the correct order. For example,
551 a syntax file entry \f(CW\ebibitem[]{}\fR means that the \f(CW\ebibitem\fR command takes
552 an optional argument followed by a required one, while the entry \f(CW\ebf\fR
553 means that the \f(CW\ebf\fR command takes no arguments at all. When \fBtex2lyx\fR
554 encounters a token that it doesn't know how to translate into LyX, it will
555 copy the token---along with the correct number of arguments---exactly. If the
556 token is not in the syntax file, then \fBtex2lyx\fR just copies as many arguments
557 as it finds. This means that it may copy too much. But since the user can
558 specify additional syntax files, that shouldn't happen often.
560 Some commands that cannot be translated to LyX, like \f(CW\embox\fR, have as one of
561 their arguments regular LaTeX text. If the string \*(L"translate\*(R" is put into an
562 argument of an (untranslatable) command in the syntax file, then \fBtex2lyx\fR will
563 translate that argument instead of copying it verbatim. So, for example, the
564 default syntax file has \f(CW\eraisebox{}[][]{translate}\fR. This means that the
565 \f(CW\eraisebox\fR command and the first argument (and optional arguments if they
566 exist) are copied in TeX mode, but the last argument (which may contain math,
567 complicated LaTeX, other untranslatable commands, etc.) will be translated
568 into LyX. You can't use \*(L"translate\*(R" on optional arguments.
570 User-defined syntax files are allowed to define new commands and
571 their syntax, or override the number of arguments for a command given in the
572 default syntax file. (E.g., if you're using a style that gives an extra
573 argument to some command...) However, this will only be useful for commands
574 copied in TeX mode. Commands which are actually translated by \fBtex2lyx\fR (like
575 \f(CW\eitem\fR) have their argument syntax hard-coded. The hard-coded commands are
576 identified in the default syntax file.
578 Second, the syntax file describes any \*(L"regular environments\*(R". Usually, an
579 entire unknown environment will be copied in TeX mode. If you define a regular
580 environment \*(L"foo\*(R", though, then only the \f(CW\ebegin{foo}\fR and \f(CW\eend{foo}\fR
581 commands will be copied in TeX mode; the text within the environment will be
582 treated (i.e., translated) by \fBtex2lyx\fR as regular LaTeX, rather than being
583 copied into TeX mode. Don't try to declare \*(L"tabbing\*(R" and \*(L"picture\*(R" as regular
584 environments, as the text within those environments will confuse \fBtex2lyx\fR; use
585 this capability for new environments you create that have plain text or math
586 or simple commands in them. You also can't declare unknown math environments
587 (like equation*) as regular environments, either, since the LyX math editor
588 won't understand them. The names of regular environments appear,
589 whitespace-separated, between \f(CW\ebegin{tex2lyxre}\fR and \f(CW\eend{tex2lyxre}\fR
590 statements in the syntax file. (If you have a regular environment which you
591 won't use very often, you can use the \fB\-r\fR option rather than writing a
594 \fBtex2lyx\fR should always explain why it crashes, if it crashes. Some diagnostics
595 may be very technical, though, if they come from the guts of the code.
596 \fBtex2lyx\fR gives much more information while running if you use the \fB\-d\fR option,
597 but you shouldn't need that unless something goes wrong.
599 When it's finished, \fBtex2lyx\fR will tell you if it finished successfully or
600 died due to some error.
602 Always keep a copy of your original LaTeX files either under a different
603 name or in a different directory. There are a couple ways in which using LyX
604 could lead to overwriting the original LaTeX file.
606 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
607 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
608 you if you want to overwrite it.)
610 If you have the \euse_tempdir variable set to false in your lyxrc (or did not
611 have defined a temporary directory path in LyX's preferences, respectively),
612 LyX will create its temporary files in your current directory, which means your
613 LaTeX original may be overwritten (without a warning from LyX) when you view
614 or export the LyX document.
616 .Ip "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
617 User's personal layout files for document classes
618 .Ip "\fI\s-1MY_LYXDIR\s0\fR/syntax.default" 4
619 User's personal syntax file
620 .Ip "\fI\s-1LIBDIR\s0\fR/layouts/*.layout" 4
621 System-wide layout files for document classes
622 .Ip "\fI\s-1LIBDIR\s0\fR/lib/syntax.default" 4
623 System-wide LaTeX syntax file
625 \fI\s-1LIBDIR\s0\fR is the system-wide LyX directory, usually something like
626 /usr/local/share/lyx/. \fI\s-1MY_LYXDIR\s0\fR is your personal LyX directory, something
627 like .lyx/ in your home directory.
629 \fIlyx\fR\|(1), \fIlatex\fR\|(1)
631 tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)
634 .IX Title "TEX2LYX 1"
635 .IX Name "B<tex2lyx> - translate well-behaved LaTeX into LyX"
639 .IX Header "SYNOPSIS"
649 .IX Item "\fB\-help\fR"
661 .IX Header "DESCRIPTION"
663 .IX Subsection "Introduction"
671 .IX Subsection "Usage"
681 .IX Subsection "What tex2lyx Can Handle"
715 .IX Subsection "What tex2lyx Can't Handle --- But it's \s-1OK\s0"
729 .IX Subsection "What tex2lyx Handles Badly --- aka \s-1BUGS\s0"
737 .IX Subsection "What LyX Can't Handle"
749 .IX Subsection "The Future of tex2lyx"
751 .IX Header "EXAMPLES"
755 .IX Subsection "Bug Reports"
757 .IX Subsection "Implementation Details:"
777 .IX Subsection "Layout Files"
779 .IX Subsection "Syntax Files"
781 .IX Subsection "Miscellaneous"
783 .IX Header "DIAGNOSTICS"
785 .IX Header "WARNINGS"
789 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout"
791 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/syntax.default"
793 .IX Item "\fI\s-1LIBDIR\s0\fR/layouts/*.layout"
795 .IX Item "\fI\s-1LIBDIR\s0\fR/lib/syntax.default"
797 .IX Header "SEE ALSO"
projects / lyx.git / blob