Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TEX2LYX(1)			tex2lyx	2.3.4.2			    TEX2LYX(1)

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 re-
       sulting	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 mod-
       ule1[,module2...]]   [ -s sfile1[,sfile2...]]  [	 -skipchildren	 ]   [
       -roundtrip ] [ -copyfiles ] inputfile [ outputfile ]

OPTIONS
       -c     Class.  By default, when tex2lyx sees a \documentclass{foo} com-
	      mand, it creates a file of textclass "foo"  and  reads  the  LyX
	      layout   file   for   that   class   (something	like  /usr/lo-
	      cal/share/lyx/layouts/foo.layout	OR  HOME/.lyx/layouts/foo.lay-
	      out).   Use -c to	declare	a different textclass (and read	a dif-
	      ferent 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  ex-
	      isting  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 mod-
	      ules 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 en-
	      codings file.  tex2lyx will ignore any  encoding	changing  com-
	      mands 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 \in-
	      put.  This option	is useful if the child documents are generated
	      files  and/or contain many commands that tex2lyx does not	under-
	      stand 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 de-
	      tails.

       -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	direc-
	      tory if the output file is located in a different	directory than
	      the input	file. This is useful if	you want to ensure that	no in-
	      cluded  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 ex-
       ist and does not	have one of these suffixes, tex2lyx will try to	trans-
       late 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:

       o   Get through a well-behaved LaTeX2e file without crashing

       o   Translate a lot of that file.

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

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

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

       o   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 ex-
	   actly 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.

       o   PROOFREAD THE DOCUMENT!!

	   I'm	sure you were planning on doing	this anyway, but it's particu-
	   larly important after translating a LaTeX document. tex2lyx is bet-
	   ter	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 im-
	   proved, but it's not	perfect.

   What	tex2lyx	Can Handle
       tex2lyx understands many	LaTeX commands.	It will	translate:

       o   regular text, including mini-commands like ~, `', \@, \TeX, as well
	   as accented characters like \'{a}, and the special cases ?` and !`

       o   title  commands  like  \author,  \date, \title, \thanks and the ab-
	   stract environment

       o   heading commands like \section including  starred  commands	(\sec-
	   tion*)

       o   Environments:  quote, quotation, and	verse; center, flushright, and
	   flushleft

       o   itemize, enumerate, and description environments, and  their	 \item
	   commands.  Also, well-behaved nested	lists

       o   cross-referencing commands: \ref, \pageref, \label, and \cite

       o   \footnote and \margin

       o   font-changing  commands  including  \em, \emph, \textit, and	corre-
	   sponding commands to	change family, size, series, and shape

       o   \input{foo} (or \input{foo.blah}) and \include{foo}.	Plain TeX \in-
	   put command "\input foo.tex"	is also	supported.

       o   tabular  environment,  and  commands	that go	inside it like \hline,
	   \cline, and \multicolumn (but see below)

       o   float environments table and	table*,	as well	as  \caption  commands
	   within them

       o   float  environments	figure and figure*, as well as graphics	inclu-
	   sion	commands \epsf,	\epsffile, \epsfbox, \epsfxsize, \epsfig, \ps-
	   fig,	and \includegraphics.  Both the	graphics and graphicx forms of
	   \includegraphics are	supported.

       o   thebibliography environment and \bibitem command, as	well  as  Bib-
	   TeX's \bibliography and \bibliographystyle commands

       o   miscellaneous commands: \hfill, \\, \noindent, \ldots...

       o   documentclass-specific  environments	 (and some commands) which can
	   be translated to LyX	layouts

       o   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  \be-
       gin{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
       o   some	spacing	commands (\hspace, \pagebreak and \linebreak)

       o   \centering, \raggedleft, \raggedright

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

       o   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 rec-
       ognize  the  "foo"  environment,	 it  will  copy	verbatim until it sees
       \end{foo} (unless you use the -r	option). Most of  these	 unknown  com-
       mands  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.

       o   "Exact"  copying  of	 unknown environments and commands isn't quite
	   exact.  This	will yield ugly	LyX, but in almost all cases the  out-
	   put	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 com-
	   mands, and skip blocks.

       o   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 com-
	   mands,  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 set-
	   tings  will	be  overwritten	if you modify the text layout in LyX's
	   document settings. Better remove these special options from the La-
	   TeX	preamble (Document->Settings->LaTeX Preamble) and use the cor-
	   responding LyX document settings, if	possible.

       o   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  en-
	   vironment 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  men-
       tioned 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.

       o   For a number	of commands (such as \\), LyX does not support the op-
	   tional argument.  tex2lyx will automatically	discard	 the  optional
	   arguments with a warning to stdout.	LyX also ignores the width ar-
	   gument for the thebibliography environment.

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

       o   LyX allows figures to have sizes in the units known to TeX, such as
	   in, cm, etc.	It also	translates percentages of  \textwidth,	\text-
	   height,  \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  nec-
       essary.	 When  it finds	a \begin{myenv}	... \end{myenv}	block, it will
       translate the stuff within the block, but copy the \begin and \end com-
       mands in	TeX mode.

       tex2lyx -n -c "literate-article"	foo.tex

       The above will change a noweb document into a LyX literate-article doc-
       ument. A	user would do this if the noweb	document had documentclass ar-
       ticle.

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 in-
       clude  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 com-
       plete file which	causes the same	problem	as your	original file.

   Layout Files
       tex2lyx	reads  a  LyX layout file to know how to handle	LaTeX environ-
       ments 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  syn-
       tax  file.   tex2lyx  will read your personal syntax file if it exists;
       otherwise it will read the system-wide file. tex2lyx  will  read	 addi-
       tional  syntax files if you specify them	with the -s option. (These ex-
       tra 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  re-
       quired  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	verba-
       tim.   So,   for	  example,   the   default  syntax  file  has  \raise-
       box{}[][]{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 com-
       mands 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 en-
       vironment will be treated (i.e.,	translated) by tex2lyx as regular  La-
       TeX, rather than	being copied into TeX mode. Don't try to declare "tab-
       bing" and "picture" as regular environments, as the text	 within	 those
       environments will confuse tex2lyx; use this capability for new environ-
       ments 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	under-
       stand  them. The	names of regular environments appear, whitespace-sepa-
       rated, 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 differ-
       ent 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 "chkcon-
       fig.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/local/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  per-
       sonal 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-de-
       vel@lists.lyx.org)

Version	2.3.4.2			  2020-02-07			    TEX2LYX(1)

NAME | SYNOPSIS | OPTIONS | DESCRIPTION | EXAMPLES | NOTES | WARNINGS | ENVIRONMENT | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tex2lyx&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help