Home
Main website
Display Sidebar
Hide Ads
Recent Changes
View Source:
reLyX(1)
Edit
PageHistory
Diff
Info
LikePages
RELYX !!!RELYX N NA AM ME E S SY YN NO OP PS SI IS S O OP PT TI IO ON NS S D DE ES SC CR RI IP PT TI IO ON N E EX XA AM MP PL LE ES S N NO OT TE ES S D DI IA AG GN NO OS ST TI IC CS S W WA AR RN NI IN NG GS S F FI IL LE ES S S SE EE E A AL LS SO O A AU UT TH HO OR RS S ---- !!N NA AM ME E __rreeLLyyXX__ - translate well-behaved LaTeX into LyX !!S SY YN NO OP PS SI IS S The simplest way to use __rreeLLyyXX__ is via the File- __rreeLLyyXX__ on the given file and loads the resulting file into LyX. You should try that first, and call it from the command line only if you need to use more complicated options. __rreeLLyyXX__ [[ __--cc__ ''textclass'' ] [[ __--ddff__ ] [[ __--oo__ ''outputdir'' ] [[__--nn__] [[ __--rr__ ''renv1''[[,''renv2''...]] [[ __--ss__ ''sfile1''[[,''sfile2''...]] ''inputfile'' __rreeLLyyXX --pp --cc__ ''textclass'' [[ __--ddff__ ] [[ __--oo__ ''outputdir'' ] [[ __--rr__ ''renv1''[[,''renv2''...]] [[ __--ss__ ''sfile1''[[,''sfile2''...]] ''inputfiles'' __rreeLLyyXX --hh__ !!O OP PT TI IO ON NS S __--cc__ Class. By default, when __rreeLLyyXX__ sees a documentclass{foo} command, it creates a file of textclass ``foo'' and reads the LyX layout file for that class (something like /usr/local/share/lyx/layouts/foo.layout OR __HHOOMMEE__ /.lyx/layouts/foo.layout). Use __--cc__ to declare a different textclass (and read a different layout file). __--dd__ Debug. By default, __rreeLLyyXX__ gives sparse output and deletes the temporary files which were created during translation. Using the __--dd__ flag will create much more output (both to stdout and stderr) and leave the temporary files around. __--ff__ Force. __rreeLLyyXX__ will not run if the .lyx file it would generate already exists Use the __--ff__ option (carefully) to clobber any existing files. __--hh__ Help. Print out usage information and quit. __--nn__ Noweb. Translate a noweb (aka literate programming) file. This should be (almost?) equivalent to running ``noweb2lyx foo.tex foo.lyx''. This option requires the __--cc__ option. __--oo__ Output directory. With this option, all temporary files and LyX output files (for the given input file, for any included files, or for any file fragments given with the __--pp__ option) will be put into ''outputdir''. Otherwise, for each file ''dir/foo.tex'', the temporary files and the LyX output file will be created in ''dir''. This can be useful if a file includes files from other directories which you want to consolidate in one directory, or if you don't have write permission on the directory the LaTeX files are in. __--pp__ Partial file. The input files are LaTeX fragments, with no preamble matter or begin{document} commands. This option requires the __--cc__ option, since there are no documentclass commands in the files __rreeLLyyXX__ is translating. When using this option, you can translate more than one file, as long as all files are the same class. The LyX file created by __rreeLLyyXX__ can be included in an existing LyX file using the ``Include LyX File'' command from LyX's Insert menu. __--rr__ Regular environments (see the section on ''Syntax Files''). If you give more than one environment, separate them with commas (not spaces). You'll probably need to quote the environment list, especially if it has asterisk environments (foo*) in it. If you use this command often, considering creating a personal syntax file. __--ss__ Syntax files. Input (one or more quoted, comma-separated) syntax files to read in addition to the default. (see the section on ''Syntax Files'' for details). !!D DE ES SC CR RI IP PT TI IO ON N __IInnttrroodduuccttiioonn__ __rreeLLyyXX__ will create a LyX file ''dir/foo.lyx'' from the LaTeX file ''dir/foo.tex'' (unless the __--oo__ option is used). Suffixes .tex, .ltx and .latex are supported. If ''inputfile'' does not exist and does not have one of these suffixes, __rreeLLyyXX__ will try to translate ''inputfile.tex''. (This is similar to the behavior of LaTeX.) The purpose of __rreeLLyyXX__ is to translate ''well-behaved'' LaTeX2e into LyX. If your LaTeX file doesn't compile---or if you do weird things, like redefining standard !LaTex commands---it may choke. LaTeX209 will often be translated correctly, but it's not guaranteed. __rreeLLyyXX__ has some bugs and lacks a few features. However, its main goals are: Get through a well-behaved LaTeX2e file without crashing Translate a lot of that file. Localize the parts that can't be translated and copy them in TeX mode It achieves these main goals pretty well on most files. There are many improvements that can and will be made to __rreeLLyyXX__ in the future. However, we wanted to get __rreeLLyyXX__ out there early on, to make it easier for new LyX users to read in their existing LaTeX files. __UUssaaggee__ Here's a more lengthy description of what you should do to translate a LaTeX document into LyX. Run __rreeLLyyXX__. __rreeLLyyXX__ will inform you of its progress and give any warnings to stderr, so if you don't want any output at all, try (in csh) `reLyX foo.tex __NOT redirect standard output to ''foo.lyx''. Run LyX (version 0.12 or 1.0 or later) on the resulting .lyx file. In theory, most of the file will have been translated, and anything that's untranslatable will be highlighted in red (TeX mode). In theory, LyX will be able to read in the file, and to create printed documents from it, because all that untranslated red stuff will be passed directly back to LaTeX, which LyX uses as a backend. Unfortunately, reality doesn't always reflect theory. If __rreeLLyyXX__ crashes, or LyX cannot read the generated LyX file, see the BUGS entry elsewhere in this document or the ''BUGS'' file. Change things that are highlighted in red (TeX mode) by hand in LyX. As mentioned above, you should be able to print out the LyX file even without doing this. However, changing a command in TeX mode to the corresponding LyX object will allow you to take advantage of LyX's WYSIWYM editing. __rreeLLyyXX__ is not guaranteed to create a LyX file which generates exactly the same output as the LaTeX file, but it should come close. __rreellyyXX__ will generally err on the side of translating less to ensure that dvi or ps files are accurate, even though this leads to more ``evil red text'' and less WYSIWYM . PROOFREAD THE DOCUMENT !! I'm sure you were planning on doing this anyway, but it's particularly important after translating a LaTeX document. __rreeLLyyXX__ is, at least now, better at ``macro-translating'' (translating the whole document) than ``micro-translating'' (translating every little detail). For example, you may see extra spaces or deleted spaces. Space handling has improved, but it's not perfect. __WWhhaatt rreeLLyyXX CCaann HHaannddllee__ __rreeLLyyXX__ understands many LaTeX commands. It will translate: regular text, including mini-commands like ~, `', @, TeX, as well as accented characters like '{a}, and the special cases ?` and !` title commands like author, date, title, thanks and the abstract environment heading commands like section including starred commands (section*) Environments: quote, quotation, and verse; center, flushright, and flushleft itemize, enumerate, and description environments, and their item commands. Also, well-behaved nested lists cross-referencing commands: ref, pageref, label, and cite footnote and margin font-changing commands including em, emph, textit, and corresponding commands to change family, size, series, and shape input{foo} (or input{foo.blah}) and include{foo}. Plain TeX input command ``input foo.tex'' is also supported. tabular environment, and commands that go inside it like hline, cline, and multicolumn (but see below) float environments table and table*, as well as caption commands within them float environments figure and figure*, as well as graphics inclusion commands epsf, epsffile, epsfbox, epsfxsize, epsfig, psfig, and includegraphics. Both the graphics and graphicx forms of includegraphics are supported. Note, however, that many figures will not be translatable into LyX. See the section on ``What LyX Can't Handle'' below. thebibliography environment and bibitem command, as well as BibTeX's bibliography and bibliographystyle commands miscellaneous commands: hfill, \, noindent, ldots... documentclass-specific environments (and some commands) which can be translated to LyX layouts arguments to certain untranslatable commands (e.g. mbox) Some of this support may not be 100% yet. See below for details __rreeLLyyXX__ copies math (almost) verbatim from your LaTeX file. Luckily, LyX reads in LaTeX math, so (almost) any math which is supported by LyX should work just fine. A few math commands which are not supported by LyX will be replaced with their equivalents, e.g., to is converted to rightarrow. See the section on ''Syntax Files'' for more details. __rreeLLyyXX__ will also copy any preamble commands (i.e., anything before begin{document}) verbatim, so fancy stuff you've got in your preamble should be conserved in dvi and printed documents, although it will not of course show up in the LyX window. Check Layout- __WWhhaatt rreeLLyyXX CCaann''tt HHaannddllee ------ BBuutt iitt''ss OOKK__ tabular* tables minipages spacing commands (vspace, pagebreak, par, ...) centering, raggedleft, raggedright verb and verbatim environment. __rreeLLyyXX__ is careful to copy ''exactly'' in this case, including comments and whitespace. some unknown (e.g., user-defined) environments and commands __rreeLLyyXX__ copies unknown commands, along with their arguments, verbatim into the LyX file. Also, if it sees a begin{foo} where it doesn't recognize the ``foo'' environment, it will copy verbatim until it sees end{foo} (unless you use the __--rr__ option). Hopefully, then, most of these unknown commands won't cause __rreeLLyyXX__ to break; they'll merely require you to do some editing once you've loaded the file up in LyX. That should be less painful than editing either the .tex or the .lyx file using a text editor. __WWhhaatt rreeLLyyXX HHaannddlleess BBaaddllyy ------ aakkaa BBUUGGSS__ Since __rreeLLyyXX__ is relatively new, it's got a number of problems. As it matures, these bugs will be squished. If __rreeLLyyXX__ is choking on something, or LyX can't read it after __rreeLLyyXX__ translates it, the best thing to do is to put begin{reLyXskip} before the offending text, and end{reLyXskip} after it. I call this a ``skip'' block. __rreeLLyyXX__ will copy this block exactly, in TeX mode. Then edit the resulting LyX file, and translate the unknown stuff by hand. The reLyXskip environment is magical; the begin and end commands will not be put into the LyX file. ``Exact'' copying of unknown environments and commands isn't quite exact. Specifically, newlines and comments may be lost. This will yield ugly LyX, but in almost all cases the output will be the same. However, certain parts of the file will be copied perfectly, including whitespace and comments. This includes: the LaTeX preamble, verbatim environments and verb commands, and skip blocks. __rreeLLyyXX__ translates only a few options to the documentclass command. (Specifically 1[[012]pt, [[letterlegalexecutivea4a5b5]paper, [[onetwo]side, landscape, and [[onetwo]column.) Other options are placed in the ``options'' field in the Layout- More importantly, __rreeLLyyXX__ doesn't translate usepackage commands, margin commands, newcommands, or, in fact, anything else from the preamble. It simply copies them into the LaTeX preamble. If you have margin commands in your preamble, then the LyX file will generate the right margins. However, these margins will override any margins you set in the LyX Layout- inputencoding, pagestyle, etc. The foil class has a couple bugs. __rreeLLyyXX__ may do weird things with optional arguments to foilhead commands. Also, it may handle begin{dinglist} incorrectly (although the stuff in the environment should translate normally). Less significant bugs can be found in the ''BUGS'' file. __rreeLLyyXX__ is hopefully rather robust. As mentioned above, it may not translate your file perfectly, but it shouldn't crash. If it does crash---and the problem is not one of those mentioned above or in the ''BUGS'' file---see the section on ''Bug Reports''. __WWhhaatt LLyyXX CCaann''tt HHaannddllee__ LyX itself is missing a couple features, such that even if __rreeLLyyXX__ translates things perfectly, LyX may still have trouble reading it. If you really need these features, you can export your final document as LaTeX, and put them back in. See ''BUGS'' for more details on these bugs. For a number of commands, LyX does not support the optional argument. Examples include chapter (and other sectioning commands), and \. __rreeLLyyXX__ will automatically discard the optional arguments with a warning to stdout. LyX also ignores the width argument for the thebibliography environment. Centering (or right or left justifying) works on full paragraphs. LyX support for tables isn't perfect. For complicated tables, use a ``skip'' block, so that they will be copied in TeX mode. The LyX math editor can't handle the AMS -LaTeX math environments align, split, etc. So those environments will be copied in TeX mode. You can change equation* environments to the exactly equivalent displaymath, and then they will be translated correctly. Lyx does not support clipping or bounding boxes for included graphics files. Therefore, many graphics inclusion commands will be untranslatable, and copied in TeX mode. In certain cases, you might be able to translate the command by hand within LyX---for example, if you included a bounding box but the bounding box is already in the .eps file. LyX only allows figures to have sizes in in,cm, or percentages of textwidth or textheight (or columnwidth). __rreeLLyyXX__ will translate from other units, like pt or mm, but it cannot translate other lengths (e.g. if you wanted to scale a figure to size topmargin for some reason). __rreeLLyyXX__ will copy figures with untranslatable sizes in TeX mode. Again, you might be able to fix that within LyX. __TThhee FFuuttuurree ooff rreeLLyyXX__ In the future, more commands and environments will be supported by __rreeLLyyXX__. Bugs will be eradicated. See the TODO file for details. !!E EX XA AM MP PL LE ES S reLyX __--ddff --oo__ ``my/dir'' __--rr__ ``myenv'' foo.tex __ The above will create a file my/dir/foo.lyx from foo.tex, overwriting if necessary. When it finds a begin{myenv} ... end{myenv} block, it will translate the stuff within the block, but copy the begin and end commands in TeX mode. Finally, I'm going to keep the temporary files around (they will also be in my/dir/) and output lots of debugging information into the file foo.debug. reLyX __--nn --cc__ ``literate-article'' foo.tex The above will change a noweb document into a LyX literate-article document. A user would do this if the noweb document had documentclass article. !!N NO OT TE ES S __BBuugg RReeppoorrttss__ If __rreeLLyyXX__ is crashing or otherwise acting strangely---in ways other than those described in the section on ''BUGS'' or the ''BUGS'' file---then please run __rreeLLyyXX --dd__. That will allow you to figure out where in the reLyXing process it crashed. That, in turn, will allow you to write a better bug report, which will allow the developers to fix it more quickly and easily. Bug reports should be sent to the LyX developers' mailing list. Its address is currently lyx-devel@lists.lyx.org, but you can check the LyX home page, http://www.lyx.org if that bounces. If you are running __rreeLLyyXX__ on a huge file, please do not send all of the output in your bug report. Just include the last ten or twenty lines of output, along with the piece of the LaTeX file it crashed on. Or, even better, attach a small but complete file which causes the same problem as your original file. __IImmpplleemmeennttaattiioonn DDeettaaiillss::__ __rreeLLyyXX__ makes several ``passes'' in order to translate a TeX file. On each pass, it creates one or two files. Pass 0 Before doing anything, read the syntax file (or files). Pass 1a Split preamble (anything before a begin{document} command) off the rest of the file. It saves the two pieces in separate files. This is necessary because there may be very strange stuff in a preamble. It also ignores anything after the end{document}, on the assumption that it isn't LaTeX. Pass 1b Translate the preamble. Currently, that just means translating the documentclass command and copying the rest exactly into the LyX preamble. Once you know what class the document is, read the LyX layout file for that class. Pass 2 ``Clean'' the TeX file, generating slightly stricter LaTeX. This includes: Change, e.g., x^2 to the equivalent but clearer x^{2} Removing optional arguments that LyX can't handle (e.g., from chapter) Changing {em foo} to emph{foo}, etc. This is necessary because LyX always writes out the non-local forms anyway. This should very rarely make a difference. Pass 3 Translate LaTeX text, commands, and environments to LyX. Pass 4 Put the two pieces back together, and do some final tweaking, to generate the LyX file If there are any input or include commands, __rreeLLyyXX__ will loop back to the beginning and translate those. It assumes that the included files are the same class as the main file, and that they have no preamble matter. (If you have an input command in the preamble of a file, the command will be copied exactly into the LaTeX preamble portion of the LyX file, so the included file won't be translated.) So when translating included files, it skips passes 0 and 1. If __rreeLLyyXX__ doesn't find a file you wanted to include, it will give a warning, but will continue to translate any files it does find. __LLaayyoouutt FFiilleess__ __rreeLLyyXX__ reads a LyX layout file to know how to handle LaTeX environments and commands which get translated to LyX layouts. This file will include all ``normal'' non-math environments (i.e., including quote and itemize, but not tabular, minipage, and some other fancy environments), and commands like section and title. If you want to reLyX a class that doesn't have an existing layout file, then you'll have to create a layout file. But you have to do this anyway, in order to LyX the file, since LyX depends on layout files to know how to display and process its files. Check the LyX documentation for help with this task (which can be hard or easy, depending on the class you want to create a layout file for.) If your class is quite similar to a class that has a layout file, then consider using the __--cc__ option. __SSyynnttaaxx FFiilleess__ __rreeLLyyXX__ always reads at least one syntax file, called the default syntax file. __rreeLLyyXX__ will read your personal syntax file if it exists; otherwise it will read the system-wide file. __rreeLLyyXX__ will read additional syntax files if you specify them with the __--ss__ option. (These extra files should have the same format as the default file, but will tend to be shorter, since they only have to specify extra commands not found in the default file.) A syntax file tells __rreeLLyyXX__ a few things. First, it describes the syntax of each command, that is, how many required arguments and how many optional arguments the command takes. Knowing this makes it easier for __rreeLLyyXX__ to copy (in TeX mode) commands that it doesn't know how to translate. The syntax file simply has a command, followed by braces or brackets describing its arguments in the correct order. For example, a syntax file entry bibitem[[]{} means that the bibitem command takes an optional argument followed by a required one, while the entry bf means that the bf command takes no arguments at all. When __rreeLLyyXX__ encounters a token that it doesn't know how to translate into LyX, it will copy the token---along with the correct number of arguments---exactly. If the token is not in the syntax file, then __rreeLLyyXX__ just copies as many arguments as it finds. This means that it may copy too much. But since the user can specify additional syntax files, that shouldn't happen often. Some commands that cannot be translated to LyX, like mbox, have as one of their arguments regular LaTeX text. If the string ``translate'' is put into an argument of an (untranslatable) command in the syntax file, then __rreeLLyyXX__ will translate that argument instead of copying it verbatim. So, for example, the default syntax file has raisebox{}[[][[]{translate}. This means that the raisebox command and the first argument (and optional arguments if they exist) are copied in TeX mode, but the last argument (which may contain math, complicated LaTeX, other untranslatable commands, etc.) will be translated into LyX. You can't use ``translate'' on optional arguments. User-defined syntax files are allowed to define new commands and their syntax, or override the number of arguments for a command given in the default syntax file. (E.g., if you're using a style that gives an extra argument to some command...) However, this will only be useful for commands copied in TeX mode. Commands which are actually translated by __rreeLLyyXX__ (like item) have their argument syntax hard-coded. The hard-coded commands are identified in the default syntax file. Second, the syntax file describes any ``regular environments''. Usually, an entire unknown environment will be copied in TeX mode. If you define a regular environment ``foo'', though, then only the begin{foo} and end{foo} commands will be copied in TeX mode; the text within the environment will be treated (i.e., translated) by __rreeLLyyXX__ as regular LaTeX, rather than being copied into TeX mode. Don't try to declare ``tabbing'' and ``picture'' as regular environments, as the text within those environments will confuse __rreeLLyyXX__; use this capability for new environments you create that have plain text or math or simple commands in them. You also can't declare unknown math environments (like equation*) as regular environments, either, since the LyX math editor won't understand them. The names of regular environments appear, whitespace-separated, between begin{reLyXre} and end{reLyXre} statements in the syntax file. (If you have a regular environment which you won't use very often, you can use the __--rr__ option rather than writing a syntax file.) Third, the syntax file describes a math translation table. The LyX math editor doesn't support a few commands. For example, _ is supported, but the equivalent sb is not. Put any commands you'd like translate between begin{reLyXmt} and end{reLyXmt} statements. The statement ``\ {Vert}'' means that any \ in math mode will be converted to ``Vert '' (in cases where a token made up of a backslash and a non-letter is translated to something with letters at the end, a space is added by __rreeLLyyXX__. That way, ``a'' is correctly translated to ``Vert a __MMiisscceellllaanneeoouuss__ You need Perl version 5.002 or later to run __rreeLLyyXX__. __ !!D DI IA AG GN NO OS ST TI IC CS S __rreeLLyyXX__ should always explain why it crashes, if it crashes. Some diagnostics may be very technical, though, if they come from the guts of the code. __rreeLLyyXX__ gives much more information while running if you use the __--dd__ option, but you shouldn't need that unless something goes wrong. When it's finished, __rreeLLyyXX__ will tell you if it finished successfully or died due to some error. !!W WA AR RN NI IN NG GS S Always keep a copy of your original LaTeX files either under a different name or in a different directory. There are a couple ways in which using LyX could lead to overwriting the original LaTeX file. If you import foo.tex to create foo.lyx, then edit foo.lyx and want to re-export it, note that it will overwrite the original foo.tex. (LyX will ask you if you want to overwrite it.) If you have the use_tempdir variable set to false in your lyxrc, then LyX will create its temporary files in your current directory, which means your LaTeX original may be overwritten (without a warning from LyX) when you ``view dvi'' or print the LyX document. !!F FI IL LE ES S ''MY_LYXDIR'' /layouts/*.layout User's personal layout files for document classes ''MY_LYXDIR'' /reLyX/syntax.default User's personal syntax file ''LIBDIR'' /layouts/*.layout System-wide layout files for document classes ''LIBDIR'' /reLyX/syntax.default System-wide LaTeX syntax file ''LIBDIR'' is the system-wide LyX directory, usually something like /usr/local/share/lyx/. ''MY_LYXDIR'' is your personal LyX directory, something like .lyx/ in your home directory. !!S SE EE E A AL LS SO O lyx(1), latex(1) !!A AU UT TH HO OR RS S Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu) Code contributors: John Weiss wrote the original CleanTeX pass. Etienne Grossmann Jose Abilio Oliveira Matos David Suarez de Lis Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx Other contributors: Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug reports, advice, and feature suggestions. Asger K. Alstrup Nielsen and Marc Pavese provided advice. Various members of the LyX developers' and users' lists provided bug reports and feature suggestions. __rreeLLyyXX__ uses a modified version the Perl TeX parser Text::TeX package written by Ilya Zakharevich (ilya@math.ohio-state.edu), available on CPAN . ----
2 pages link to
reLyX(1)
:
lyx(1)
Man1r
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
