
 
 
 
 This file documents LaTeX2RTF , a converter that translates
LaTeX  to RTF.
 
 Copyright 1998-2002 Georg Lehner, minor updates by
Wilfried Hennings and
 Scott Prahl
 
 Permission is granted to make
and distribute verbatim copies of this
 manual provided the copyright
notice and this permission notice are
 preserved on all copies.
 
versions of this manual under the conditions for verbatim copying,
provided also that the sections entitled "Copying" and "GNU General
Public License" are included exactly as in the original, and provided
that the entire resulting derived work is distributed under the terms
of
 a permission notice identical to this one.
 
 Permission is
granted to copy and distribute translations of this manual
 into
another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
 
 
 

LaTeX2RTF

**********

   
 This file documents LaTeX2RTF , a converter that translates LaTeX
to RTF.
 
 
 
 

History & Copyright
*******************

   
 In 1994 the first Version of LaTeX2RTF  was written by Fernando
Dorner and Andreas Granzer of
 the Viena University supervised by Ralf
Schlatterbeck in a one-semester course. They
 created a simple LaTeX
parser and added most of the infrastructure for the program.
 This was
version 1.0 of LaTeX2RTF .  In 1995, work on LaTeX2RTF  was continued
in another
 one-semester course by Friedrich Polzer and Gerhard
Trisko. The result was LaTeX2RTF  version
 1.5.  Ralf Schlatterbeck
<ralf@zoo.priv.at> maintained and extended LaTeX2RTF  until
 1998.
 
In 1998 Georg Lehner <jorge_lehner@gmx.net> found the reference to
LaTeX2RTF  on the
 TeX Conversion Webpage
