2 ''' $RCSfile: reLyX.man,v $$Revision: 1.3 $$Date: 2002/10/28 09:52:39 $
4 ''' $Log: reLyX.man,v $
5 ''' Revision 1.3 2002/10/28 09:52:39 poenitz
8 ''' Revision 1.2 2000/03/29 23:02:36 karger
9 ''' Very minor changes (sorry kayvan!)
26 .ie \\n(.$>=3 .ne \\$3
42 ''' Set up \*(-- to give an unbreakable dash;
43 ''' string Tr holds user defined translation string.
44 ''' Bell System Logo is used as a dummy character.
50 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
51 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
54 ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
55 ''' \*(L" and \*(R", except that they are used on ".xx" lines,
56 ''' such as .IP and .SH, which do another additional levels of
57 ''' double-quote interpretation
86 .\" If the F register is turned on, we'll generate
87 .\" index entries out stderr for the following things:
92 .\" X<> Xref (embedded
93 .\" Of course, you have to process the output yourself
94 .\" in some meaninful fashion.
97 .tm Index:\\$1\t\\n%\t"\\$2"
102 .TH RELYX 1 "Version 2.9.2.2 2.9.2.2" "11/Aug/99" "User Contributed Perl Documentation"
106 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
107 .de CQ \" put $1 in typewriter font
113 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
116 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
117 . \" AM - accent mark definitions
119 . \" fudge factors for nroff and troff
128 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
134 . \" simple accents for nroff and troff
147 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
148 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
149 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
150 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
151 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
152 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
153 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
154 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
155 . 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'
157 . \" troff and (daisy-wheel) nroff accents
158 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
159 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
160 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
161 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
162 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
163 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
164 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
165 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
166 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
167 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
168 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
169 .ds ae a\h'-(\w'a'u*4/10)'e
170 .ds Ae A\h'-(\w'A'u*4/10)'E
171 .ds oe o\h'-(\w'o'u*4/10)'e
172 .ds Oe O\h'-(\w'O'u*4/10)'E
173 . \" corrections for vroff
174 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
175 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
176 . \" for low resolution devices (crt and lpr)
177 .if \n(.H>23 .if \n(.V>19 \
181 . ds v \h'-1'\o'\(aa\(ga'
197 \fBreLyX\fR \- translate well-behaved LaTeX into LyX
199 The simplest way to use \fBreLyX\fR is via the File->Import command in LyX. (This
200 option is available starting with version 1.0.0.) That runs \fBreLyX\fR on
201 the given file and loads the resulting file into LyX. You should try that
202 first, and call it from the command line only if you need to use more
205 \fBreLyX\fR [ \fB\-c\fR \fItextclass\fR ] [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ] [\fB\-n\fR]
206 [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
209 \fBreLyX\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ]
210 [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
213 \fBreLyX\fR \fB\-h\fR
216 Class. By default, when \fBreLyX\fR sees a \f(CW\edocumentclass{foo}\fR command, it
217 creates a file of textclass \*(L"foo\*(R" and reads the LyX layout file for that class
218 (something like /usr/local/share/lyx/layouts/foo.layout \s-1OR\s0
219 \fB\s-1HOME\s0\fR/.lyx/layouts/foo.layout). Use \fB\-c\fR to declare a different textclass
220 (and read a different layout file).
222 Debug. By default, \fBreLyX\fR gives sparse output and deletes the temporary files
223 which were created during translation. Using the \fB\-d\fR flag will create much
224 more output (both to stdout and stderr) and leave the temporary files around.
226 Force. \fBreLyX\fR will not run if the .lyx file it would generate already exists
227 Use the \fB\-f\fR option (carefully) to clobber any existing files.
229 Help. Print out usage information and quit.
231 Noweb. Translate a noweb (aka literate programming) file. This should be
232 (almost?) equivalent to running \*(L"noweb2lyx foo.tex foo.lyx\*(R". This option
233 requires the \fB\-c\fR option.
235 Output directory. With this option, all temporary files and LyX output files
236 (for the given input file, for any included files, or for any file fragments
237 given with the \fB\-p\fR option) will be put into \fIoutputdir\fR. Otherwise, for
238 each file \fIdir/foo.tex\fR, the temporary files and the LyX output file will be
239 created in \fIdir\fR. This can be useful if a file includes files from other
240 directories which you want to consolidate in one directory, or if you don't
241 have write permission on the directory the LaTeX files are in.
243 Partial file. The input files are LaTeX fragments, with no preamble matter or
244 \f(CW\ebegin{document}\fR commands. This option requires the \fB\-c\fR option, since there
245 are no \f(CW\edocumentclass\fR commands in the files \fBreLyX\fR is translating. When
246 using this option, you can translate more than one file, as long as all files
247 are the same class. The LyX file created by \fBreLyX\fR can be included in an
248 existing LyX file using the \*(L"Include LyX File\*(R" command from LyX's Insert menu.
250 Regular environments (see the section on \fISyntax Files\fR). If you give more than one
251 environment, separate them with commas (not spaces). You'll probably need to
252 quote the environment list, especially if it has asterisk environments (foo*)
253 in it. If you use this command often, considering creating a personal syntax
256 Syntax files. Input (one or more quoted, comma-separated) syntax files to read
257 in addition to the default. (see the section on \fISyntax Files\fR for details).
260 \fBreLyX\fR will create a LyX file \fIdir/foo.lyx\fR from the LaTeX file
261 \fIdir/foo.tex\fR (unless the \fB\-o\fR option is used).
263 Suffixes .tex, .ltx and .latex are supported. If \fIinputfile\fR
264 does not exist and does not have one of these suffixes, \fBreLyX\fR will try to
265 translate \fIinputfile.tex\fR. (This is similar to the behavior of LaTeX.)
267 The purpose of \fBreLyX\fR is to translate \fIwell-behaved\fR LaTeX2e into LyX. If
268 your LaTeX file doesn't compile---or if you do weird things, like redefining
269 standard LaTex commands---it may choke. LaTeX209 will often be translated
270 correctly, but it's not guaranteed.
272 \fBreLyX\fR has some bugs and lacks a few features. However, its main goals are:
274 Get through a well-behaved LaTeX2e file without crashing
276 Translate a lot of that file.
278 Localize the parts that can't be translated and copy them in TeX mode
280 It achieves these main goals pretty well on most files.
282 There are many improvements that can and will be made to \fBreLyX\fR in the
283 future. However, we wanted to get \fBreLyX\fR out there early on, to make
284 it easier for new LyX users to read in their existing LaTeX files.
286 Here's a more lengthy description of what you should do to translate a LaTeX
291 \fBreLyX\fR will inform you of its progress and give any warnings to stderr, so if
292 you don't want any output at all, try (in csh) \*(L'reLyX foo.tex >& /dev/null\*(R'.
293 You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
295 Run LyX (version 0.12 or 1.0 or later) on the resulting .lyx file.
297 In theory, most of the file will have been translated, and anything that's
298 untranslatable will be highlighted in red (TeX mode). In theory, LyX will be
299 able to read in the file, and to create printed documents from it, because all
300 that untranslated red stuff will be passed directly back to LaTeX, which LyX
301 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
302 \fBreLyX\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.
304 Change things that are highlighted in red (TeX mode) by hand in LyX.
306 As mentioned above, you should be able to print out the LyX file even without
307 doing this. However, changing a command in TeX mode to the corresponding LyX
308 object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
310 \fBreLyX\fR is not guaranteed to create a LyX file which generates exactly the same
311 output as the LaTeX file, but it should come close. \fBrelyX\fR will generally err
312 on the side of translating less to ensure that dvi or ps files are accurate,
313 even though this leads to more \*(L"evil red text\*(R" and less \s-1WYSIWYM\s0.
315 \s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
317 I'm sure you were planning on doing this anyway, but it's particularly
318 important after translating a LaTeX document. \fBreLyX\fR is, at least now, better
319 at \*(L"macro-translating\*(R" (translating the whole document) than
320 \*(L"micro-translating\*(R" (translating every little detail). For example, you may see
321 extra spaces or deleted spaces. Space handling has improved, but it's
323 .Sh "What reLyX Can Handle"
324 \fBreLyX\fR understands many LaTeX commands. It will translate:
326 regular text, including mini-commands like ~, \*(L'\*(R', \f(CW\e@\fR, \f(CW\eTeX\fR, as well as
327 accented characters like \f(CW\e'{a}\fR, and the special cases ?` and !`
329 title commands like \f(CW\eauthor\fR, \f(CW\edate\fR, \f(CW\etitle\fR, \f(CW\ethanks\fR and the
332 heading commands like \f(CW\esection\fR including starred commands (\f(CW\esection*\fR)
334 Environments: quote, quotation, and verse; center, flushright, and flushleft
336 itemize, enumerate, and description environments, and their \f(CW\eitem\fR commands.
337 Also, well-behaved nested lists
339 cross-referencing commands: \f(CW\eref\fR, \f(CW\epageref\fR, \f(CW\elabel\fR, and \f(CW\ecite\fR
341 \f(CW\efootnote\fR and \f(CW\emargin\fR
343 font-changing commands including \f(CW\eem\fR, \f(CW\eemph\fR, \f(CW\etextit\fR, and
344 corresponding commands to change family, size, series, and shape
346 \f(CW\einput{foo}\fR (or \f(CW\einput{foo.blah}\fR) and \f(CW\einclude{foo}\fR. Plain TeX
347 \f(CW\einput\fR command \*(L"\f(CW\einput foo.tex\fR\*(R" is also supported.
349 tabular environment, and commands that go inside it like \f(CW\ehline\fR, \f(CW\ecline\fR,
350 and \f(CW\emulticolumn\fR (but see below)
352 float environments table and table*, as well as \f(CW\ecaption\fR commands within
355 float environments figure and figure*, as well as graphics inclusion commands
356 \eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
357 Both the graphics and graphicx forms of \eincludegraphics are supported.
358 Note, however, that many figures will not be translatable into LyX. See
359 the section on \*(L"What LyX Can't Handle\*(R" below.
361 thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
362 \f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
364 miscellaneous commands: \f(CW\ehfill\fR, \f(CW\e\fR\f(CW\e\fR, \f(CW\enoindent\fR, \f(CW\eldots\fR...
366 documentclass-specific environments (and some commands) which can be
367 translated to LyX layouts
369 arguments to certain untranslatable commands (e.g. \f(CW\embox\fR)
371 Some of this support may not be 100% yet. See below for details
373 \fBreLyX\fR copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
374 in LaTeX math, so (almost) any math which is supported by LyX should work just
375 fine. A few math commands which are not supported by LyX will be replaced with
376 their equivalents, e.g., \f(CW\eto\fR is converted to \f(CW\erightarrow\fR. See
377 the section on \fISyntax Files\fR for more details.
379 \fBreLyX\fR will also copy any preamble commands (i.e., anything before
380 \f(CW\ebegin{document}\fR) verbatim, so fancy stuff you've got in your preamble
381 should be conserved in dvi and printed documents, although it will not of
382 course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.
383 .Sh "What reLyX Can't Handle --- But it's \s-1OK\s0"
389 spacing commands (\f(CW\evspace\fR, \f(CW\epagebreak\fR, \f(CW\epar\fR, ...)
391 \f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
393 \f(CW\everb\fR and verbatim environment. \fBreLyX\fR is careful to copy \fIexactly\fR in
394 this case, including comments and whitespace.
396 some unknown (e.g., user-defined) environments and commands
398 \fBreLyX\fR copies unknown commands, along with their arguments, verbatim into the
399 LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
400 \*(L"foo\*(R" environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
401 you use the \fB\-r\fR option). Hopefully, then, most of these unknown commands
402 won't cause \fBreLyX\fR to break; they'll merely require you to do some editing
403 once you've loaded the file up in LyX. That should be less painful than
404 editing either the .tex or the .lyx file using a text editor.
405 .Sh "What reLyX Handles Badly --- aka \s-1BUGS\s0"
406 Since \fBreLyX\fR is relatively new, it's got a number of problems. As it
407 matures, these bugs will be squished.
409 If \fBreLyX\fR is choking on something, or LyX can't read it after \fBreLyX\fR
410 translates it, the best thing to do is to put \f(CW\ebegin{reLyXskip}\fR before the
411 offending text, and \f(CW\eend{reLyXskip}\fR after it. I call this a \*(L"skip\*(R" block.
412 \fBreLyX\fR will copy this block exactly, in TeX mode. Then edit the resulting
413 LyX file, and translate the unknown stuff by hand. The reLyXskip environment
414 is magical; the \f(CW\ebegin\fR and \f(CW\eend\fR commands will not be put into the LyX
417 \*(L"Exact\*(R" copying of unknown environments and commands isn't quite exact.
418 Specifically, newlines and comments may be lost. This will yield ugly LyX, but
419 in almost all cases the output will be the same. However, certain parts of the
420 file will be copied perfectly, including whitespace and comments. This
421 includes: the LaTeX preamble, verbatim environments and \f(CW\everb\fR commands, and
424 \fBreLyX\fR translates only a few options to the \f(CW\edocumentclass\fR command.
425 (Specifically 1[012]pt, [letter|legal|executive|a4|a5|b5]paper,
426 [one|two]side, landscape, and [one|two]column.) Other options are placed in
427 the \*(L"options\*(R" field in the Layout->Document popup.
429 More importantly, \fBreLyX\fR doesn't translate \f(CW\eusepackage\fR commands, margin
430 commands, \f(CW\enewcommands\fR, or, in fact, anything else from the preamble. It
431 simply copies them into the LaTeX preamble. If you have margin commands in
432 your preamble, then the LyX file will generate the right margins. However,
433 these margins will override any margins you set in the LyX Layout->Paper
434 popup. So you should remove the options from the preamble
435 (Layout->Latex Preamble) to be safe. The same goes for setting your language
436 with babel, \f(CW\einputencoding\fR, \f(CW\epagestyle\fR, etc.
438 The foil class has a couple bugs. \fBreLyX\fR may do weird things with optional
439 arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
440 incorrectly (although the stuff in the environment should translate normally).
442 Less significant bugs can be found in the \fI\s-1BUGS\s0\fR file.
444 \fBreLyX\fR is hopefully rather robust. As mentioned above, it may not translate
445 your file perfectly, but it shouldn't crash. If it does crash---and the
446 problem is not one of those mentioned above or in the \fI\s-1BUGS\s0\fR file---see
447 the section on \fIBug Reports\fR.
448 .Sh "What LyX Can't Handle"
449 LyX itself is missing a couple features, such that even if \fBreLyX\fR translates
450 things perfectly, LyX may still have trouble reading it. If you really need
451 these features, you can export your final document as LaTeX, and put them
452 back in. See \fI\s-1BUGS\s0\fR for more details on these bugs.
454 For a number of commands, LyX does not support the optional argument. Examples
455 include \f(CW\echapter\fR (and other sectioning commands), and \f(CW\e\e\fR.
456 \fBreLyX\fR will automatically discard the optional arguments with a warning to
457 stdout. LyX also ignores the width argument for the thebibliography
460 Centering (or right or left justifying) works on full paragraphs.
462 LyX support for tables isn't perfect. For complicated tables, use a \*(L"skip\*(R"
463 block, so that they will be copied in TeX mode.
465 The LyX math editor can't handle the \s-1AMS\s0\-LaTeX math environments align, split,
466 etc. So those environments will be copied in TeX mode. You can change
467 equation* environments to the exactly equivalent displaymath, and then they
468 will be translated correctly.
470 Lyx does not support clipping or bounding boxes for included graphics files.
471 Therefore, many graphics inclusion commands will be untranslatable, and
472 copied in TeX mode. In certain cases, you might be able to translate the
473 command by hand within LyX---for example, if you included a bounding box but
474 the bounding box is already in the .eps file.
476 LyX only allows figures to have sizes in in,cm, or percentages of \etextwidth
477 or \etextheight (or \ecolumnwidth). \fBreLyX\fR will translate from other units, like
478 pt or mm, but it cannot translate other lengths (e.g. if you wanted to scale a
479 figure to size \etopmargin for some reason). \fBreLyX\fR will copy figures with
480 untranslatable sizes in TeX mode. Again, you might be able to fix that within
482 .Sh "The Future of reLyX"
483 In the future, more commands and environments will be supported by \fBreLyX\fR.
484 Bugs will be eradicated.
486 See the \s-1TODO\s0 file for details.
488 reLyX \fB\-df\fR \fB\-o\fR \*(L"my/dir\*(R" \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
490 The above will create a file my/dir/foo.lyx from foo.tex, overwriting if
491 necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
492 translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
493 commands in TeX mode. Finally, I'm going to keep the temporary files around
494 (they will also be in my/dir/) and output lots of debugging information into
497 reLyX \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
499 The above will change a noweb document into a LyX literate-article
500 document. A user would do this if the noweb document had documentclass
504 If \fBreLyX\fR is crashing or otherwise acting strangely---in ways
505 other than those described in the section on \fI\s-1BUGS\s0\fR or the \fI\s-1BUGS\s0\fR file---then please run
506 \fBreLyX \-d\fR. That will allow you to figure out where in the reLyXing process
507 it crashed. That, in turn, will allow you to write a better bug report, which
508 will allow the developers to fix it more quickly and easily.
510 Bug reports should be sent to the LyX developers\*(R' mailing list. Its address
511 is currently lyx-devel@lists.lyx.org, but you can check the LyX home page,
512 http://www.lyx.org if that bounces. If you are running \fBreLyX\fR on a huge file,
513 please do not send all of the output in your bug report. Just include the last
514 ten or twenty lines of output, along with the piece of the LaTeX file it
515 crashed on. Or, even better, attach a small but complete file which causes
516 the same problem as your original file.
517 .Sh "Implementation Details:"
518 \fBreLyX\fR makes several \*(L"passes\*(R" in order to translate a TeX file. On each pass,
519 it creates one or two files.
521 Before doing anything, read the syntax file (or files).
523 Split preamble (anything before a \f(CW\ebegin{document}\fR command) off the rest
524 of the file. It saves the two pieces in separate files. This is necessary
525 because there may be very strange stuff in a preamble. It also ignores
526 anything after the \f(CW\eend{document}\fR, on the assumption that it isn't LaTeX.
528 Translate the preamble. Currently, that just means translating the
529 \f(CW\edocumentclass\fR command and copying the rest exactly into the LyX preamble.
531 Once you know what class the document is, read the LyX layout file for that
534 \*(L"Clean\*(R" the TeX file, generating slightly stricter LaTeX. This includes:
536 Change, e.g., x^2 to the equivalent but clearer x^{2}
538 Removing optional arguments that LyX can't handle (e.g., from \f(CW\echapter\fR)
540 Changing \f(CW{\eem foo}\fR to \f(CW\eemph{foo}\fR, etc. This is necessary because LyX
541 always writes out the non-local forms anyway. This should very rarely make a
544 Translate LaTeX text, commands, and environments to LyX.
546 Put the two pieces back together, and do some final tweaking, to generate the
549 If there are any \f(CW\einput\fR or \f(CW\einclude\fR commands, \fBreLyX\fR will loop back to
550 the beginning and translate those. It assumes that the included files are the
551 same class as the main file, and that they have no preamble matter. (If you
552 have an \f(CW\einput\fR command in the preamble of a file, the command will be
553 copied exactly into the LaTeX preamble portion of the LyX file, so the
554 included file won't be translated.) So when translating included files, it
555 skips passes 0 and 1.
557 If \fBreLyX\fR doesn't find a file you wanted to include, it will give a warning,
558 but will continue to translate any files it does find.
560 \fBreLyX\fR reads a LyX layout file to know how to handle LaTeX environments and
561 commands which get translated to LyX layouts. This file will include all
562 \*(L"normal\*(R" non-math environments (i.e., including quote and itemize, but not
563 tabular, minipage, and some other fancy environments), and commands like
564 \f(CW\esection\fR and \f(CW\etitle\fR. If you want to reLyX a class that doesn't have an
565 existing layout file, then you'll have to create a layout file. But you have
566 to do this anyway, in order to LyX the file, since LyX depends on layout files
567 to know how to display and process its files. Check the LyX documentation for
568 help with this task (which can be hard or easy, depending on the class you
569 want to create a layout file for.) If your class is quite similar to a class
570 that has a layout file, then consider using the \fB\-c\fR option.
572 \fBreLyX\fR always reads at least one syntax file, called the default syntax file.
573 \fBreLyX\fR will read your personal syntax file if it exists; otherwise it will
574 read the system-wide file. \fBreLyX\fR will read additional syntax files if you
575 specify them with the \fB\-s\fR option. (These extra files should have the same
576 format as the default file, but will tend to be shorter, since they only have
577 to specify extra commands not found in the default file.) A syntax file tells
578 \fBreLyX\fR a few things.
580 First, it describes the syntax of each command, that is, how many required
581 arguments and how many optional arguments the command takes. Knowing this
582 makes it easier for \fBreLyX\fR to copy (in TeX mode) commands that it doesn't
583 know how to translate. The syntax file simply has a command, followed by
584 braces or brackets describing its arguments in the correct order. For example,
585 a syntax file entry \f(CW\ebibitem[]{}\fR means that the \f(CW\ebibitem\fR command takes
586 an optional argument followed by a required one, while the entry \f(CW\ebf\fR
587 means that the \f(CW\ebf\fR command takes no arguments at all. When \fBreLyX\fR
588 encounters a token that it doesn't know how to translate into LyX, it will
589 copy the token---along with the correct number of arguments---exactly. If the
590 token is not in the syntax file, then \fBreLyX\fR just copies as many arguments
591 as it finds. This means that it may copy too much. But since the user can
592 specify additional syntax files, that shouldn't happen often.
594 Some commands that cannot be translated to LyX, like \f(CW\embox\fR, have as one of
595 their arguments regular LaTeX text. If the string \*(L"translate\*(R" is put into an
596 argument of an (untranslatable) command in the syntax file, then \fBreLyX\fR will
597 translate that argument instead of copying it verbatim. So, for example, the
598 default syntax file has \f(CW\eraisebox{}[][]{translate}\fR. This means that the
599 \f(CW\eraisebox\fR command and the first argument (and optional arguments if they
600 exist) are copied in TeX mode, but the last argument (which may contain math,
601 complicated LaTeX, other untranslatable commands, etc.) will be translated
602 into LyX. You can't use \*(L"translate\*(R" on optional arguments.
604 User-defined syntax files are allowed to define new commands and
605 their syntax, or override the number of arguments for a command given in the
606 default syntax file. (E.g., if you're using a style that gives an extra
607 argument to some command...) However, this will only be useful for commands
608 copied in TeX mode. Commands which are actually translated by \fBreLyX\fR (like
609 \f(CW\eitem\fR) have their argument syntax hard-coded. The hard-coded commands are
610 identified in the default syntax file.
612 Second, the syntax file describes any \*(L"regular environments\*(R". Usually, an
613 entire unknown environment will be copied in TeX mode. If you define a regular
614 environment \*(L"foo\*(R", though, then only the \f(CW\ebegin{foo}\fR and \f(CW\eend{foo}\fR
615 commands will be copied in TeX mode; the text within the environment will be
616 treated (i.e., translated) by \fBreLyX\fR as regular LaTeX, rather than being
617 copied into TeX mode. Don't try to declare \*(L"tabbing\*(R" and \*(L"picture\*(R" as regular
618 environments, as the text within those environments will confuse \fBreLyX\fR; use
619 this capability for new environments you create that have plain text or math
620 or simple commands in them. You also can't declare unknown math environments
621 (like equation*) as regular environments, either, since the LyX math editor
622 won't understand them. The names of regular environments appear,
623 whitespace-separated, between \f(CW\ebegin{reLyXre}\fR and \f(CW\eend{reLyXre}\fR
624 statements in the syntax file. (If you have a regular environment which you
625 won't use very often, you can use the \fB\-r\fR option rather than writing a
628 You need Perl version 5.002 or later to run \fBreLyX\fR. <plug> If you don't have
629 Perl, you should get it anyway (at http://www.perl.com), because it's a really
630 useful tool for pretty much anything. </plug>
632 \fBreLyX\fR should always explain why it crashes, if it crashes. Some diagnostics
633 may be very technical, though, if they come from the guts of the code.
634 \fBreLyX\fR gives much more information while running if you use the \fB\-d\fR option,
635 but you shouldn't need that unless something goes wrong.
637 When it's finished, \fBreLyX\fR will tell you if it finished successfully or
638 died due to some error.
640 Always keep a copy of your original LaTeX files either under a different
641 name or in a different directory. There are a couple ways in which using LyX
642 could lead to overwriting the original LaTeX file.
644 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
645 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
646 you if you want to overwrite it.)
648 If you have the \euse_tempdir variable set to false in your lyxrc, then LyX
649 will create its temporary files in your current directory, which means your
650 LaTeX original may be overwritten (without a warning from LyX) when you \*(L"view
651 dvi\*(R" or print the LyX document.
653 .Ip "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
654 User's personal layout files for document classes
655 .Ip "\fI\s-1MY_LYXDIR\s0\fR/reLyX/syntax.default" 4
656 User's personal syntax file
657 .Ip "\fI\s-1LIBDIR\s0\fR/layouts/*.layout" 4
658 System-wide layout files for document classes
659 .Ip "\fI\s-1LIBDIR\s0\fR/reLyX/syntax.default" 4
660 System-wide LaTeX syntax file
662 \fI\s-1LIBDIR\s0\fR is the system-wide LyX directory, usually something like
663 /usr/local/share/lyx/. \fI\s-1MY_LYXDIR\s0\fR is your personal LyX directory, something
664 like .lyx/ in your home directory.
666 \fIlyx\fR\|(1), \fIlatex\fR\|(1)
668 Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
672 John Weiss wrote the original CleanTeX pass.
676 Jose\*' Abi\*'lio Oliveira Matos
680 Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx
684 Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug
685 reports, advice, and feature suggestions.
687 Asger K. Alstrup Nielsen and Marc Pavese provided advice.
689 Various members of the LyX developers\*(R' and users\*(R' lists provided bug reports
690 and feature suggestions.
692 \fBreLyX\fR uses a modified version the Perl TeX parser Text::TeX package written
693 by Ilya Zakharevich (ilya@math.ohio-state.edu), available on \s-1CPAN\s0.
697 .IX Name "B<reLyX> - translate well-behaved LaTeX into LyX"
701 .IX Header "SYNOPSIS"
723 .IX Header "DESCRIPTION"
725 .IX Subsection "Introduction"
733 .IX Subsection "Usage"
743 .IX Subsection "What reLyX Can Handle"
777 .IX Subsection "What reLyX Can't Handle --- But it's \s-1OK\s0"
791 .IX Subsection "What reLyX Handles Badly --- aka \s-1BUGS\s0"
799 .IX Subsection "What LyX Can't Handle"
811 .IX Subsection "The Future of reLyX"
813 .IX Header "EXAMPLES"
817 .IX Subsection "Bug Reports"
819 .IX Subsection "Implementation Details:"
839 .IX Subsection "Layout Files"
841 .IX Subsection "Syntax Files"
843 .IX Subsection "Miscellaneous"
845 .IX Header "DIAGNOSTICS"
847 .IX Header "WARNINGS"
851 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout"
853 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/reLyX/syntax.default"
855 .IX Item "\fI\s-1LIBDIR\s0\fR/layouts/*.layout"
857 .IX Item "\fI\s-1LIBDIR\s0\fR/reLyX/syntax.default"
859 .IX Header "SEE ALSO"
projects / lyx.git / blob