anne/lyx_mirror
1
0
Fork 0
mirror of https://git.lyx.org/repos/lyx.git synced 2024-11-09 18:31:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

* src/tex2lyx/tex2lyx.man:

Browse Source 
- make the man page a bit less outdated (bug 2770).

note that the page isn't really up to date yet. I didn't check anything thoroughly (especially the "what's supported" and "what's not supported" part). Uwe, maybe a job for you, as you are most familiar with it nowadays.

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@24386 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Jürgen Spitzmüller 2008-04-20 15:22:17 +00:00
parent b35b731fbf
commit 5445b04a9b
1 changed files with 48 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
src/tex2lyx/tex2lyx.man
View File

@ -198,15 +198,15 @@ in LyX. That runs \fBtex2lyx\fR 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.
.PP
\fBtex2lyx\fR [ \fB\-c\fR \fItextclass\fR ] [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ] [\fB\-n\fR]
[\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
\fIinputfile\fR
\fBtex2lyx\fR [ \fB\-df\fR ] [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
[\fB\-n\fR] [\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
\fIinputfile\fR [ \fB\-c\fR \fItextclass\fR ]
.PP
\fBtex2lyx\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR [ \fB\-df\fR ] [ \fB\-o\fR \fIoutputdir\fR ]
\fBtex2lyx\fR [ \fB\-df\fR ] [ \fB\-userdir\fR \fIuserdir\fR ] [ \fB\-systemdir\fR \fIsystemdir\fR ]
[\ \fB\-r\fR\ \fIrenv1\fR[,\fIrenv2\fR...]] [\ \fB\-s\fR\ \fIsfile1\fR[,\fIsfile2\fR...]]
\fIinputfiles\fR
\fIinputfiles\fR \fB\-p\fR \fB\-c\fR \fItextclass\fR
.PP
\fBtex2lyx\fR \fB\-h\fR
\fBtex2lyx\fR \fB\-help\fR
.SH "OPTIONS"
.Ip "\fB\-c\fR" 4
Class. By default, when \fBtex2lyx\fR sees a \f(CW\edocumentclass{foo}\fR command, it
@ -219,22 +219,14 @@ Debug. By default, \fBtex2lyx\fR gives sparse output and deletes the temporary f
which were created during translation. Using the \fB\-d\fR flag will create much
more output (both to stdout and stderr) and leave the temporary files around.
.Ip "\fB\-f\fR" 4
Force. \fBtex2lyx\fR will not run if the .lyx file it would generate already exists
Force. \fBtex2lyx\fR will not run if the .lyx file it would generate already exists.
Use the \fB\-f\fR option (carefully) to clobber any existing files.
.Ip "\fB\-h\fR" 4
.Ip "\fB\-help\fR" 4
Help. Print out usage information and quit.
.Ip "\fB\-n\fR" 4
Noweb. Translate a noweb (aka literate programming) file. This should be
(almost?) equivalent to running \*(L"noweb2lyx foo.tex foo.lyx\*(R". This option
requires the \fB\-c\fR option.
.Ip "\fB\-o\fR" 4
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 \fB\-p\fR option) will be put into \fIoutputdir\fR. Otherwise, for
each file \fIdir/foo.tex\fR, the temporary files and the LyX output file will be
created in \fIdir\fR. 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.
.Ip "\fB\-p\fR" 4
Partial file. The input files are LaTeX fragments, with no preamble matter or
\f(CW\ebegin{document}\fR commands. This option requires the \fB\-c\fR option, since there
@ -251,10 +243,16 @@ file.
.Ip "\fB\-s\fR" 4
Syntax files. Input (one or more quoted, comma-separated) syntax files to read
in addition to the default. (see the section on \fISyntax Files\fR for details).
.Ip "\fB\-sysdir\fR" 4
Specify a system directory. Normally, you shouldn't need this. Your LyX system directory is
chosen. Cf. the section \f(CWFILES\fR for details.
.Ip "\fB\-userdir\fR" 4
Specify a user directory. Normally, you shouldn't need this. Your LyX user directory is
chosen. Cf. the section \f(CWFILES\fR for details.
.SH "DESCRIPTION"
.Sh "Introduction"
\fBtex2lyx\fR will create a LyX file \fIdir/foo.lyx\fR from the LaTeX file
\fIdir/foo.tex\fR (unless the \fB\-o\fR option is used).
\fIdir/foo.tex\fR.
.PP
Suffixes .tex, .ltx and .latex are supported. If \fIinputfile\fR
does not exist and does not have one of these suffixes, \fBtex2lyx\fR will try to
@ -262,7 +260,7 @@ translate \fIinputfile.tex\fR. (This is similar to the behavior of LaTeX.)
.PP
The purpose of \fBtex2lyx\fR is to translate \fIwell-behaved\fR 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
standard LaTeX commands---it may choke. LaTeX209 will often be translated
correctly, but it's not guaranteed.
.PP
\fBtex2lyx\fR has some bugs and lacks a few features. However, its main goals are:
@ -288,23 +286,23 @@ Run \fBtex2lyx\fR.
you don't want any output at all, try (in csh) \*(L'tex2lyx foo.tex >& /dev/null\*(R'.
You should \s-1NOT\s0 redirect standard output to \fIfoo.lyx\fR.
.Ip "\(bu" 4
Run LyX (version 0.12 or 1.0 or later) on the resulting .lyx file.
Run LyX (version 1.4 or later) on the resulting .lyx file.
.Sp
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
untranslatable will be transferred to TeX mode (ERT in LyX-speak). 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
that untranslated ERT stuff will be passed directly back to LaTeX, which LyX
uses as a backend. Unfortunately, reality doesn't always reflect theory. If
\fBtex2lyx\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.
.Ip "\(bu" 4
Change things that are highlighted in red (TeX mode) by hand in LyX.
Change things that are highlighted in ERT (TeX mode) by hand in LyX.
.Sp
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 \s-1WYSIWYM\s0 editing.
.Sp
\fBtex2lyx\fR is not guaranteed to create a LyX file which generates exactly the same
output as the LaTeX file, but it should come close. \fBrelyX\fR will generally err
output as the LaTeX file, but it should come close. \fBtex2lyx\fR will generally err
on the side of translating less to ensure that dvi or ps files are accurate,
even though this leads to more \*(L"evil red text\*(R" and less \s-1WYSIWYM\s0.
.Ip "\(bu" 4
@ -380,8 +378,6 @@ course show up in the LyX window. Check Layout->LaTeX Preamble to make sure.
.Ip "\(bu" 4
tabular* tables
.Ip "\(bu" 4
minipages
.Ip "\(bu" 4
spacing commands (\f(CW\evspace\fR, \f(CW\epagebreak\fR, \f(CW\epar\fR, ...)
.Ip "\(bu" 4
\f(CW\ecentering\fR, \f(CW\eraggedleft\fR, \f(CW\eraggedright\fR
@ -402,13 +398,6 @@ editing either the .tex or the .lyx file using a text editor.
Since \fBtex2lyx\fR is relatively new, it's got a number of problems. As it
matures, these bugs will be squished.
.PP
If \fBtex2lyx\fR is choking on something, or LyX can't read it after \fBtex2lyx\fR
translates it, the best thing to do is to put \f(CW\ebegin{tex2lyxskip}\fR before the
offending text, and \f(CW\eend{tex2lyxskip}\fR after it. I call this a \*(L"skip\*(R" block.
\fBtex2lyx\fR will copy this block exactly, in TeX mode. Then edit the resulting
LyX file, and translate the unknown stuff by hand. The tex2lyxskip environment
is magical; the \f(CW\ebegin\fR and \f(CW\eend\fR commands will not be put into the LyX
file.
.Ip "\(bu" 4
\*(L"Exact\*(R" copying of unknown environments and commands isn't quite exact.
Specifically, newlines and comments may be lost. This will yield ugly LyX, but
@ -428,27 +417,31 @@ 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->Paper
popup. So you should remove the options from the preamble
(Layout->Latex Preamble) to be safe. The same goes for setting your language
with babel, \f(CW\einputencoding\fR, \f(CW\epagestyle\fR, etc.
(Layout->Latex Preamble) to be safe. The same goes for \f(CW\einputencoding\fR,
\f(CW\epagestyle\fR, etc.
.Ip "\(bu" 4
The foil class has a couple bugs. \fBtex2lyx\fR may do weird things with optional
\fBtex2lyx\fR doesn't handle unicode yet. So if you have an utf8-encoded tex file, some
characters might not be (well) supported. Also, the output format of \fBtex2lyx\fR
is that of LyX 1.4 until unicode support is implemented. Thus, newer features cannot be
supported natively.
.Ip "\(bu" 4
The foil class has a couple of bugs. \fBtex2lyx\fR may do weird things with optional
arguments to \f(CW\efoilhead\fR commands. Also, it may handle \f(CW\ebegin{dinglist}\fR
incorrectly (although the stuff in the environment should translate normally).
.PP
Less significant bugs can be found in the \fI\s-1BUGS\s0\fR file.
Less significant bugs can be found on \fI\s-1http://bugzilla.lyx.org\s0\fR.
.PP
\fBtex2lyx\fR 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 \fI\s-1BUGS\s0\fR file---see
problem is not one of those mentioned above or on \fI\s-1http://bugzilla.lyx.org\s0\fR---see
the section on \fIBug Reports\fR.
.Sh "What LyX Can't Handle"
LyX itself is missing a couple features, such that even if \fBtex2lyx\fR translates
LyX itself is missing a couple of features, such that even if \fBtex2lyx\fR 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 \fI\s-1BUGS\s0\fR for more details on these bugs.
.Ip "\(bu" 4
For a number of commands, LyX does not support the optional argument. Examples
include \f(CW\echapter\fR (and other sectioning commands), and \f(CW\e\e\fR.
For a number of commands (such as \f(CW\e\e\fR), LyX does not support the optional argument.
\fBtex2lyx\fR will automatically discard the optional arguments with a warning to
stdout. LyX also ignores the width argument for the thebibliography
environment.
@ -481,14 +474,13 @@ Bugs will be eradicated.
.PP
See the \s-1TODO\s0 file for details.
.SH "EXAMPLES"
tex2lyx \fB\-df\fR \fB\-o\fR \*(L"my/dir\*(R" \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
tex2lyx \fB\-df\fR \fB\-r\fR \*(L"myenv\*(R" foo.tex > foo.debug
.PP
The above will create a file my/dir/foo.lyx from foo.tex, overwriting if
The above will create a file foo.lyx from foo.tex, overwriting if
necessary. When it finds a \f(CW\ebegin{myenv} ... \eend{myenv}\fR block, it will
translate the stuff within the block, but copy the \f(CW\ebegin\fR and \f(CW\eend\fR
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.
and output lots of debugging information into the file foo.debug.
.PP
tex2lyx \fB\-n\fR \fB\-c\fR \*(L"literate-article\*(R" foo.tex
.PP
@ -498,18 +490,19 @@ article.
.SH "NOTES"
.Sh "Bug Reports"
If \fBtex2lyx\fR is crashing or otherwise acting strangely---in ways
other than those described in the section on \fI\s-1BUGS\s0\fR or the \fI\s-1BUGS\s0\fR file---then please run
other than those described in the section on \fI\s-1BUGS\s0\fR or on
\fI\s-1http://bugzilla.lyx.org\s0\fR---then please run
\fBtex2lyx \-d\fR. That will allow you to figure out where in the tex2lyxing 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.
.PP
Bug reports should be sent to the LyX developers\*(R' 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 \fBtex2lyx\fR 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.
Bug reports should either be posted to http://bugzilla.lyx.org or sent to the
LyX developers\*(R' 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 \fBtex2lyx\fR 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.
.Sh "Implementation Details:"
\fBtex2lyx\fR makes several \*(L"passes\*(R" in order to translate a TeX file. On each pass,
it creates one or two files.
@ -620,10 +613,6 @@ whitespace-separated, between \f(CW\ebegin{tex2lyxre}\fR and \f(CW\eend{tex2lyxr
statements in the syntax file. (If you have a regular environment which you
won't use very often, you can use the \fB\-r\fR option rather than writing a
syntax file.)
.Sh "Miscellaneous"
You need Perl version 5.002 or later to run \fBtex2lyx\fR. <plug> If you don't have
Perl, you should get it anyway (at http://www.perl.com), because it's a really
useful tool for pretty much anything. </plug>
.SH "DIAGNOSTICS"
\fBtex2lyx\fR 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.
@ -661,32 +650,10 @@ like .lyx/ in your home directory.
.SH "SEE ALSO"
\fIlyx\fR\|(1), \fIlatex\fR\|(1)
.SH "AUTHORS"
Copyright (c) 1998-9 Amir Karger (karger@post.harvard.edu)
tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)
.PP
Code contributors:
.Ip "\(bu" 4
John Weiss wrote the original CleanTeX pass.
.Ip "\(bu" 4
Etienne Grossmann
.Ip "\(bu" 4
Jose\*' Abi\*'lio Oliveira Matos
.Ip "\(bu" 4
David Suarez de Lis
.Ip "\(bu" 4
Kayvan Aghaiepour Sylvan added noweb stuff and wrote noweb2lyx
.PP
Other contributors:
.Ip "\(bu" 4
Jean-Marc Lasgouttes worked on the wrapper script and offered lots of bug
reports, advice, and feature suggestions.
.Ip "\(bu" 4
Asger K. Alstrup Nielsen and Marc Pavese provided advice.
.Ip "\(bu" 4
Various members of the LyX developers\*(R' and users\*(R' lists provided bug reports
and feature suggestions.
.rn }` ''
.IX Title "RELYX 1"
.IX Title "TEX2LYX 1"
.IX Name "B<tex2lyx> - translate well-behaved LaTeX into LyX"
.IX Header "NAME"
@ -701,7 +668,7 @@ and feature suggestions.
.IX Item "\fB\-f\fR"
.IX Item "\fB\-h\fR"
.IX Item "\fB\-help\fR"
.IX Item "\fB\-n\fR"