2 ''' $RCSfile: reLyX.man,v $$Revision: 1.2 $$Date: 2000/03/29 23:02:36 $
4 ''' $Log: reLyX.man,v $
5 ''' Revision 1.2 2000/03/29 23:02:36 karger
6 ''' Very minor changes (sorry kayvan!)
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 RELYX 1 "Version 2.9.2.2 2.9.2.2" "11/Aug/99" "User Contributed Perl Documentation"
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 \fBreLyX\fR \- translate well-behaved LaTeX into LyX
196 The simplest way to use \fBreLyX\fR is via the File->Import command in LyX. (This
197 option is available starting with version 1.0.0.) That runs \fBreLyX\fR on
198 the given file and loads the resulting file into LyX. You should try that
199 first, and call it from the command line only if you need to use more
202 \fBreLyX\fR [ \fB\-c\fR \fItextclass\fR ] [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ] [\fB\-n\fR]
203 [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
206 \fBreLyX\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ]
207 [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
210 \fBreLyX\fR \fB\-h\fR
213 Class. By default, when \fBreLyX\fR sees a \f(CW\edocumentclass{foo}\fR command, it
214 creates a file of textclass \*(L"foo\*(R" and reads the LyX layout file for that class
215 (something like /usr/local/share/lyx/layouts/foo.layout \s-1OR\s0
216 \fB\s-1HOME\s0\fR/.lyx/layouts/foo.layout). Use \fB\-c\fR to declare a different textclass
217 (and read a different layout file).
219 Debug. By default, \fBreLyX\fR gives sparse output and deletes the temporary files
220 which were created during translation. Using the \fB\-d\fR flag will create much
221 more output (both to stdout and stderr) and leave the temporary files around.
223 Force. \fBreLyX\fR will not run if the .lyx file it would generate already exists
224 Use the \fB\-f\fR option (carefully) to clobber any existing files.
226 Help. Print out usage information and quit.
228 Noweb. Translate a noweb (aka literate programming) file. This should be
229 (almost?) equivalent to running \*(L"noweb2lyx foo.tex foo.lyx\*(R". This option
230 requires the \fB\-c\fR option.
232 Output directory. With this option, all temporary files and LyX output files
233 (for the given input file, for any included files, or for any file fragments
234 given with the \fB\-p\fR option) will be put into \fIoutputdir\fR. Otherwise, for
235 each file \fIdir/foo.tex\fR, the temporary files and the LyX output file will be
236 created in \fIdir\fR. This can be useful if a file includes files from other
237 directories which you want to consolidate in one directory, or if you don't
238 have write permission on the directory the LaTeX files are in.
240 Partial file. The input files are LaTeX fragments, with no preamble matter or
241 \f(CW\ebegin{document}\fR commands. This option requires the \fB\-c\fR option, since there
242 are no \f(CW\edocumentclass\fR commands in the files \fBreLyX\fR is translating. When
243 using this option, you can translate more than one file, as long as all files
244 are the same class. The LyX file created by \fBreLyX\fR can be included in an
245 existing LyX file using the \*(L"Include LyX File\*(R" command from LyX's Insert menu.
247 Regular environments (see the section on \fISyntax Files\fR). If you give more than one
248 environment, separate them with commas (not spaces). You'll probably need to
249 quote the environment list, especially if it has asterisk environments (foo*)
250 in it. If you use this command often, considering creating a personal syntax
253 Syntax files. Input (one or more quoted, comma-separated) syntax files to read
254 in addition to the default. (see the section on \fISyntax Files\fR for details).
257 \fBreLyX\fR will create a LyX file \fIdir/foo.lyx\fR from the LaTeX file
258 \fIdir/foo.tex\fR (unless the \fB\-o\fR option is used).
260 Suffixes .tex, .ltx and .latex are supported. If \fIinputfile\fR
261 does not exist and does not have one of these suffixes, \fBreLyX\fR will try to
262 translate \fIinputfile.tex\fR. (This is similar to the behavior of LaTeX.)
264 The purpose of \fBreLyX\fR is to translate \fIwell-behaved\fR LaTeX2e into LyX. If
265 your LaTeX file doesn't compile---or if you do weird things, like redefining
266 standard LaTex commands---it may choke. LaTeX209 will often be translated
267 correctly, but it's not guaranteed.
269 \fBreLyX\fR has some bugs and lacks a few features. However, its main goals are:
271 Get through a well-behaved LaTeX2e file without crashing
273 Translate a lot of that file.
275 Localize the parts that can't be translated and copy them in TeX mode
277 It achieves these main goals pretty well on most files.
279 There are many improvements that can and will be made to \fBreLyX\fR in the
280 future. However, we wanted to get \fBreLyX\fR out there early on, to make
281 it easier for new LyX users to read in their existing LaTeX files.
283 Here's a more lengthy description of what you should do to translate a LaTeX
288 \fBreLyX\fR will inform you of its progress and give any warnings to stderr, so if
289 you don't want any output at all, try (in csh) \*(L'reLyX foo.tex >& /dev/null\*(R'.
290 You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
292 Run LyX (version 0.12 or 1.0 or later) on the resulting .lyx file.
294 In theory, most of the file will have been translated, and anything that's
295 untranslatable will be highlighted in red (TeX mode). In theory, LyX will be
296 able to read in the file, and to create printed documents from it, because all
297 that untranslated red stuff will be passed directly back to LaTeX, which LyX
298 uses as a backend. Unfortunately, reality doesn't always reflect theory. If
299 \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.
301 Change things that are highlighted in red (TeX mode) by hand in LyX.
303 As mentioned above, you should be able to print out the LyX file even without
304 doing this. However, changing a command in TeX mode to the corresponding LyX
305 object will allow you to take advantage of LyX's \s-1WYSIWYM\s0 editing.
307 \fBreLyX\fR is not guaranteed to create a LyX file which generates exactly the same
308 output as the LaTeX file, but it should come close. \fBrelyX\fR will generally err
309 on the side of translating less to ensure that dvi or ps files are accurate,
310 even though this leads to more \*(L"evil red text\*(R" and less \s-1WYSIWYM\s0.
312 \s-1PROOFREAD\s0 \s-1THE\s0 \s-1DOCUMENT\s0!!
314 I'm sure you were planning on doing this anyway, but it's particularly
315 important after translating a LaTeX document. \fBreLyX\fR is, at least now, better
316 at \*(L"macro-translating\*(R" (translating the whole document) than
317 \*(L"micro-translating\*(R" (translating every little detail). For example, you may see
318 extra spaces or deleted spaces. Space handling has improved, but it's
320 .Sh "What reLyX Can Handle"
321 \fBreLyX\fR understands many LaTeX commands. It will translate:
323 regular text, including mini-commands like ~, \*(L'\*(R', \f(CW\e@\fR, \f(CW\eTeX\fR, as well as
324 accented characters like \f(CW\e'{a}\fR, and the special cases ?` and !`
326 title commands like \f(CW\eauthor\fR, \f(CW\edate\fR, \f(CW\etitle\fR, \f(CW\ethanks\fR and the
329 heading commands like \f(CW\esection\fR including starred commands (\f(CW\esection*\fR)
331 Environments: quote, quotation, and verse; center, flushright, and flushleft
333 itemize, enumerate, and description environments, and their \f(CW\eitem\fR commands.
334 Also, well-behaved nested lists
336 cross-referencing commands: \f(CW\eref\fR, \f(CW\epageref\fR, \f(CW\elabel\fR, and \f(CW\ecite\fR
338 \f(CW\efootnote\fR and \f(CW\emargin\fR
340 font-changing commands including \f(CW\eem\fR, \f(CW\eemph\fR, \f(CW\etextit\fR, and
341 corresponding commands to change family, size, series, and shape
343 \f(CW\einput{foo}\fR (or \f(CW\einput{foo.blah}\fR) and \f(CW\einclude{foo}\fR. Plain TeX
344 \f(CW\einput\fR command \*(L"\f(CW\einput foo.tex\fR\*(R" is also supported.
346 tabular environment, and commands that go inside it like \f(CW\ehline\fR, \f(CW\ecline\fR,
347 and \f(CW\emulticolumn\fR (but see below)
349 float environments table and table*, as well as \f(CW\ecaption\fR commands within
352 float environments figure and figure*, as well as graphics inclusion commands
353 \eepsf, \eepsffile, \eepsfbox, \eepsfxsize, \eepsfig, \epsfig, and \eincludegraphics.
354 Both the graphics and graphicx forms of \eincludegraphics are supported.
355 Note, however, that many figures will not be translatable into LyX. See
356 the section on \*(L"What LyX Can't Handle\*(R" below.
358 thebibliography environment and \f(CW\ebibitem\fR command, as well as BibTeX's
359 \f(CW\ebibliography\fR and \f(CW\ebibliographystyle\fR commands
361 miscellaneous commands: \f(CW\ehfill\fR, \f(CW\e\fR\f(CW\e\fR, \f(CW\enoindent\fR, \f(CW\eldots\fR...
363 documentclass-specific environments (and some commands) which can be
364 translated to LyX layouts
366 arguments to certain untranslatable commands (e.g. \f(CW\embox\fR)
368 Some of this support may not be 100% yet. See below for details
370 \fBreLyX\fR copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads
371 in LaTeX math, so (almost) any math which is supported by LyX should work just
372 fine. A few math commands which are not supported by LyX will be replaced with
373 their equivalents, e.g., \f(CW\eto\fR is converted to \f(CW\erightarrow\fR. See
374 the section on \fISyntax Files\fR for more details.
376 \fBreLyX\fR will also copy any preamble commands (i.e., anything before
377 \f(CW\ebegin{document}\fR) verbatim, so fancy stuff you've got in your preamble
378 should be conserved in dvi and printed documents, although it will not of
379 course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.
380 .Sh "What reLyX Can't Handle --- But it's \s-1OK\s0"
386 spacing commands (\f(CW\evspace\fR, \f(CW\epagebreak\fR, \f(CW\epar\fR, ...)
388 \f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
390 \f(CW\everb\fR and verbatim environment. \fBreLyX\fR is careful to copy \fIexactly\fR in
391 this case, including comments and whitespace.
393 some unknown (e.g., user-defined) environments and commands
395 \fBreLyX\fR copies unknown commands, along with their arguments, verbatim into the
396 LyX file. Also, if it sees a \f(CW\ebegin{foo}\fR where it doesn't recognize the
397 \*(L"foo\*(R" environment, it will copy verbatim until it sees \f(CW\eend{foo}\fR (unless
398 you use the \fB\-r\fR option). Hopefully, then, most of these unknown commands
399 won't cause \fBreLyX\fR to break; they'll merely require you to do some editing
400 once you've loaded the file up in LyX. That should be less painful than
401 editing either the .tex or the .lyx file using a text editor.
402 .Sh "What reLyX Handles Badly --- aka \s-1BUGS\s0"
403 Since \fBreLyX\fR is relatively new, it's got a number of problems. As it
404 matures, these bugs will be squished.
406 If \fBreLyX\fR is choking on something, or LyX can't read it after \fBreLyX\fR
407 translates it, the best thing to do is to put \f(CW\ebegin{reLyXskip}\fR before the
408 offending text, and \f(CW\eend{reLyXskip}\fR after it. I call this a \*(L"skip\*(R" block.
409 \fBreLyX\fR will copy this block exactly, in TeX mode. Then edit the resulting
410 LyX file, and translate the unknown stuff by hand. The reLyXskip environment
411 is magical; the \f(CW\ebegin\fR and \f(CW\eend\fR commands will not be put into the LyX
414 \*(L"Exact\*(R" copying of unknown environments and commands isn't quite exact.
415 Specifically, newlines and comments may be lost. This will yield ugly LyX, but
416 in almost all cases the output will be the same. However, certain parts of the
417 file will be copied perfectly, including whitespace and comments. This
418 includes: the LaTeX preamble, verbatim environments and \f(CW\everb\fR commands, and
421 \fBreLyX\fR translates only a few options to the \f(CW\edocumentclass\fR command.
422 (Specifically 1[012]pt, [letter|legal|executive|a4|a5|b5]paper,
423 [one|two]side, landscape, and [one|two]column.) Other options are placed in
424 the \*(L"options\*(R" field in the Layout->Document popup.
426 More importantly, \fBreLyX\fR doesn't translate \f(CW\eusepackage\fR commands, margin
427 commands, \f(CW\enewcommands\fR, or, in fact, anything else from the preamble. It
428 simply copies them into the LaTeX preamble. If you have margin commands in
429 your preamble, then the LyX file will generate the right margins. However,
430 these margins will override any margins you set in the LyX Layout->Paper
431 popup. So you should remove the options from the preamble
432 (Layout->Latex Preamble) to be safe. The same goes for setting your language
433 with babel, \f(CW\einputencoding\fR, \f(CW\epagestyle\fR, etc.
435 The foil class has a couple bugs. \fBreLyX\fR may do weird things with optional
436 arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
437 incorrectly (although the stuff in the environment should translate normally).
439 Less significant bugs can be found in the \fI\s-1BUGS\s0\fR file.
441 \fBreLyX\fR is hopefully rather robust. As mentioned above, it may not translate
442 your file perfectly, but it shouldn't crash. If it does crash---and the
443 problem is not one of those mentioned above or in the \fI\s-1BUGS\s0\fR file---see
444 the section on \fIBug Reports\fR.
445 .Sh "What LyX Can't Handle"
446 LyX itself is missing a couple features, such that even if \fBreLyX\fR translates
447 things perfectly, LyX may still have trouble reading it. If you really need
448 these features, you can export your final document as LaTeX, and put them
449 back in. See \fI\s-1BUGS\s0\fR for more details on these bugs.
451 For a number of commands, LyX does not support the optional argument. Examples
452 include \f(CW\echapter\fR (and other sectioning commands), and \f(CW\e\e\fR.
453 \fBreLyX\fR will automatically discard the optional arguments with a warning to
454 stdout. LyX also ignores the width argument for the thebibliography
457 Centering (or right or left justifying) works on full paragraphs.
459 LyX support for tables isn't perfect. For complicated tables, use a \*(L"skip\*(R"
460 block, so that they will be copied in TeX mode.
462 The LyX math editor can't handle the \s-1AMS\s0\-LaTeX math environments align, split,
463 etc. So those environments will be copied in TeX mode. You can change
464 equation* environments to the exactly equivalent displaymath, and then they
465 will be translated correctly.
467 Lyx does not support clipping or bounding boxes for included graphics files.
468 Therefore, many graphics inclusion commands will be untranslatable, and
469 copied in TeX mode. In certain cases, you might be able to translate the
470 command by hand within LyX---for example, if you included a bounding box but
471 the bounding box is already in the .eps file.
473 LyX only allows figures to have sizes in in,cm, or percentages of \etextwidth
474 or \etextheight (or \ecolumnwidth). \fBreLyX\fR will translate from other units, like
475 pt or mm, but it cannot translate other lengths (e.g. if you wanted to scale a
476 figure to size \etopmargin for some reason). \fBreLyX\fR will copy figures with
477 untranslatable sizes in TeX mode. Again, you might be able to fix that within
479 .Sh "The Future of reLyX"
480 In the future, more commands and environments will be supported by \fBreLyX\fR.
481 Bugs will be eradicated.
483 See the \s-1TODO\s0 file for details.
485 reLyX \fB\-df\fR \fB\-o\fR \*(L"my/dir\*(R" \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
487 The above will create a file my/dir/foo.lyx from foo.tex, overwriting if
488 necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
489 translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
490 commands in TeX mode. Finally, I'm going to keep the temporary files around
491 (they will also be in my/dir/) and output lots of debugging information into
494 reLyX \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
496 The above will change a noweb document into a LyX literate-article
497 document. A user would do this if the noweb document had documentclass
501 If \fBreLyX\fR is crashing or otherwise acting strangely---in ways
502 other than those described in the section on \fI\s-1BUGS\s0\fR or the \fI\s-1BUGS\s0\fR file---then please run
503 \fBreLyX \-d\fR. That will allow you to figure out where in the reLyXing process
504 it crashed. That, in turn, will allow you to write a better bug report, which
505 will allow the developers to fix it more quickly and easily.
507 Bug reports should be sent to the LyX developers\*(R' mailing list. Its address
508 is currently lyx-devel@lists.lyx.org, but you can check the LyX home page,
509 http://www.lyx.org if that bounces. If you are running \fBreLyX\fR on a huge file,
510 please do not send all of the output in your bug report. Just include the last
511 ten or twenty lines of output, along with the piece of the LaTeX file it
512 crashed on. Or, even better, attach a small but complete file which causes
513 the same problem as your original file.
514 .Sh "Implementation Details:"
515 \fBreLyX\fR makes several \*(L"passes\*(R" in order to translate a TeX file. On each pass,
516 it creates one or two files.
518 Before doing anything, read the syntax file (or files).
520 Split preamble (anything before a \f(CW\ebegin{document}\fR command) off the rest
521 of the file. It saves the two pieces in separate files. This is necessary
522 because there may be very strange stuff in a preamble. It also ignores
523 anything after the \f(CW\eend{document}\fR, on the assumption that it isn't LaTeX.
525 Translate the preamble. Currently, that just means translating the
526 \f(CW\edocumentclass\fR command and copying the rest exactly into the LyX preamble.
528 Once you know what class the document is, read the LyX layout file for that
531 \*(L"Clean\*(R" the TeX file, generating slightly stricter LaTeX. This includes:
533 Change, e.g., x^2 to the equivalent but clearer x^{2}
535 Removing optional arguments that LyX can't handle (e.g., from \f(CW\echapter\fR)
537 Changing \f(CW{\eem foo}\fR to \f(CW\eemph{foo}\fR, etc. This is necessary because LyX
538 always writes out the non-local forms anyway. This should very rarely make a
541 Translate LaTeX text, commands, and environments to LyX.
543 Put the two pieces back together, and do some final tweaking, to generate the
546 If there are any \f(CW\einput\fR or \f(CW\einclude\fR commands, \fBreLyX\fR will loop back to
547 the beginning and translate those. It assumes that the included files are the
548 same class as the main file, and that they have no preamble matter. (If you
549 have an \f(CW\einput\fR command in the preamble of a file, the command will be
550 copied exactly into the LaTeX preamble portion of the LyX file, so the
551 included file won't be translated.) So when translating included files, it
552 skips passes 0 and 1.
554 If \fBreLyX\fR doesn't find a file you wanted to include, it will give a warning,
555 but will continue to translate any files it does find.
557 \fBreLyX\fR reads a LyX layout file to know how to handle LaTeX environments and
558 commands which get translated to LyX layouts. This file will include all
559 \*(L"normal\*(R" non-math environments (i.e., including quote and itemize, but not
560 tabular, minipage, and some other fancy environments), and commands like
561 \f(CW\esection\fR and \f(CW\etitle\fR. If you want to reLyX a class that doesn't have an
562 existing layout file, then you'll have to create a layout file. But you have
563 to do this anyway, in order to LyX the file, since LyX depends on layout files
564 to know how to display and process its files. Check the LyX documentation for
565 help with this task (which can be hard or easy, depending on the class you
566 want to create a layout file for.) If your class is quite similar to a class
567 that has a layout file, then consider using the \fB\-c\fR option.
569 \fBreLyX\fR always reads at least one syntax file, called the default syntax file.
570 \fBreLyX\fR will read your personal syntax file if it exists; otherwise it will
571 read the system-wide file. \fBreLyX\fR will read additional syntax files if you
572 specify them with the \fB\-s\fR option. (These extra files should have the same
573 format as the default file, but will tend to be shorter, since they only have
574 to specify extra commands not found in the default file.) A syntax file tells
575 \fBreLyX\fR a few things.
577 First, it describes the syntax of each command, that is, how many required
578 arguments and how many optional arguments the command takes. Knowing this
579 makes it easier for \fBreLyX\fR to copy (in TeX mode) commands that it doesn't
580 know how to translate. The syntax file simply has a command, followed by
581 braces or brackets describing its arguments in the correct order. For example,
582 a syntax file entry \f(CW\ebibitem[]{}\fR means that the \f(CW\ebibitem\fR command takes
583 an optional argument followed by a required one, while the entry \f(CW\ebf\fR
584 means that the \f(CW\ebf\fR command takes no arguments at all. When \fBreLyX\fR
585 encounters a token that it doesn't know how to translate into LyX, it will
586 copy the token---along with the correct number of arguments---exactly. If the
587 token is not in the syntax file, then \fBreLyX\fR just copies as many arguments
588 as it finds. This means that it may copy too much. But since the user can
589 specify additional syntax files, that shouldn't happen often.
591 Some commands that cannot be translated to LyX, like \f(CW\embox\fR, have as one of
592 their arguments regular LaTeX text. If the string \*(L"translate\*(R" is put into an
593 argument of an (untranslatable) command in the syntax file, then \fBreLyX\fR will
594 translate that argument instead of copying it verbatim. So, for example, the
595 default syntax file has \f(CW\eraisebox{}[][]{translate}\fR. This means that the
596 \f(CW\eraisebox\fR command and the first argument (and optional arguments if they
597 exist) are copied in TeX mode, but the last argument (which may contain math,
598 complicated LaTeX, other untranslatable commands, etc.) will be translated
599 into LyX. You can't use \*(L"translate\*(R" on optional arguments.
601 User-defined syntax files are allowed to define new commands and
602 their syntax, or override the number of arguments for a command given in the
603 default syntax file. (E.g., if you're using a style that gives an extra
604 argument to some command...) However, this will only be useful for commands
605 copied in TeX mode. Commands which are actually translated by \fBreLyX\fR (like
606 \f(CW\eitem\fR) have their argument syntax hard-coded. The hard-coded commands are
607 identified in the default syntax file.
609 Second, the syntax file describes any \*(L"regular environments\*(R". Usually, an
610 entire unknown environment will be copied in TeX mode. If you define a regular
611 environment \*(L"foo\*(R", though, then only the \f(CW\ebegin{foo}\fR and \f(CW\eend{foo}\fR
612 commands will be copied in TeX mode; the text within the environment will be
613 treated (i.e., translated) by \fBreLyX\fR as regular LaTeX, rather than being
614 copied into TeX mode. Don't try to declare \*(L"tabbing\*(R" and \*(L"picture\*(R" as regular
615 environments, as the text within those environments will confuse \fBreLyX\fR; use
616 this capability for new environments you create that have plain text or math
617 or simple commands in them. You also can't declare unknown math environments
618 (like equation*) as regular environments, either, since the LyX math editor
619 won't understand them. The names of regular environments appear,
620 whitespace-separated, between \f(CW\ebegin{reLyXre}\fR and \f(CW\eend{reLyXre}\fR
621 statements in the syntax file. (If you have a regular environment which you
622 won't use very often, you can use the \fB\-r\fR option rather than writing a
625 Third, the syntax file describes a math translation table. The LyX math editor
626 doesn't support a few commands. For example, \f(CW_\fR is supported, but the
627 equivalent \f(CW\esb\fR is not. Put any commands you'd like translate between
628 \f(CW\ebegin{reLyXmt}\fR and \f(CW\eend{reLyXmt}\fR statements. The statement
629 \*(L"\f(CW\e| {\eVert}\fR\*(R" means that any \f(CW\e|\fR in math mode will be converted to
630 \*(L"\f(CW\eVert \fR\*(R" (in cases where a token made up of a backslash and a non-letter is
631 translated to something with letters at the end, a space is added by \fBreLyX\fR.
632 That way, \*(L"\f(CW\e|a\fR\*(R" is correctly translated to \*(L"\f(CW\eVert a\fR").
634 You need Perl version 5.002 or later to run \fBreLyX\fR. <plug> If you don't have
635 Perl, you should get it anyway (at http://www.perl.com), because it's a really
636 useful tool for pretty much anything. </plug>
638 \fBreLyX\fR should always explain why it crashes, if it crashes. Some diagnostics
639 may be very technical, though, if they come from the guts of the code.
640 \fBreLyX\fR gives much more information while running if you use the \fB\-d\fR option,
641 but you shouldn't need that unless something goes wrong.
643 When it's finished, \fBreLyX\fR will tell you if it finished successfully or
644 died due to some error.
646 Always keep a copy of your original LaTeX files either under a different
647 name or in a different directory. There are a couple ways in which using LyX
648 could lead to overwriting the original LaTeX file.
650 If you import foo.tex to create foo.lyx, then edit foo.lyx and want to
651 re-export it, note that it will overwrite the original foo.tex. (LyX will ask
652 you if you want to overwrite it.)
654 If you have the \euse_tempdir variable set to false in your lyxrc, then LyX
655 will create its temporary files in your current directory, which means your
656 LaTeX original may be overwritten (without a warning from LyX) when you \*(L"view
657 dvi\*(R" or print the LyX document.
659 .Ip "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout" 4
660 User's personal layout files for document classes
661 .Ip "\fI\s-1MY_LYXDIR\s0\fR/reLyX/syntax.default" 4
662 User's personal syntax file
663 .Ip "\fI\s-1LIBDIR\s0\fR/layouts/*.layout" 4
664 System-wide layout files for document classes
665 .Ip "\fI\s-1LIBDIR\s0\fR/reLyX/syntax.default" 4
666 System-wide LaTeX syntax file
668 \fI\s-1LIBDIR\s0\fR is the system-wide LyX directory, usually something like
669 /usr/local/share/lyx/. \fI\s-1MY_LYXDIR\s0\fR is your personal LyX directory, something
670 like .lyx/ in your home directory.
672 \fIlyx\fR\|(1), \fIlatex\fR\|(1)
674 Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
678 John Weiss wrote the original CleanTeX pass.
682 Jose\*' Abi\*'lio Oliveira Matos
686 Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx
690 Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug
691 reports, advice, and feature suggestions.
693 Asger K. Alstrup Nielsen and Marc Pavese provided advice.
695 Various members of the LyX developers\*(R' and users\*(R' lists provided bug reports
696 and feature suggestions.
698 \fBreLyX\fR uses a modified version the Perl TeX parser Text::TeX package written
699 by Ilya Zakharevich (ilya@math.ohio-state.edu), available on \s-1CPAN\s0.
703 .IX Name "B<reLyX> - translate well-behaved LaTeX into LyX"
707 .IX Header "SYNOPSIS"
729 .IX Header "DESCRIPTION"
731 .IX Subsection "Introduction"
739 .IX Subsection "Usage"
749 .IX Subsection "What reLyX Can Handle"
783 .IX Subsection "What reLyX Can't Handle --- But it's \s-1OK\s0"
797 .IX Subsection "What reLyX Handles Badly --- aka \s-1BUGS\s0"
805 .IX Subsection "What LyX Can't Handle"
817 .IX Subsection "The Future of reLyX"
819 .IX Header "EXAMPLES"
823 .IX Subsection "Bug Reports"
825 .IX Subsection "Implementation Details:"
845 .IX Subsection "Layout Files"
847 .IX Subsection "Syntax Files"
849 .IX Subsection "Miscellaneous"
851 .IX Header "DIAGNOSTICS"
853 .IX Header "WARNINGS"
857 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/layouts/*.layout"
859 .IX Item "\fI\s-1MY_LYXDIR\s0\fR/reLyX/syntax.default"
861 .IX Item "\fI\s-1LIBDIR\s0\fR/layouts/*.layout"
863 .IX Item "\fI\s-1LIBDIR\s0\fR/reLyX/syntax.default"
865 .IX Header "SEE ALSO"
projects / lyx.git / blob