*** The epslatex terminal driver for gnuplot ***

* Why a new terminal driver for LaTeX?

I use Gnuplot mostly to create figures for inclusion into LaTeX
documents. One of the features i like most is that all the text can by 
typeset be LaTeX (eepic, emtex, pslatex, pstricks terminals). To my
opinion each of the existing LaTeX terminal drivers has some
disadvantages. And all these drivers share the drawback that the
resulting LaTeX file cant be processed by pdflatex. So I started to
write my own terminal driver. 

* How does it work?

The idea is about the same as the pslatex and pstricks
terminal. Graphics (Lines, Dots, ...) is drawn using Postscript
commands, all text will be typeset by LaTeX. The epslatex driver
produces two files: one (a EPS file) containing all the Postscript
stuff, another (a LaTeX file) that contains all the text and includes
(via \includegraphics} the EPS file. This LaTeX file is made for
inclusion into a LaTeX document via \input{latexfile}.
To display/print the resulting document you need a dvi driver that
supports inclusion of postscript file, as xdvi, yap and dvips do.

For processing the LaTeX document by pdflatex you only have to convert
the eps files to pdf, e.g. with epstopdf (free, requires ghostscript)
or Adobe Distiller. pdflatex then includes the pdf files instead of
the eps files. So (if everything is properly configured, as in teTeX)
the same document can be processed by latex and pdflatex yielding the
same result.

* Other features

I tried to include all the features from the LaTeX drivers i liked
best. Some of them are
- nice arrow heads (from pstricks)
- dotted/dashed lines start and stop with a dot/dash (from
  pstricks). That looks nice especially in the legend.
- Shape of the dots are about the same as in pstricks.
- color
- set size and multiplot work
- resizing of the resulting graph can rather easily be done by editing
  the LaTeX part.
- better (?) positioning of text

* Caveats

- To get the LaTeX part you have to give an output file name by set
  output "file.eps". This creates file.eps and file.tex
- Only one plot per file.
- You have to add \usepackage{graphicx} or \usepackage{graphics} to
  your LaTeX document.


* How to use it?

From the online help:

Two options may be set in the `epslatex` driver.

Syntax:
       set terminal epslatex {default}
                             {color | monochrome} {solid | dashed}
                             {"<fontname>"} {<fontsize>}

`default` mode sets all options to their defaults: `monochrome`,
`dashed`, \"default\" and 11pt. Default size of a plot is 5 inches
wide and 3 inches high.

`solid` draws all plots with solid lines, overriding any dashed
patterns; `\"<fontname>\"` is the name of font; and `<fontsize>` is
the size of the font in PostScript points. Font selection isn't
supported yet.  Font size selection is supported only for the
calculation of proper spacing.  The actual LaTeX font at the point of
inclusion is taken, so use LaTeX commands for changing fonts. If you
use e.g. 12pt as font size for your LaTeX documents, use 
   set terminal epslatex "default" 12
.
All drivers for LaTeX offer a special way of controlling text
positioning: If any text string begins with '{', you also need to
include a '}' at the end of the text, and the whole text will be
centered both horizontally and vertically by LaTeX. --- If the text
string begins with '[', you need to continue it with: a position
specification (up to two out of t,b,l,r), ']{', the text itself, and
finally, '}'. The text itself may be anything LaTeX can typeset as an
LR-box. \rule{}{}'s may help for best positioning.  See also the
documenation of the pslatex terminal driver.  To create multiline
labels, use \shortstack, example
   set ylabel '[r]{\shortstack{first line \\ second line}}'

The driver produces two different files, one for the LaTeX part and
one for the eps part of the figure.  The name of the LaTeX file is
derived from the name of the eps file given on the `set output`
command; it is determined by replacing the trailing `.eps` (actually
just the final extent in the file name---and the option will be turned
off if there is no extent) with `.tex` in the output file name.
Remember to close the file before leaving `gnuplot`.  There is no
LaTeX output if no output file is given!  In your LaTeX documents use
'\input{filename}' for inclusion of the figure.  And dont forget to
add \usepackage{graphics} or \usepackage{graphicx} to the preamble.

Via 'epstopdf' (contained e.g. in the teTeX package, requires
ghostscript) pdf files can made out of the eps files. If the graphics
package is properly configured, the LaTeX files can also be processed
by pdflatex without changes, and the pdf files are included instead of
the eps files.


* Installation

I started from gnuplot 3.7.0.5. I admit, I didnt try it with
3.8. Taking a quick glance i see no reason why it shouldnt work.

Add the files epslatex.trm and prolog.c to the term directory and add
#include "epslatex.trm" to src/term.h. Recompile Gnuplot. I didnt
figure out how to change the Makefiles, so I always used

touch src/term.c
make

to recompile Gnuplot if I made changes to epslatex.trm or prolog.c.

* Example

The files test.eps and test.tex are the result of the gnuplot test
command. How to include the result into a LaTeX-document is
demonstrated in main.tex with the result shown in main.ps.

* Credits

Big parts of the epslatex terminal driver are taken from the pslatex
and the pstricks terminal driver. Some postscript code is taken from
the pstricks package. 



* Suggestions, Bugs, Ideas...

Please send them to me, Gregor.Thalhammer@uibk.ac.at


Gregor Thalhammer

Gregor.Thalhammer@uibk.ac.at
