Provided by: lyx_2.3.7-1_amd64 bug

NAME

       tex2lyx - translate well-behaved LaTeX into LyX

SYNOPSIS

       The  simplest  way to use tex2lyx is via the File->Import->LaTeX (plain) menu item in LyX.
       That runs tex2lyx 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.

       tex2lyx [ -userdir userdir ] [ -systemdir systemdir ] [ -f ] [ -n ] [ -c textclass ] [  -e
       encoding  ]  [ -fixedenc encoding ] [ -m module1[,module2...]]  [ -s sfile1[,sfile2...]] [
       -skipchildren ] [ -roundtrip ] [ -copyfiles ] inputfile [ outputfile ]

OPTIONS

       -c     Class. By default, when tex2lyx 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 HOME/.lyx/layouts/foo.layout).  Use
              -c to declare a different textclass (and read a different layout file).

              This  option  is  needed  if  the  input file is a LaTeX fragment, with no preamble
              matter or \begin{document} command. LyX files created by tex2lyx from partial files
              can  be  included in an existing LyX file using the “Include LyX File” command from
              LyX's Insert menu.

       -m     Module. Load the given modules. This is useful if tex2lyx  does  not  automatically
              detect  a  given  module,  but  you  know the modules that provide some commands or
              environments that are used in the imported file. The  modules  are  loaded  in  the
              given order. If a module foo depends on a module bar, bar must be given before foo.

       -f     Force. tex2lyx will not run if the .lyx file it would generate already exists.  Use
              the -f option (carefully) to clobber any existing files.

       -e     Specify the default encoding using the LaTeX name as defined in the encodings file.
              tex2lyx  will  use  this  encoding,  but  switch  if it finds any encoding changing
              commands in the input.

       -fixedenc
              Specify the encoding using the  LaTeX  name  as  defined  in  the  encodings  file.
              tex2lyx will ignore any encoding changing commands in the input.

       -n     Noweb.  Translate a noweb (aka literate programming) file. This should be (almost?)
              equivalent to running “noweb2lyx foo.tex foo.lyx”.  This  option  requires  the  -c
              option.

       -skipchildren
              Do  not translate child documents included via \include and \input.  This option is
              useful if the child documents are generated files and/or contain many commands that
              tex2lyx does not understand yet.

       -s     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).

       -sysdir
              Specify a system directory. Normally, you shouldn't  need  this.  Your  LyX  system
              directory is chosen. Cf. the section FILES for details.

       -userdir
              Specify  a  user  directory.  Normally,  you  shouldn't  need  this.  Your LyX user
              directory is chosen. Cf. the section FILES for details.

       -roundtrip
              Call LyX to re-export the created output file to LaTeX. If the output file name  is
              not  given  it  is determined automatically to avoid over-writing the input file by
              accident: If the input file  is  named  foo.tex  the  output  file  will  be  named
              foo.lyx.lyx, and the re-exported file will be named foo.lyx.tex.

       -copyfiles
              Copy  all  included files tex2lyx is aware of to the output directory if the output
              file is located in a different directory than the input file. This is useful if you
              want to ensure that no included file is overwritten (either in roundtrip mode or by
              a later  export  from  LyX).  Please  note  that  the  resulting  document  may  be
              uncompilable.  This  happens if it needs files that tex2lyx does not know about and
              therefore does not copy to the output directory.

       -help  Help. Print out usage information and quit.

       -version
              Print out the version number and build information and quit.

