Notes about using tikz2pdf

tikz2pdf-notes.txt

Including TikZ Pictures
=======================

In the following, I describe how I include TikZ pictures in my LaTeX
documents.  I decided to put every figure into a separate file, which
I name e.g. "foo.tikz".  The advantages of this approach are:

- One can compile the .tikz file on its own, i.e. editing and fiddling
  around with it until the figure is "done", without compiling the whole
  main document. (For this, I use tikz2pdf_, as described below.)

- Every figure is managed in a separate file that can be put into
  CVS/SVN/.. and gets its own versioning history and backups.

- Reusing figures from one document within another is a matter of
  including the external file in multiple .tex documents.

- Externalization of graphics is simplified.

Actually, I do not only use ``\input`` to read the external files, but
I am using the following code in the LaTeX document preamble:

.. code-block:: latex

  \newif\iffinal % introduce a switch for draft vs. final document
  %\finaltrue % use this to compile the final document

  % [more preamble that in my case also uses \iffinal for other stuff]

  \usepackage{tikz}
  \pgfrealjobname{thesis} % <-- NOTE: this needs to be the real document's basename
                          %     (else you'll only get an empty output file)

  \iffinal
    \newcommand{\inputTikZ}[1]{%
      \input{#1.tikz}%
    }
  \else
    \newcommand{\inputTikZ}[1]{%
      \beginpgfgraphicnamed{#1-external}%
      \input{#1.tikz}%
      \endpgfgraphicnamed%
    }
  \fi

Then, within the document I can just use the newly defined command to
include the figure:

.. code-block:: latex

  \begin{figure}
  \begin{centering}
  % like \input{...}, but adds caching via PGF's externalization feature:
  \inputTikZ{Figures/house-example/house}
  \end{centering}
  \caption{\label{fig:house-example}An example drawing showing a house.}
  \end{figure}

This means that I can use ``pdflatex --jobname foo-external
thesis.tex`` (or ``Figures/house-example/house-external`` in the above
example) to compile the included picture ``foo.tikz`` into
``foo-external.pdf``, which is then automatically included for a
faster compilation of ``thesis.tex``.  (See section "Externalizing
Graphics" in the PGF/TikZ manual, i.e. section 60 at the time of
writing.)

Here is an example ``foo.tikz`` file:

.. code-block:: latex
   :source-file: tikz/foo.tikz

As you can see, I added the ``tikzpicture`` environment within the
.tikz file; one disadvantage of this approach is that one cannot
easily scale the picture if it should have different sizes in
different documents.

tikz2pdf
--------

{software/scripts/tikz2pdf}

For a quick preview of changes I make to my figures, I wrote this
little python script, which creates a temporary .tex file that
includes the .tikz file and compiles that to create a .pdf file.
Even better, it stays running and watches the .tikz file for changes;
as soon as the file is changed in an editor, the .pdf is recreated.
This is similar to KTikZ__, a GUI program that comprises both an
editor (with completion AFAIK) and preview pane.

Its main features currently are:

- Automatic recompilation of the .tizk file on changes.  If you don't
  want that, use the ``--once`` commandline option.

- The template .tex file is dumped into ``~/.tikz2pdf.tex``; you may
  adapt it to your needs, e.g. adding ``\usetikzlibarary`` etc. from your
  main document's preamble.

- Using --view of -s (for "start viewer"), you will automatically get
  a viewer (kpdf hardcoded currently) fired up that displays the first
  successfully compiled PDF (and if your viewer watches the PDF file,
  the display will automatically update after every change to the
  .tikz file).

- The output from calling pdflatex is hidden (unless you use
  ``--verbose``), but will be internally catched and output if
  pdflatex fails to allow you to see the error messages.

- At program exit, all (eh, see below) generated files are removed.


__ http://www.hackenberger.at/blog/ktikz-editor-for-the-tikz-language/

Future Work
-----------

The following limitations are to be solved:

- Ideally, it would be possible to include the same picture in
  multiple documents with different sizes.  The only way I see ATM is
  to define a length or command (e.g. ``\picturewidth``) that is used
  within the .tikz file.

- Similarly, I would occasionally like to add beamer commands to
  create animations (e.g. ``\pause{}`` or ``\only``), which works
  nicely, but again I would like to be able to use one .tikz file for
  both uses (I think this would be possible, thinking of beamer's
  article-mode, but I do not know yet, how).

- Currently, tikz2pdf only supports ``~/.tikz2pdf.tex``, but I want to
  change that eventually such that it also looks for templates in the
  directory of the .tikz file and its parent directories.  This would
  allow to automatically pick up a matching preamble for every figure.

- Make the PDF viewer configurable.

- I don't know a reliable way to recognize which files were created by
  pdflatex, so I am overly careful with removing them.  As long as the
  basename of the .tex file is ``tikz2pdf_temp.*``, I decided to
  remove all these files, but originally I planned for the PDF name to
  depend on the .tikz basename.