% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.

\section{Installation}

There are different ways of installing \pgfname, depending
on your system and needs, and you may need to install other
packages as well as, see below. Before installing, you may wish to
review the licenses under which the package is
distributed, see Section~\ref{section-license}. 

Typically, the package will already be installed on your
system. Naturally, in this case you do not need to worry about the
installation process at all and you can skip the rest of this
section. 


\subsection{Package and Driver Versions}

This documentation is part of version \pgfversion\ of the \pgfname\
package. In order to run \pgfname, you need a reasonably recent 
\TeX\ installation. When using \LaTeX, you need the following packages
installed (newer versions should also work):
\begin{itemize}
\item
  |xcolor| version \xcolorversion.
\item
  |xkeyval| version \xkeyvalversion, if you wish to use \tikzname.
\end{itemize}
With plain \TeX, |xcolor| is not needed, but you obviously do not
get its (full) functionality. 

Currently, \pgfname\ supports the following backend drivers:
\begin{itemize}
\item
  |pdftex| version 0.14 or higher. Earlier versions do not work.
\item
  |dvips| version 5.94a or higher. Earlier versions may also work.

  For inter-picture connections, you need process pictures using
  |pdftex| version 1.40 or higher running in DVI mode.
\item
  |dvipdfm| version 0.13.2c or higher. Earlier versions may also work.

  For inter-picture connections, you need process pictures using
  |pdftex| version 1.40 or higher running in DVI mode.
\item
  |tex4ht| version 2003-05-05 or higher. Earlier versions may also work.
\item
  |vtex| version 8.46a or higher. Earlier versions may also work.
\item
  |textures| version 2.1 or higher. Earlier versions may also work.
\end{itemize}

Currently, \pgfname\ supports the following formats:
\begin{itemize}
\item
  |latex| with complete functionality.
\item
  |plain| with complete functionality, except for graphics inclusion,
  which works only for pdf\TeX.
\item
  |context| with complete functionality, except for graphics inclusion,
  which works only for pdf\TeX.
\end{itemize}

For more details, see Section~\ref{section-formats}.



\subsection{Installing Prebundled Packages}

I do not create or manage prebundled packages of \pgfname, but,
fortunately, nice other people do. I cannot give detailed instructions
on how to install these packages, since I do not manage them, but I
\emph{can} tell you were to find them. If you have a problem with
installing, you might wish to have a look at the Debian page or the
Mik\TeX\ page first.


\subsubsection{Debian}

The command ``|aptitude install pgf|'' should do the trick. Sit back
and relax. In detail, the following packages are installed:  
\begin{verbatim}
http://packages.debian.org/pgf
http://packages.debian.org/latex-xcolor
\end{verbatim}


\subsubsection{MiKTeX}

For MiK\TeX, use the update wizard to install the (latest versions of
the) packages called |pgf|, |xcolor|, and |xkeyval|. 




\subsection{Installation in a texmf Tree}

For a permanent installation, you place the files of the
the \textsc{pgf} package in an appropriate |texmf| tree. 

When you ask \TeX\ to use a certain class or package, it usually looks
for the necessary files in so-called |texmf| trees. These trees
are simply huge directories that contain these files. By default,
\TeX\ looks for files in three different |texmf| trees:
\begin{itemize}
\item
  The root |texmf| tree, which is usually located at
  |/usr/share/texmf/| or |c:\texmf\| or somewhere similar.
\item
  The local  |texmf| tree, which is usually located at
  |/usr/local/share/texmf/| or |c:\localtexmf\| or somewhere similar.
\item
  Your personal  |texmf| tree, which is usually located in your home
  directory at |~/texmf/| or |~/Library/texmf/|.   
\end{itemize}

You should install the packages either in the local tree or in
your personal tree, depending on whether you have write access to the
local tree. Installation in the root tree can cause problems, since an
update of the whole \TeX\ installation will replace this whole tree.


\subsubsection{Installation that Keeps Everything Together}

Once you have located the right texmf tree, you must decide whether
you want to install \pgfname\ in such a way that ``all its files are
kept in one place'' or whether you want to be
``\textsc{tds}-compliant,'' where \textsc{tds} means ``\TeX\ directory
structure.''

If you want to keep ``everything in one place,'' inside the |texmf|
tree that you have chosen create a sub-sub-directory called
|texmf/tex/generic/pgf| or
|texmf/tex/generic/pgf-|\texttt{\pgfversion}, if you prefer. Then
place all files of the |pgf| package in this directory. Finally,
rebuild \TeX's filename database. This is done by running the command
|texhash| or |mktexlsr| (they are the same). In Mik\TeX, there is a
menu option to do this. 


\subsubsection{Installation that is TDS-Compliant}

While the above installation process is the most ``natural'' one and
although I would like to recommend it since it makes updating and
managing the \pgfname\ package easy, it is not
\textsc{tds}-compliant. If you want to be \textsc{tds}-compliant,
proceed as follows: (If you do not know what \textsc{tds}-compliant
means, you probably do not want to be \textsc{tds}-compliant.)

The |.tar| file of the |pgf| package contains the following files and
directories at its root: |README|, |doc|,  |generic|, |plain|, and
|latex|. You should ``merge'' each of the four directories with the
following directories |texmf/doc|, |texmf/tex/generic|,
|texmf/tex/plain|, and |texmf/tex/latex|. For example, in the |.tar|
file the |doc| directory contains just the directory |pgf|, and this
directory has to be moved to |texmf/doc/pgf|. The root |README| file
can be ignored since it is reproduced in |doc/pgf/README|.

You may also consider keeping everything in one place and using
symbolic links to point from the \textsc{tds}-compliant directories to
the central installation.

\vskip1em
For a more detailed explanation of the standard installation process
of packages, you might wish to consult
\href{http://www.ctan.org/installationadvice/}{|http://www.ctan.org/installationadvice/|}.
However, note that the \pgfname\ package does not come with a
|.ins| file (simply skip that part).


\subsection{Updating the Installation}

To update your installation from a previous version, all you need to
do is to replace everything in the directory |texmf/tex/generic/pgf|
with the files of the new version (or in all the directories where
|pgf| was installed, if you chose a \textsc{tds}-compliant
installation). The easiest way to do this is to first delete the old
version and then proceed as described above. Sometimes, there are
changes in the syntax of certain command from version to version. If
things no longer work that used to work, you may wish to have a look
at the release notes and at the change log. 

