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