(http://tug.org/utilities/texconv/index.html)  of
 Wilfried Hennings
<W.Hennings@fz-juelich.de> and added some functionality and took
 over
the maintainence of the program.  The last version release by Georg is
1.8aa.
 The bulk of development post 1.8aa was done by Scott Prahl.  
Wilfried Hennings now coordinates the development of the program and
maintains the project
 on SourceForge
(http://sourceforge.net/projects/latex2rtf/) where there are also
(low volume) mailing lists for users
<latex2rtf-users@lists.sourceforge.net>
 and developers
<latex2rtf-developers@lists.sourceforge.net>.
 For subscription to
these lists:
<latex2rtf-users-request@lists.sourceforge.net?subject=subscribe>
 or
<latex2rtf-developers-request@lists.sourceforge.net?subject=subscribe>

 As of April 2002, version 1.9.13 of LaTeX2RTF  is available. 
 One
day there shall be a jump to Version 2.0, but this is not history but
future ...
 
 The contents of this manual were composed by copying
shamelessly what was
 available in the original sources and
documentation.
 

Introduction
************

   
 LaTeX2RTF  is a translator program from LaTeX  text into "rich
text format" files.  These
 files are commonly referred to as RTF
files.  RTF is a published standard format by
 Microsoft.  This
standard can be ambiguous in places and Microsoft ignores
 parts of
the standard it finds inconvenient, but RTF is widely used by many
WYSIWIG text
 editors and is supported by Microsoft Word and most text
processors.
 
 LaTeX2RTF  translates the text and as much of the
formatting information from LaTeX  to RTF.
 Be forewarned that the
typeset output is not nearly as good as what you would get 
 from
using LaTeX  directly.
 So, why bother translating? Consider,
 
  1. You use LaTeX  and hate everything beginning with MS-....
     Nevertheless, you have
 to share your documents with people who
     don't even now that there exist other things than
 MS-....
     

  2. You know somebody who frequently sends you very fine LaTeX
     documents. Unfortunately,
 you are "on the other side" and need
     to import her files, steal some part, and then
 desktop publish
     it in your fine MS-... environment.
       
        
 There are drawbacks to the conversion process. In fact,
don't expect any LaTeX  file to
 be converted as you would like, don't
expect it to be converted without errors or
 warnings, and don't be
especially surprised when it doesn't convert at all.  LaTeX2RTF  is
known to have many bugs and many missing features. Paradoxically, this
number seems to
 grow more and more with each day.  However, we can
categorically state that there are some
 special cases,  in which a
LaTeX  file will be translated to RTF satisfactorily by
 LaTeX2RTF  --
This was sort of disclaimer, ok? OK!
 
 LaTeX  is a system for
typesetting text and therefore it focuses on the logical
 structure of
a document, whilst RTF is meant to be a transport format for a family
of
 Desktop Publishing Software, dealing mostly with the design of a
text.
 
 Although the possible different commands and styles in LaTeX
are much more flexible and
 standardized than in RTF, only a small
subset of commands has been implemented to date. 
 *Note Unimplemented
Features::.
 
 Some of the capabilities of LaTeX2RTF  are restricted
in scope or buggy. *Note Known Bugs::.
 
 RTF is a moving target,
because Microsoft does not stop inventing new extensions and
 features
for it. So you cannot view newer RTF files with older word processors.

 LaTeX2RTF  eventually will generate RTF output that is unreadable
with your Program.  The syntax and
 semantics of RTF are somewhat
artistic, i.e., you can generate a syntactically correct RTF
 file
that cannot be displayed by some/most word processors.
 
 For more
details on RTF look at the RTF-Tools by Paul DuBois, and the
corresponding
 newsgroups, etc. `http://www.primate.wisc.edu/'
 

Availability
************

   
 LaTeX2RTF  is available for many Unix Platforms, for the
Macintosh, and for MS-DOS, including
 all versions of MS Windows 95.

 The MS-DOS version (1.8aa and up) will also run under all MS Windows
versions. It requires
 an i386 processor or better. The Win32 Version
requires
 Cygnus-Cygwin32 (http://sources.redhat.com/cygwin/). As the
MS-DOS version (1.8aa and
 up) will also run under all MS windows
versions, the Win32 version has been discontinued.
 
 Subsequent to
1.8aa, Scott Prahl <prahl@ece.ogi.edu> has fixed many bugs, improved
handling of tabular environments, significantly improved handling of
equations, added macro expansion, improved handling of
 cross
references, added bitmap rendering of equations,
 and added some
support for `\includegraphics' files.
 
 You find the latest version
on
 SourceForge (http://sourceforge.net/projects/latex2rtf/) and -
with some delay - on
 CTAN sites: e.g., `http://www.dante.de' or
`http://www.ctan.org'.
 
 There are a couple of people working on the
LaTeX2RTF , coordinated by
 Wilfried Hennings
<W.Hennings@fz-juelich.de>. Contact the mailing_list for the
 latest
news.
 

Installing LaTeX2RTF
********************

   
 

General
=======

   
 The documentation of the program is found in the `doc/' directory
in the
 file `latex2rtf.texi' in the GNU TeXInfo format.  For your
convenience, you
 can find HTML and PDF versions of the manual there
as well.
 

UNIX
====

   
 To install, 
  1. Edit `Makefile' for your local configuration.  In particular, pay
     attention
 to the `PREFIX' variable.  If you do not have root
     access you might wish 
 to set the makefile variable `PREFIX' to
     be your home directory. 
 
 On some machines the cc compiler
     will issue errors. 
 In this case, better use the gcc compiler
     (from GNU). 
 Edit `Makefile' and change the line `CC=cc' into
     `CC=gcc'.
 

  2. As of version 1.9.13, LaTeX2RTF  supports conversion of LaTeX
     equations to
 bitmaps using the shell script `latex2png', found
     in `scripts/'.  
 `latex2png' requires that
 both LaTeX  and
     `ImageMagick' are installed. 
 LaTeX2RTF  will translate
     documents without a working `latex2png', but some
 features will
     be missing.
 

  3. `make'
 
  If this is not your first time installation, you may
     want to preserve
   your old configuration (`*.cfg') files. Copy
     them to a safe place before
   installing.
 
 On IBM AIX, the
     IBM make utility does not support some of the commands
 used in
     Makefile. In this case use `gmake' (from GNU) instead.
 

  4. `make check'
 
 [OPTIONAL] This tests LaTeX2RTF  on a variety of
     LaTeX  files.  Expect
 a whole lot of warnings, but no outright
     errors.
 

  5. `make install'
 
 If your `mkdir' doesn't support the `-p'
     option, then create
   the necessary directories by hand and
     remove the option from the `$MKDIR' variable.
   If you have
     other problems, just copy `latex2rtf' and `latex2png' to
   a
     binary directory, and move the contents of the `cfg/' directory
     to
   the location specified by `$CFG_INSTALL'.
  

  6. `make install-info'
 
 [OPTIONAL] This installs `.info' files
     for use with the `info'
 program.
 
        
 You no longer need to define the environment variable
`RTFPATH'. This
 is only necessary if you move the directory
containing the `.cfg' files.  
 Just define `RTFPATH' to be the path
to the new location.
 
 

DOS or Windows
==============

   
 The UNIX and Mac distributions do not contain an executable for
DOS 
 or Windows. Instead, get the DOS port as file
`latex2rtf-x.xx_dos.zip'
 (where x.xx is the version number) from  
SourceForge (http://sourceforge.net/projects/latex2rtf/)
 
 The DOS
distribution contains a precompiled executable which should run 
under plain DOS and also under any MS Windows system.
 
 To install
latex2rtf, extract all files from the zip archive to `C:\l2r'
 or to
another folder (i.e. directory) of your choice,
 preserving the folder
structure (winzip: check "use folder names").

 If you extracted them to another folder (e.g. `C:\Program
Files\l2r'),
 edit the files `L2R.BAT' and `L2RSEM.BAT' and change the
pathes 
 to `LATEX2RT.EXE' and to the cfg files 
 so that they point
to the folders where you put them.
 If there is a blank in any of the
folder names
 (as in e.g. "Program Files"), then you need to enclose
both
 the file-ID and the cfg path in double quotes, e.g.

 `"C:\Program Files\l2r\latex2rt" -P "C:\Program Files\l2r\cfg" %1 %2
...'
 
 If you install LaTeX2RTF  under WinNT, Win2000 or WinXP and 
you want other users to be able to use LaTeX2RTF , you must assign the
files and folders appropriate user permissions (at least read &
execute).
 If you don't know about user permissions, put LaTeX2RTF
into
 `C:\Program Files\l2r' or what else the standard folder 
 for
installing applications is named (e.g. in the German version it 
 is
`C:\Programme\l2r'). 
 
 Make sure that the folder containing the
files 
 `L2R.BAT', `L2RSEM.BAT' and `LATEX2PNG.BAT' 
 is in your
search path, or put these files into a folder 
 which is in your
search path (e.g. `C:\Windows').

 To display the current search path, enter `path' 
 from the command
prompt (with no arguments).
 
 To add a folder - e.g. C:\l2r - to the
search path:
   * DOS, Win3.1, Win95, Win98, WinME
        * Open the file `C:\Autoexec.bat' either with Edit (DOS) or 
          with Notepad (Windows).

        * At the end of that file, add the line
          
 `PATH=%PATH%;C:\l2r' 

        * Save the file to its original location.

   * WinNT, WinXP
        * Right-click "My Computer" (German: "Arbeitsplatz"), then
          select "Properties";

        * NT: Click the "Environment" tab;
          
 XP: Click the "Extended" tab, then the "Environment
          variables" button;

        * Find the line beginning with `PATH=' and append the string
          
 `;C:\l2r'
          
 so that the complete line looks like
          
 `PATH=C:\WINDOWS;...;...;C:\l2r'

        * Click "OK"

 To start the program under Windows, open a command prompt (or
console window)
 - under DOS you are already at the command prompt -,
use `cd <folder>' to make the folder with your TeX files the
 current
folder, then enter either `L2R <filename> <options>'
 or `L2RSEM
<filename> <options>' where <filename> is the name 
 of your TeX file
without the .tex extension.

 L2R.BAT and L2RSEM.BAT only differ in the character being used
 as
parameter separator in the EQ fields, see chapter *Note Equations::.

 If you want to use the option to convert equations to bitmaps (-M
12),
 you must have TeX, ImageMagick and Ghostscript installed.
 This
works only on win32 systems (win95, win98, winNT4, win2000, winXP)
because ImageMagick is available only for win32, not for pure DOS.

 
   * Of TeX, you need a complete installation.
 

   * Of ImageMagick, get the version for Win2000. It will also work
     under win95 and win98.
 You only need convert.exe.
 

   * Of Ghostscript, you only need gswin32c.exe and gsdll32.dll.
   
 Either the folders where TeX, ImageMagick and Ghostscript are
installed
 must be in your search path, or you must edit the file
`LATEX2PNG.BAT' 
 and specify the folders where TeX, ImageMagick and
Ghostscript are installed
 in the SET commands, e.g.
 
     ...
     rem Set path to latex here (ending with \) 
     rem     if it isn't in your search path:
     SET TEXDIR=C:\texmf\miktex\bin\
     
     rem Set path to ImageMagick's convert here (ending with \) 
     rem     if it isn't in your search path:
     SET MAGICKDIR=C:\ImageMagick\
     
     rem Set path to Ghostscript's gswin32c.exe here (NOT ending with \) 
     rem     if it isn't in your search path:
     SET GSDIR=C:\gs\gs7.04\bin
   
 LaTeX2RTF  first writes a temporary .tex file to disk which
consists of only 
 the equation to be converted. It then sends the
call for latex2png.bat to
 the operating system. One user had problems
that this didn't work although
 manually calling latex2png.bat from
the command prompt worked.

 I guess the problem was caused by using 4NT.exe as command processor
instead
 of the (default) command.com, but he not (yet) confirmed
this.
 
 

Macintosh
=========

   
 If you want a MacOS X version, make sure that you have installed
the developer tools CD
 that is appropriate for your OS version, and
then follow the directions above for
 UNIX installation.
 
 There is
a classic MacOS PPC port of the 1.9k of LaTeX2RTF  and I have made a
binary
 distribution of this application.  Unfortunately, because I
(Scott Prahl) do all
 development under MacOS X, the binaries for the
Classic version often lag (far) behind the
 current UNIX version.
 
To convert a LaTeX  file, just drag the file onto the LaTeX2RTF
application icon.  The
 translation is best if there are `.aux' and
`.bbl' files in the same folder as
 the `.tex' file to be converted.
These should be generated using LaTeX  and
 `bibtex'.
 

Problems Compiling
==================

   
 The code for LaTeX2RTF  is standard ANSI C.  Some possible
pitfalls
 are
   * Not correctly defining your compiler in the Makefile.
 The
     default is to use `gcc'.  
 

   * Encountering errors because the compiler options.  During
     development
 all compiler warnings are turned on.  However,
     different compilers have
 different interpretations of `-Wall'
     and `-pedantic' and 
 so may generate errors that were not found
     in a different development
 system.  Plese report these, but a
     quick fix is to remove all compiler
 options.
 

   * Not defining `RTFPATH' (either as environment variable or by
 the
     command line parameter -P).
 

   * Not defining `HAS_NO_STRDUP' in the Makefile when your system
     lacks this facility.
   

Problems with `make check'
==========================

   
 All the files in the `test' directory are converted (with more or
less
 success) using LaTeX2RTF  and are tested before each CVS
check-in and with
 all released tarballs.  If you have successfully
compiled LaTeX2RTF  then
 problems are probably caused by
 
     

   * Not defining `RTFPATH'.
 

   * Not defining `HAS_NO_STRDUP' in the Makefile when your system
     lacks this facility.
   

Using LaTeX2RTF
***************

   
 

General Assumptions
===================

   
 LaTeX2RTF  assumes that the `.tex' file you want to convert is a
valid 
 LaTeX  document.  The chances of a successful LaTeX2RTF
conversion are slightly better than the
 proverbial snowball's if the
`.tex' file doesn't `latex' properly.  Use 
 LaTeX  to find and
correct errors before using LaTeX2RTF .
 
 To correctly convert font
names you must edit the `fonts.cfg' configuration file.
 This file is
used to specify the needed font names and how the LaTeX  default font
names
 should be converted to RTF.  *Note Font Configuration::. LaTeX
variables and user
 defined commands are not evaluated. They will be
simply ignored. To let LaTeX2RTF  know the
 names of variables you can
add them in the `ignore.cfg' file.  *Note Ignore Command::.
 
 The
environment variable RTFPATH may contain a search path for the support
files (all
 files ending in `.cfg'). If no file is found during the
search in the search-path or
 if the environment variable is not set,
the compiled-in default for the configuration-file
 directory is used.
If the files are not found at all the program aborts.
 
 In the
MS-DOS version the search path is separated by `;' in the Unix version
by `:'. For
 the paths themselves apply `\' and `/'. A separator may
appear at the beginning or ending
 of RTFPATH.
 
 Make sure that the
configuration files are in the correct directory. LaTeX2RTF  will need
at
 least `fonts.cfg', `direct.cfg', `ignore.cfg', `english.cfg'. You
may
 have to change one ore more of them to suit your needs. *Note
Configuring LaTeX2RTF::.
 
 *Note Missing options::, for actual
implementations irregularities.
 
 *Note Reporting Bugs::, for
information on how to reach the maintainer.
 

LaTeX2RTF Options
=================

   
 The LaTeX2RTF  command converts a LaTeX  file into RTF text
format. The text and
 much of the formatting information is translated
to RTF making the new file
 look similar to the original.  The command
line syntax is:
 
     latex2rtf [-options] inputfile.[tex]
   
 The `-options' may consist of one or more of the following
 
`-a auxfile'
     specify an `.aux' file (for table and figure references) that
     differs from `inputfile.aux'. If this is omitted, the name of the
     inputfile with the suffix replaced `.aux''will be taken.  You
     must
 provide both files (`.tex' and the `.aux') to be able to
     convert cross-references in a LaTeX  file.  The `.aux' is created
     by running the `inputfile.tex' through `latex'.
 

`-b bblfile'
     Unless an `bblfile' is specified with the `-b' option, LaTeX2RTF
     uses a
 `inputfile.bbl'.  The `bblfile' file is used for
     citations and is typically
 created by running `inputfile.aux'
     through `bibtex'.
 

`-d'
     The `-d' option determines the amount of debugging information to
     send to
 stderr while translating. `0' means only Errors, `1'
     Warning Messages
 (default) also.  These numbers can go as high
     as `7'.
 

`-i language'
     used to set the idiom or language used by the LaTeX  document.
     Typically, this is
 specified in a LaTeX2e  document by including
     `\usepackage[language]{babel}' where
 `language' is one of the
     languages supported by the `babel' package.   All
 languages
     listed in the babel system are supported so far as translations
     for "Chapter,"
 "References," and the like.  Specific support for
     specific options of the german style
 package are explictly
     supported. The french translated names are found in the
     `french.cfg' file in the `cfg/' directory.  *Note Language
     Configuration::.
 

`-l'
     same as `-i latin1' (Note that the default behavior is to use
     `ansinew'
 which is a superset of `latin1'). Included for
     backwards compatibility.
 

`-o outputfile'
     Unless an `outputfile' is specified with the `-o' option, the
     resulting RTF
 filename is formed by removing `.tex' from the
     `inputfile' and appending
 `.rtf'.
 

`-C codepage'
     used to specify the character set (code page) used in the LaTeX
     document. This is only
 important when non-ansi characters are
     included in the LaTeX  document. Typically this
 is done in a
     LaTeX2e  file by using `\usepackage[codepage]{inputenc}' This
     command
 is not needed if the above command is already in the
     LaTeX2e  file.  You may select any
 of the following code pages:
     ansinew, applemac, cp437, cp437de, cp850, cp852, cp865,
     decmulti, cp1250, cp1252, latin1, latin2, latin3, latin4, latin5,
     latin9, next.  The
 default behavior is to use ansinew (code page
     1252).  Cyrillic support includes
 conversion of koi8-r, koi8-u,
     cp1251, cp855, cp866, maccyr, and macukr encodings.
 

`-D dots_per_inch'
     used to specify the number of dots per inch for equations
     converted to bitmaps.  
 This value is also used when picture
     environments are converted to bitmaps as well
 as when EPS
     graphics are converted to png files.  The default value is 300
     dots per
 inch.
 

`-M#'
     where # selects the type of equation conversion.  Use
 	


    `-M1'
          	convert displayed equations to RTF

    `-M2'
          	convert inline equations to RTF

    `-M4'
          	convert displayed equations to bitmap

    `-M8'
          	convert inline equations to bitmap

    `-M16'
          	insert Word comment field that the original equation text
     These switches can be added together to get the desired
     conversion.  Handy examples are
 	


    `-M3'
          	convert both inline and displayed equations to RTF (default)

    `-M6'
          	convert inline equations to RTF and displayed equations to
          bitmaps

    `-M12'
          	convert both inline and displayed equations to bitmaps
     Bitmap conversion requires that you have installed a working
     latex2png script.
 Producing bitmaps is slow.
 

`-P /path/to/cfg'
     used to specify the directory that contains the `.cfg' files
 

`-S'
     used to specify that semicolons should be used to separate
     arguments in RTF fields
 (instead of commas).  Typically this is
     needed when the machine that opens the RTF file
 has a version of
     Windows that uses `,' for decimal points.
 

`-V'
     prints version information on standard output and exits.
 

`-W'
     includes warnings directly in the RTF file
 

`-Z#'
     add the specified number of extra `}' to the end of the RTF file.
     This
 is useful for files that are not cleanly converted by
     LaTeX2RTF .
 
 
 With no arguments other than switches starting
with a "-", 
 LaTeX2RTF  acts as a filter, i.e., it reads from `stdin'
and writes to `stdout'.
 In addition, diagnostic messages are sent to
`stderr'. If these standard
 channels are not redirected using `<' and
`>', then the
 input is read from the command line, and both output
and error
 messages are printed on the screen.
 
 If a non-switch
argument is present, LaTeX2RTF  assumes it is the name of
 the input
file. The file must have extension ".tex" but the extension
 is
optional. The output file is constructed from the input file name
 by
removing the extension ".tex" and adding ".rtf".
 

Debugging
=========

   
 With the `-d' option you can specify how much processing
information
 LaTeX2RTF  reports.
 If there is a logfile specified the
output goes to this file. Nonetheless
 Warnings and Errors are logged
to stderr always.
 
 Possible values of `-d' are
  0. only errors.

  1. Translation Warnings (default).

  2. shows preparsing of sections

  3. Reasonably high level debugging messages

  4. Show all function calls

  5. Show all each character as it is processed

  6. Show processing of characters as they are output as well
        

Features
********

   
 In this chapter you find what styles is LaTeX2RTF  supposed to
translate
 correctly to RTF.
 
 

LaTeX2e
=======

   
 LaTeX2RTF  understands most of the commands introduced with
LaTeX2e .  It supports both
 the old 2.09 version of
`\documentstyle[options]{format#}' and the newer
`\documentclass[options]{format}'.  
 

Input Encoding
==============

   
 It is not necesary to specify the `-C' option if you use
`\usepackage{isolatin1}'
 or `\documentstyle[isolatin1]{...}'.
LaTeX2RTF  automagically detects these
 packages/style options and
switches to processing of ISO-Latin1 codes.  The following
 encodings
are supported: ansinew, applemac, cp437, cp437de, cp850, cp852, cp865,
decmulti, cp1250, cp1252, latin1, latin2, latin3, latin4, latin5,
latin9, next,
 koi8-r, koi8-u, cp1251, cp855, cp866, maccyr, and
macukr.  The encoding used in
 RTF files is cp1252.  If cyrillic fonts
are present, then these are represented
 in the RTF file using cp1251
(Windows Cyrillic).
 
 

Language Support
================

   
 The following languages from the Babel package are supported:
afrikaans,
 german, nynorsk, spanish, bahasa, dutch, icelandic,
polish, swedish,
 basque, english, portuges, turkish, brazil,
esperanto, irish, romanian,
 usorbian, breton, estonian, italian,
samin, welsh, catalan, finnish,
 latin, scottish, croatian, lsorbian,
serbian, czech, french, magyar,
 slovak, danish, galician, norsk,
slovene,
 
 The only thing that these files do is to translate
various words usually
 emitted by LaTeX  during processing.  For
example, this ensures that the
 LaTeX2RTF  will provide the correct
translation of the word "Chapter" in
 the converted document.
 
 You
can select any of the above languages using the `-l' option.  This
 is
not needed if your LaTeX  file contains
`\usepackage[language]{babel}'.
 
 Encountering the `german' package
or documentstyle option (by H. Partl of the
 Viena University) makes
LaTeX2RTF  behave like that: German Quotes, German
 Umlauts by `"a',
etc....  This support is programmed directly 
 into LaTeX2RTF  and
supporting similar features for other languages will require 
patching the source code.
 
 *Note Language Configuration::, for
details on how to write a `language.cfg' file
 for your language by
yourself.
 

Cross References
================

   
 Cross references include everything that you might expect and
then some:
 bibliographic citations, equation references, table
references, figure 
 references, and section references.  Section,
equation, table and figure references
 are implemented by placing RTF
bookmarks around the equation number (or table
 number or figure
number).  
 
 Page references work but are implemented as "warm"
cross-references.  This
 means that Word does not automatically update
the page references when the file
 is opened.  To update the page
references you must select the entire document
 (in Word) and press
`F9'.
 
 Bibliographic references currently require that a valid
`.aux' file be
 present.  This is where LaTeX2RTF  obtains the
reference numbers.  It would be
 nice if LaTeX2RTF  just automatically
numbered the references when there was
 no `.aux' file, but LaTeX2RTF
does not do this yet.
  
 Footnotes are implemented and appear at the
bottom of each page.  
 
 Indexing is reasonable well supported.  The
simple mark-up of `makeindex'
     \index{topic!subtopic@\textit{subtopic}}
   is supported.  The rest of the fancy indexing stuff is not
implemented.
 The index is created at the location of the
`\printindex' command.
 When a file with an index is first opened in
Word, you must select the 
 entire file and update the page references
and fields by pressing `F9'.
 
 Currently, there is no support for
`\labels' of `\item's in enumerate environments.
 
 The conversion of
cross-references is not perfect because of the different
 mechanisms
in the LaTeX  and Word worlds.  In particular, if there are 
 multiple
`\label' in a figure, table, or section environment then only the
first
 gets processed.  It is also possible to confuse the LaTeX2RTF
in eqnarray environments.
 

Equations
=========

   
 There are four separate levels of equation translation based on
the -M switch, 
 *Note LaTeX2RTF Options::.
 Each equation is now
converted either to an EQ field or to a bitmap. 
 
 This is an
interim solution (for some definition of "interim"). 
 Ideally the
equations would become OLE equation objects in the
 RTF file, but this
needs to be implemented.
 
 Some functions in the EQ fields have two
or more parameters with a separator 
 between each two. Unfortunately,
the interpretation of these separators depends 
 on the country
specific settings in the MS Windows system in which the rtf file 
 is
opened. E.g. in English versions of MS Windows, the default parameter
separator 
 is the comma, in German versions the default is the
semicolon. If the parameter 
 in the RTF file does not match the
Windows setting, some EQ fields are not 
 interpreted correctly. You
can check and set the separator in [Windows control panel 
 - country
settings - numbers - list separator]. By default, latex2rtf uses
 the
comma as separator. If latex2rtf is called with the command line
parameter -S ,
 the semicolon is inserted as parameter delimiter. 
 

 

Tables
======

   
 The table code is currently barely working.  It needs to be
rewritten.
 

Graphics
========

   
 There is now rudimentary support for `\includegraphics'.  Three
file types
 will be inserted into the RTF file without needing
conversion: .pict, .jpeg, and
 .png files.  EPS files are converted to
PNG using `convert' from the ImageMagick 
 package.  
 

Pagestyles
==========

   
 If there is no `\pagestyle' command, the RTF output is generated
as with plain
 pagestyle, i.e. each page get's its page number
centered at the bottom.
 
 You must turn this off with the
\pagestyle{empty} command in the LaTeX  file if
 you don't want
pagenumbers.
 The headings and myheadings styles are silently ignored
by now.
 The twosided option to the \documentstyle or \documentclass
produces the
 corresponding RTF tokens.
 Note that these features
require RTF Version 1.4.
 

Hyperlatex
==========

   
 Hyperlatex support is largely broken at the moment, but continues
to improve.
 
 Otfried Schwarzkopf has created the "Hyperlatex Markup
Language" which is a
 "little package that allows you to use LaTeX  to
prepare documents in HTML."
 It brings an Emacs lisp program with it
to convert the Hyperlatex file to HTML.
 Hyperlatex can be obtained
from the CTAN-sites, *Note Availability::.
 There are two convenient
commands that avoid typing: \link and \xlink that
 generate an
"internal" label which then is used in the following \Ref and
\Pageref commands.
 
 LaTeX  makes it possible to write
`\link{anchor}[ltx]{label}', which typesets:
 `anchor ltx'. LaTeX2RTF
does NOT support this aproach since the optional
 parameter is thrown
away right now, *Note LaTeX2RTF under Development::.
 
 Note that you
have to update your `.cfg' files if you are upgrading, since
 there
are a lot of HTML oriented commands in Hyperlatex that we simply can
`ignore'.
 

Configuring LaTeX2RTF
*********************

   
 

Input processing
================

   
 On processing input LaTeX2RTF  first converts the LaTeX  special
characters. If
 it encounters one of the standard commands it is
converted internally. If a
 command is not known to LaTeX2RTF  it is
first looked up in
 `direct.cfg' and the RTF code specified there is
output. If not found there it
 is looked up in the section
`ignore.cfg'.  This file includes a lot of LaTeX 
 commands that do
not affect the output (cross reference information
 and the like), or
that we are not able or willing to convert to RTF.
 
 You can use
`ignore.cfg' if you get tired of seeing 
     WARNING: command: `foo' not found - ignored
    and you don't need `foo' in your RTF document.  It would
 be nice
to send your additions to the LaTeX2RTF  mailing list for inclusion
in later distributions.
 
 LaTeX2RTF  accepts Unix, MS-DOS, and
Macintosh line ending codes (\n, \r\n
 and \r).  The files it creates
are the line ending for the platform on
 which LaTeX2RTF  was
compiled.
 
 The LaTeX  file may have been created with a wide
variety of character
 sets.  If the LaTeX  lacks the
`\package[codepage]{inputenc}'
 definition, then you may need to use
the command line switch to manually
 select the proper code page.
*Note Input Encoding::.
 

Output formatting
=================


 On writing output, LaTeX2RTF  generates `\n' as line ending code.
Your RTF Reader should accept this on any platform. If you ftp your RTF
file
 from or to MS-DOS platforms the line ending code can be
converted to `\r\n'. As
 this should also be legal to any RTF Reader
the resulting RTF rendering should
 not be affected.
 
 LaTeX2RTF
does not offer a whole lot of flexibility in how files are translated,
but it does offer some.  This flexibility resides in four files
`direct.cfg',
 `ignore.cfg', `fonts.cfg', and `language.cfg'.  These
filese
 are documented in the next four sections.
 

Direct Conversion
=================

   
 The file `direct.cfg' is used for converting LaTeX  commands by
simple text
 replacement. The format consists of lines with a LaTeX
command with backslash
 followed by comma. The rest of the line until
a `.' character will be written
 to the RTF file when the command is
found in the LaTeX  file. Lines
 starting with a `#' character are
ignored. After the `.' everything is ignored
 to end of line. To
select a specific font use `*fontname*', where 
 `fontname' be defined
in `fonts.cfg'.
 To write the `*' character use `**'. 
     \alpha,{\f*Symbol* a}. #alpha in the Symbol Font
     \copyright,\'a9.
   

Ignore Command
==============

   
 The file `ignore.cfg' is used for defining how to ignore specific
commands. This
 file is used for recognition of LaTeX  variables, user
defined variables, and
 some simple commands. All variables are
ignored but the converter must know the
 names to correctly ignore
assignments to variables. Lines in this file consist
 of a variable
name with backslash, followed by comma and the type of the
 variable
followed by `.'. Possible types are
 
`NUMBER'
     simple numeric value

`MEASURE'
     numeric value with following unit of measure

`OTHER'
     ignores anything to the first character after `=' and from there
     to next
 space. e.g., `\setbox\bak=\hbox'

`COMMAND'
     ignores anything to next `\' and from there to the occurence of
     anything
 but a letter e.g., `\newbox\bak'

`SINGLE'
     ignore single command e.g., `\noindent'

`PARAMETER'
     ignores a command with one parameter e.g., `\foo{bar}'

`PACKAGE'
     does not produce a Warning message if PACKAGE is encountered,
     e.g.,
 `PACKAGE,kleenex.'

`ENVCMD'
     proceses contents of unknown environment as if it were plain LaTeX
     
 eg. `ENVCMD,environ.' Therefore `\begin{environ} text
     \end{environ}'' as `text'.

`ENVIRONMENT'
     ignores contents of that environment, e.g., with
     `ENVIRONMENT,ifhtml.'
 `\begin{ifhtml} text \end{ifhtml}' ignores
     `text'.
 
 The types are in upper case exactly as above. Do not
use spaces. Lines starting
 with a `#' character are ignored. After
the `.' everything is ignored to end of
 line. Example:
     \pagelength,MEASURE.
   

Font Configuration
==================

   
 The file `fonts.cfg' contains the font name mapping.  For
example, this
 file determines what font is used to represent `\rm'
characters in the RTF file.  
 
 A line consists of a font name in
LaTeX  followed by comma and a font
 name in RTF. The end is marked by
a `.'. No spaces are allowed. The
 LaTeX  font will be converted to
the RTF font when it is found
 in the LaTeX  file. If multiple
translations for the same LaTeX  font are
 specified, only the first
is used. All fonts in a LaTeX  file that are
 not in this file will be
mapped to the default font. All RTF fonts
 listed in this file will be
in every RTF file header whether used or
 not.  Lines starting with a
`#' character are ignored. After the
 `.' everything is ignored to end
of line. 
 
 To add a RTF font not
 used as substitute for a LaTeX
font -- for example a Symbol font used
 in `direct.cfg' -- use a dummy
LaTeX  name like in the following
     Dummy3,MathematicalSymbols.
   
 Make sure you use the correct font name. Take care of spaces in
font names. The
 default fonts are named Roman `\rm', Slanted `\sl',
Sans Serif
 `\sf', Typewriter `\tt', or Calligraphic `\cal'.
 

Language Configuration
======================

   
 The file(s) `language.cfg' control the translation of LaTeX 's
"hardcoded"
 sectioning names.
 The standard LaTeX  styles have some
fixed Title names like `Part', `Reference'
 or `Bibliography' that
appeared in English or German in the output with the
 original
versions of LaTeX2RTF . 
 
 It is unlikely that you will need to
create a new `language.cfg' file.
 However, just look at one of the
existing files and follow the pattern.
 The format is really simple.

 

Error Messages and Logging
**************************

   
 As stated in the Debugging section, LaTeX2RTF  provides a means
to control 
 the amount of debugging information through the `-d#'
switch.  
 By using a debugging level of 4, you can get a pretty good
idea of what
 LaTeX  command caused the problem and what line that
command might be
 found on.  
 
`Fatal error messages'
     indicate a bug in the source code. PLEASE report them, if they do
     not
 apear in the documentation. *Note Reporting Bugs::.
 

`Error messages'
     always abort the program and are caused by conditions that
     prevent
 further conversion of the input file.  Typically this is
     cause by
 LaTeX2RTF  getting hopelessly confused by the number of
     braces in the
 LaTeX  file.
 

`Warning messages'
     inform you, that there is some conversion loss from LaTeX  to RTF,
     or that
 the output file has some restrictions on some RTF
     Readers. Most of these 
 warnings can be supressed by add the
     offending command to the `ignore.cfg'
 file.
 
 Error and
Warning messages should follow the GNU Coding standards, i.e. they
have the format
     inputfile':line: Error|Warning: message
   
 You can also control the level of debugging output by inserting
`\verbositylevel{#}'
 in the LaTeX  file.  This is very handy if you
have a large LaTeX  file
 that is failing in only a small section.
For example,
     problem free latex file ....
     \verbositylevel{5}
     problematic code
     \verbositylevel{0}
    will cause a huge amount of debugging information to be emitted
for the problematic code.
 
 Error reporting and logging still has
many inconsistencies, but it
 gets better with each release.
 Don't
try to make any sense in debugging levels above 4, these are for my
own delight only and can change significantly between versions.
 
The `inputfile' may be incorrectly identified if it is incorporated
through `\input' or `\include'.  The line may be also be wrong
 at
times.  *Note Known Bugs::.
 

LaTeX2RTF under Development
***************************


 

Unimplemented Features
======================

   
   * LaTeX2RTF  ignores some of the optional parameters of
     `\documentstyle' 

   * Need to finish code page support.  Some characters that need to
     be
 	  constructed using RTF `\field' commands are not
     implemented.

   * Add the code to produce the corresponding chapter, section,
     and page numbering with headings and myheadings pagestyles.
     Implement
       `\markboth' and `\markright'.

   * To support `\tableofcontents' there would be two approaches:
     Transfer
       sectioning information, title text and then
     produce page numbers by the rtf-
       reader. Scan and label
     all of the sectioning commands while reading and
       then
     construct the sectioning information using these labels. Needs
     two
       passes on LaTeX  input.

   * Include the GNU gettext package to internationalize LaTeX2RTF 's
     Messages.
   

Missing options
===============

   
 Missing or buggy command line options.
 
`-V'
     The version information output is not compatible with the GNU
     Coding
 Standards.
 

`-d'
     Information logging and Error reporting is not implemented
     consistently.
 Need to test and track problems with the
     linenumber and with the file name.
 

`-?'
     There should be an option to intersperse RTF-Output with the LaTeX
     input
 that produced it to aid debugging.
 

`-q'
     There should be a `-q' (quiet) option, to suppress Warning
     Messages. By
 now this can be achieved by the `-d0' option.
 

`-rmajor.minor'
     There should be an option that restrict the generation of RTF code
     with
 version greater than major,minor. Actually this is done at
     compile time.
 There are some Warning messages if "newer" RTF
     Code is generated, but it
 is not consistent at all.
 

`--long_names'
     It would be useful to implement the GNU long option names, e.g.:
     `-debug',
 `-output_file', `-quiet', etc.  This could be done by
     switching to the GNU
 getopt package.
 
 

Known Bugs
==========

   
  1. The first parameter of a \link{anchor}[ltx]{label} is converted to
     the
       rtf-output. Label is stored to hyperref for later use,
     the optional
       parameter is ignored. [ltx] should be
     processed as Otfried recommends it,
       to use for exclusive
     LaTeX  output.e.g: \link{readhere}[~\Ref]{explaining:
     chapter}. Since {explaining:chapter} is yet read by LaTeX  and
     hyperlatex
       when [...] is evaluated it produces the correct
     reference. LaTeX2RTF  is
       only strolling from left to right
     through the text and can't remember
       what she will see in
     the future.

  2. The diagnostics routine does not output the correct (actual)
      inputfilename. (`.aux', `.bbl', `\input').
        

Reporting Bugs
==============

   
 Report bugs to to the bug tracking system at SourceForge
(http://sourceforge.net/projects/latex2rtf/). 
 Only report bugs for
the latest version of LaTeX2RTF  that is available.  
  Please provide
the following information and observe the following
 guidelines when
reporting a bug in the program:
  1. State the version of LaTeX2RTF  that you are using.  You can get
     the version by
 specifying the `-V' option to LaTeX2RTF . 
 

  2. Specify the your operating system and version. Be sure to check
     the file `Makefile'
 for settings that may be specific to your
     machine, especially for some versions of SunOS
 there may be
     settings which are needed to compile successfully. Do this before
     submitting
 a bug report.
 

  3. If the program produces wrong output or does not work for you,
     include a short
 LaTeX  file along with a description of the
     problem.  Isolating the bug into a small
 LaTeX  file does two
     things.  First, it provides a file that can be used to test
     future
 versions of LaTeX2RTF  and second, it certainly improves
     the chances that the bug will get
 some attention.  Do not send
     me large LaTeX  or RTF files, I simply do not have the time
 to
     wade through large files to search for a bug!
 

  4. Be patient. I am maintaining the program in my free time. I did
     not
 write most of the code. Often I do not have the time to
     answer to your
 question. I will, however, try to fix reported
     bugs in upcoming releases.
        

Todo List
=========

   
 Scott's ToDo list
   * Use lex/yacc to implement getSection

   * Rewrite table code

   * Add support for pagestyle

   * Improve graphic/graphicx support

   * Better support for ignoring commands
   
 Georg's todo list
   * Make this Manual more consistent, the ToDo and Known Bug List
     shorter and
       the Features List longer.

   * Harmonize all of the error and warning messages.

   * Put warnings everywhere applicable about producing RTF 1.4
     tokens.

   * Provide an Error and Warning recovery guide to the user.

   * Add a chapter with lists of all LaTeX  commands that convert, and
     that do
       not convert to RTF, including their status (for
     future releases, never,
       partially functional, ...).
   

Index for LaTeX2RTF
*******************

   

Copyright issues:
          See ``History & Copyright''.
History of the programm:
          See ``History & Copyright''.
   
 
...Table of Contents...

 