DESCRIPTION

   Introduction
       tex2lyx will create a LyX file with the specified name (or  dir/foo.lyx  if  no  name  was
       given) from the LaTeX file dir/foo.tex.

       Suffixes  .tex,  .ltx  and  .latex are supported. If inputfile does not exist and does not
       have one of these suffixes, tex2lyx will try to translate inputfile.tex. (This is  similar
       to the behavior of LaTeX.)

       The  purpose  of tex2lyx 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.

       tex2lyx 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.

   Usage
       Here's a more lengthy description of what you should do to translate a LaTeX document into
       LyX.

       •   Run tex2lyx.

           tex2lyx 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) `tex2lyx foo.tex >& /dev/null'.  You should
           NOT redirect standard output to foo.lyx.

       •   Run LyX (version 2.1 or later) on the resulting .lyx file.

           In  theory,  most  of  the  file  will  have  been  translated,  and  anything  that's
           untranslatable will be transferred to TeX code (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  ERT  stuff  will  be  passed directly back to LaTeX, which LyX uses as a
           backend. Unfortunately, reality doesn't always reflect theory. If tex2lyx crashes,  or
           LyX cannot read the generated LyX file, see the BUGS section below.

       •   Transform things have been inserted as TeX code manually to LyX features, if possible.

           As  mentioned  above,  you should be able to print out the LyX file even without doing
           this. However, changing a command in TeX code to the  corresponding  LyX  object  will
           allow you to take advantage of LyX's WYSIWYM editing.

           tex2lyx is not guaranteed to create a LyX file which generates exactly the same output
           as the LaTeX file, although its goal is to achieve this. tex2lyx will generally err on
           the  side  of translating less to ensure that the resulting output files are accurate,
           even though this leads to more TeX code 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. tex2lyx is 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.

   What tex2lyx Can Handle
       tex2lyx 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.

       •   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

       tex2lyx  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.

       tex2lyx will copy any preamble commands (i.e., anything before \begin{document}) verbatim.
       Fancy  stuff  you've  got  in your preamble should thus be conserved in printed documents,
       although it will not of course show up in the LyX window. Check  Document->Settings->LaTeX
       Preamble to see the result.

   What tex2lyx Can't Handle --- But it's OK
       •   some spacing commands (\hspace, \pagebreak and \linebreak)

       •   \centering, \raggedleft, \raggedright

       •   \verb  and  verbatim  environment.  tex2lyx  is  careful to copy exactly in this case,
           including comments and whitespace.

       •   unknown (e.g., user-defined) environments and commands

       tex2lyx 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  -r  option).  Most  of  these
       unknown  commands  won't  cause  tex2lyx  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.

   What tex2lyx Handles Badly --- aka BUGS
       Since tex2lyx is relatively new, it's got a number of problems.  As it matures, these bugs
       will be squished.

       •   “Exact” copying of unknown environments and commands isn't  quite  exact.   This  will
           yield  ugly  LyX,  but in almost all cases the output will be the same.  However, most
           parts of the file will be copied perfectly, including whitespace  and  comments.  This
           includes:  the  LaTeX  preamble,  verbatim environments as well as \verb commands, and
           skip blocks.

       •   tex2lyx translates only a subset of the document class  options  to  native  features.
           Other options are placed in the “options” field in the Document->Settings popup.

           More importantly, tex2lyx doesn't translate \newcommands, unknown \usepackage commands
           and other unknown code in the preamble. It simply copies that into the LaTeX preamble.
           If you use special commands, e.g. to specify the text layout in a way that that is not
           understood by LyX, tex2lyx won't recognize  it.  Note  that  these  settings  will  be
           overwritten  if  you  modify the text layout in LyX's document settings. Better remove
           these special options from the LaTeX preamble (Document->Settings->LaTeX Preamble) and
           use the corresponding LyX document settings, if possible.

       •   The  foil  document  class  has  a  couple  of  bugs. tex2lyx 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).

       All known bugs of tex2lyx can be found on http://www.lyx.org/trac/wiki/BugTrackerHome.

       tex2lyx  is  rather  robust. As mentioned above, it may not translate your file perfectly,
       but the result should be usable and it shouldn't crash. If  you  encounter  problems---and
       the     problem     is     not     one     of     those     mentioned    above    or    on
       http://www.lyx.org/trac/wiki/BugTrackerHome---please report the issue as described in  the
       section on Bug Reports.

   What LyX Can't Handle
       LyX  itself  is  missing a couple of features, such that even if tex2lyx 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 (such as \\), LyX does not  support  the  optional  argument.
           tex2lyx  will  automatically  discard the optional arguments with a warning to stdout.
           LyX also ignores the width argument for the thebibliography environment.

       •   LyX support for tables isn't perfect. For complicated tables, use a “skip”  block,  so
           that they will be copied in TeX mode.

       •   LyX  allows  figures  to have sizes in the units known to TeX, such as in, cm, etc. It
           also translates percentages of \textwidth, \textheight,  \columnwidth,  but  no  other
           lengths  (e.g.  if  you  wanted to scale a figure to size \topmargin for some reason).
           tex2lyx will copy figures with untranslatable sizes in TeX mode. Again, you  might  be
           able to fix that within LyX.

EXAMPLES

       tex2lyx -f -r “myenv” foo.tex

       The  above  will  create  a  file 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.

       tex2lyx -n -c “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.

NOTES

   Bug Reports
       Bugs     should     be     reported     to      the      LyX      bug      tracker      at
       http://www.lyx.org/trac/wiki/BugTrackerHome.  Additionally,  you can post a message to the
       LyX developers' mailing list. Its address is currently  lyx-devel@lists.lyx.org.  If  your
       message  bounces, you can check the LyX home page, http://www.lyx.org/. If you are running
       tex2lyx 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.

   Layout Files
       tex2lyx  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 tex2lyx 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 -c option.

   Syntax Files
       tex2lyx always reads at least one syntax file, called the default  syntax  file.   tex2lyx
       will  read  your personal syntax file if it exists; otherwise it will read the system-wide
       file. tex2lyx will read additional syntax files if you specify them with  the  -s  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 tex2lyx 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 tex2lyx 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 tex2lyx 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 tex2lyx 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 tex2lyx 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 tex2lyx
       (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  tex2lyx  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 tex2lyx; 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{tex2lyxre}   and
       \end{tex2lyxre}  statements  in  the syntax file. (If you have a regular environment which
       you won't use very often, you can use the -r option rather than writing a syntax file.)

WARNINGS

       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.)

ENVIRONMENT

       LYX_DIR_23x
             can be used to specify which system directory to use.

       The system directory is determined by searching for the file "chkconfig.ltx".  Directories
       are searched in this order:
       1) -sysdir command line parameter
       2) LYX_DIR_23x environment variable
       3) Maybe <path of binary>/TOP_SRCDIR/lib
       4) <path of binary>/../share/<name of binary>/
       5) hardcoded lyx_dir (at build time: /usr/share/lyx)

       LYX_USERDIR_23x
              can be used to specify which user directory to use.

       The user directory is, in order of precedence:
       1) -userdir command line parameter
       2) LYX_USERDIR_23x environment variable
       3) $HOME/.<name of binary> if no explicit setting is made

FILES

       If  LIBDIR  is the system-wide LyX directory and MY_LYXDIR is your personal LyX directory,
       then the following files are read by tex2lyx:

       MY_LYXDIR/layouts/*.layout
           User's personal layout files for document classes

       MY_LYXDIR/syntax.default
           User's personal syntax file

       MY_LYXDIR/encodings
           User's personal encoding definition file

       LIBDIR/layouts/*.layout
           System-wide layout files for document classes

       LIBDIR/lib/syntax.default
           System-wide LaTeX syntax file

       LIBDIR/lib/encodings
           System-wide encoding definition file

SEE ALSO

       lyx(1), latex(1)

AUTHORS

       tex2lyx is Copyright (c) 2003ff. by the LyX Team (lyx-devel@lists.lyx.org)