Directory systems/win32/oletex

				OLETeX

1. What is OLETeX?

The primary goal of this project is development of an OLE-LaTeX interface. 
The program is aimed to allow  LaTeX users easily embed pictures and other 
objects produced by OLE-aware programs into their LaTeX documents keeping 
it platform-independent.  

OLETeX is hosted at www.sourceforge.net/projects/oletex

OLETeX uses Windows PostScript printing features to convert ANY OLE object 
(e.g. Visio picture, Excel's plot,:) into an Encapsulated Postscript (EPS) 
file which can be easily processed by LaTeX.  

OLE is a MS-Windows feature allowing one to embed objects (figures, plots, 
controls:) produced by one program into documents handled by another one. 

OLETeX is distributed under the terms of GNU General Public license.

Currently OLETeX is in BETA stage, so do not expect it to be bug-free.

2. How do I use OLETeX?


OLETeX should be used as follows:

- Create a container document (this is a file with .otx extension) using 
OTEditor. This will hold all your OLE objects  
- Use Edit a Insert object to create a new OLE object or Edit a Paste/Paste 
special  to paste an existing one. Assign meaningful identifiers to your 
objects.  
- Save the container. 
- Now you can either generate .EPS files manually by clicking appropriate 
buttons/menu items or use OT2TeX utility.  
 
If you would like to automate OLE -LaTeX interaction, you should proceed 
as follows: 

- Add 

\usepackage{graphicx}
\usepackage{oletex} 

  to the preamble of your document. oletex.sty is a style file provided 
with the OLETeX distribution.   

- By default OLETeX will look for OLE objects in the container (.otx)  file 
having the same name as your main .tex document (i.e. it will look  for 
mythesis.otx while processing mythesis.tex). If you would like to use some 
other containers you should register them:  

\oleaddfile{file1.otx}
\oleaddfile{file2.otx}

- Make references to your OLE pictures: 

\begin{figure}
\includeolepicture[angle=90]{demo}
\caption{Word-produced picture}\label{theDemo}
\end{figure}

This makes a floating figure referencing to an object with identifier 
"demo" rotated by 90 degrees with appropriate caption and label. Note, 
that you can use any graphics or graphicx options here - they are passed 
unchanged to the underlying \includegraphics command 

- Compile your document: 
>latex mydocument.tex

This will cause LaTeX to parse your file and, in particular, execute 
\includeolepicture commands. This command looks for EPS files named 
identifier.eps (demo.eps for the above example) in the current directory. 
If it finds one it executes \includegraphics for it. Otherwise, an 
appropriate warning is issued. In both cases it writes a record into a 
special mydocument.otl file. After latex.exe finishes its job this file 
contains all information about containers you have registered and OLE 
objects referenced in the document. This is a plain text file, so you can 
read and edit it in case of problems. 

- Resolve references to OLE objects. Execute 
>ot2tex mydocument.otl 

  This will cause .otl file to be parsed and all containers referenced in 
it to be loaded. For each referenced identifier OT2TeX will  try to find 
an OLE object having the same name and to generate EPS file  from it. 

- Perform final compilation of your document. Since this may require 
multiple passes, texify utility coming with MiKTeX (www.miktex.org) may be 
useful here:  

>texify mydocument.tex

If everything is OK you will get a DVI file with your pictures. Note, 
however, that you WILL NOT be able to double-click on it in DVI viewer to 
change the figure. Use OTEditor for it.  
 

NOTE 1. You HAVE to rerun OT2TeX if and only if:
�     You have referenced some new objects
�     You have changed some of OLE objects in OTEditor.
Otherwise, you can compile your documents in usual manner.

 

3. How do I install OLETeX?

-  OLETeX relies on Windows PostScript printing features. On Windows 9x/NT 
4.0 it is strongly recommended to install free Adobe PS drivers (see 
ftp://ftp.adobe.com/pub/adobe/printerdrivers/win/4.x/drivers/ for Win9x 
and  ftp://ftp.adobe.com/pub/adobe/printerdrivers/win/5.x/drivers/  for 
WinNT). On Win2K+ these drivers are preinstalled with the system.   

- Download the distribution at http://oletex.sourceforge.net/oletex.exe. 
This is a self-extracting archive  
- Unfortunately, currently there is no installer. Run the downloaded EXE, 
specify a temporary directory to store files. This will extract both 
binaries and sources. If you are not going to use OLETeX sources you can 
safely delete them.  
- Read carefully the .HLP file and follow CAREFULLY installation 
instructions there. If you fail to setup EPS printer properly, you will 
not be able to use OLETeX.  
- Test your installation as described in the help file.  
- Enjoy it! 
- Take a time to write me at trifonov@users.sourceforge.net about your 
OLETeX experience.  
 

4. Frequently Asked Questions

1. Q: I am unable to generate EPS files neither by OTEditor nor OT2TeX 
   A: It seems that your EPS printer installation is broken. Run OTEditor, 
open OptionsaSettings dialog. Press Change button near the EPS-configured 
printer. Select OLETeX Color PS L2 printer from the listbox. If you do not 
see it, you should reinstall it (see help file for details). When you have 
it selected, press OK button and choose OptionsaSave settings. Go to 
Printers folder and check printing properties of OLETeX Color PS L2 
printer. Check if its Postscript Output Option is set to Encapsulated 
Postscript and Language Level is set to 2. Check if its port is set to 
FILE. 

2. Q: I have sent my .tex document to a friend (colleague, publisher, etc) 
and he is unable to compile it  
   A: Currently, OLETeX is not a standard LaTeX tool, so most likely your 
colleague does not have it installed. You may solve problem in the 
following ways: 

    - Make him to install OLETeX :-) 
    - Generate EPS files for all your OLE objects, remove 
\usepackage{oletex} from the preamble and replace  \includeolepicture with 
\includegraphics. Send him both .tex and .eps files.  
    - Send him a compiled PostScript file. 
3. Q: Why is it so hard to compile my .tex file with OLETeX? 
   A: By default, TeX does not allow external program execution for 
security reasons, so oletex.sty cannot invoke the OT2TeX postprocessor 
automatically. Probably, when OLETeX becomes a standard LaTeX tool, I will 
try to integrate it with texify or something like it. At this time you can 
write batch file: 

4. Q: Who and why has developed this stuff? 
   A: OLETeX has been created by Peter Trifonov 
(trifonov@users.sourceforge.net). I was writing a report in LaTeX and had 
to embed some Word pictures into it. I have not found any satisfactory 
solution for this problem, so I started programming OLETeX. 

 
5. How to contact me?

If you have installed OLETeX, please write me to 
trifonov@users.sourceforge.net  about your experience. You can discuss 
OLETeX at oletex-general@lists.sourceforge.net.