
Gnuplot PGF/TikZ terminal
=========================

The PGF/TikZ terminal mainly consists of a generic Lua terminal to
wrap the gnuplot terminal C functions. This allows writing gnuplot
terminals in Lua instead of C. The first (and currently only) implemented
`backend' is the PGF/TikZ terminal for the use with TeX/LaTeX.

The actual terminal functionality is a provided by a separate Lua script
`gnuplot-tikz.lua'. The LaTeX style file is usually derived from PGF/TikZ terminal
script to keep things consistent.



Why all that hassle?
====================

There are are couple of terminals allready usable for LaTeX so why
writing another one?

Here is a brief list of reasons:

 1. I like PGF/TikZ and there is no such terminal so far.
 2. I also like lerning Lua and the use of Lua makes this terminal
    very versatile, e.g. there is no recompilation necessary if
    you want to change/add any terminal features and you also gain
    all the benefits of using a scripting language in this
    place -- whatever that means to you ;-)
 3. Most advantages are directly related to PGF/TikZ:
    a. rescaling the plot does not automatically change the linewidths
       nor the size of points (aka plot marks), fonts, arrow tips or
       fill patterns. The aspect ratio of these elements will also
       remain unchanged on unproportional scalings.
    b. you can directly produce documents of any output format
       that is supported by PGF/TikZ.
    c. changing the appearance of the plots is an easy task even
       after the generation of the PGF/TikZ code. This can be done
       locally or globally by changing certain TikZ-styles or
       dimensions.
    d. it is also easy to put the keys (aka legend) into the normal text
       area (e.g. the plot caption), because the line and plotmark styles
       are available.
    e. overlaying of the plot with e.g. additional nodes, arrows etc. is 
       possible through the use the of tikz coordinates of the actual
       plotting area.

For more reasons please have a look at the PGF/TikZ manual ;-)



Generating style and help file
==============================

To generate the style files and wrapper for the various TeX flavors enter

  lua gnuplot-tikz.lua style

on the command line. The files generated should be

  t-gnuplot-lua-tikz.tex        (Context wrapper)
  gnuplot-lua-tikz.tex          (plain TeX wrapper)
  gnuplot-lua-tikz.sty          (LaTeX wrapper)
  gnuplot-lua-tikz-common.tex   (common definitions)

and can be copied to the appropriate places.

  lua gnuplot-tikz.lua help

prints the terminal help on stdout and

  lua gnuplot-tikz.lua termhelp > gnuplot-tikz.help

generates the version to be included in gnuplot help system.



Usage
=====

The usage is quite similar to the other terminals with the difference that
most terminal options are processed by the external Lua script. To see the
list of additional script options just type
  gnuplot> set term lua tikz help
or
  # lua gnuplot-tikz.lua
on the command line.


A minimalist gnuplot session (or script) may look like this:
  
> set term lua tikz     # activate the Lua terminal and load "gnuplot.lua"
> set out 'test.tex'    # write output to file 'test.tex'
> plot x*x              # plot a nice parabola

The generated file `test.tex' can be used by simply adding the line

 \input{test.tex}

to your LaTeX document and by adding

 \usepackage{gnuplot-lua-tikz}

to the preamble.





Any comments, suggestions and bug reports are most welcome and can go
to <peter(at)affenbande.org> or the Sourceforge bug and patch trackers.

Have fun!

Peter Hedwig <peter@affenbande.org>
