Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-installation.tex

raw
1 % Copyright 2018 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Installation}
12
13 There are different ways of installing \pgfname, depending on your system and
14 needs, and you may need to install other packages as well, see below. Before
15 installing, you may wish to review the licenses under which the package is
16 distributed, see Section~\ref{section-license}.
17
18 Typically, the package will already be installed on your system. Naturally, in
19 this case you do not need to worry about the installation process at all and
20 you can skip the rest of this section.
21
22
23 \subsection{Package and Driver Versions}
24
25 This documentation is part of version \pgfversion\ of the \pgfname\ package. In
26 order to run \pgfname, you need a reasonably recent \TeX\ installation. When
27 using \LaTeX, you need the following packages installed (newer versions should
28 also work):
29 %
30 \begin{itemize}
31 \item |xcolor| version \xcolorversion.
32 \end{itemize}
33 %
34 With plain \TeX, |xcolor| is not needed, but you obviously do not get its
35 (full) functionality.
36
37 Currently, \pgfname\ supports the following backend drivers:
38 %
39 \begin{itemize}
40 \item |luatex| version 0.76 or higher. Most earlier versions also work.
41 \item |pdftex| version 0.14 or higher. Earlier versions do not work.
42 \item |dvips| version 5.94a or higher. Earlier versions may also work.
43
44 For inter-picture connections, you need to process pictures using
45 |pdftex| version 1.40 or higher running in DVI mode.
46 \item |dvipdfm| version 0.13.2c or higher. Earlier versions may also
47 work.
48
49 For inter-picture connections, you need to process pictures using
50 |pdftex| version 1.40 or higher running in DVI mode.
51 \item |dvipdfmx| version 0.13.2c or higher. Earlier versions may also
52 work.
53 \item |dvisvgm| version 1.2.2 or higher. Earlier versions may also work.
54 \item |tex4ht| version 2003-05-05 or higher. Earlier versions may also
55 work.
56 \item |vtex| version 8.46a or higher. Earlier versions may also work.
57 \item |textures| version 2.1 or higher. Earlier versions may also work.
58 \item |xetex| version 0.996 or higher. Earlier versions may also work.
59 \end{itemize}
60
61 Currently, \pgfname\ supports the following formats:
62 %
63 \begin{itemize}
64 \item |latex| with complete functionality.
65 \item |plain| with complete functionality, except for graphics inclusion,
66 which works only for pdf\TeX.
67 \item |context| with complete functionality, except for graphics
68 inclusion, which works only for pdf\TeX.
69 \end{itemize}
70
71 For more details, see Section~\ref{section-formats}.
72
73
74 \subsection{Installing Prebundled Packages}
75
76 I do not create or manage prebundled packages of \pgfname, but, fortunately,
77 nice other people do. I cannot give detailed instructions on how to install
78 these packages, since I do not manage them, but I \emph{can} tell you were to
79 find them. If you have a problem with installing, you might wish to have a look
80 at the Debian page or the MiK\TeX\ page first.
81
82
83 \subsubsection{Debian}
84
85 The command ``|apt-get install texlive-pictures|'' should do the trick.
86 Sit back and relax.
87
88
89 \subsubsection{MiKTeX}
90
91 For MiK\TeX, use the update wizard to install the (latest versions of the)
92 packages called |pgf| and |xcolor|.
93
94
95 \subsection{Installation in a texmf Tree}
96
97 For a permanent installation, you place the files of the \textsc{pgf} package
98 in an appropriate |texmf| tree.
99
100 When you ask \TeX\ to use a certain class or package, it usually looks for the
101 necessary files in so-called |texmf| trees. These trees are simply huge
102 directories that contain these files. By default, \TeX\ looks for files in
103 three different |texmf| trees:
104 %
105 \begin{itemize}
106 \item The root |texmf| tree, which is usually located at
107 |/usr/share/texmf/| or |c:\texmf\| or somewhere similar.
108 \item The local |texmf| tree, which is usually located at
109 |/usr/local/share/texmf/| or |c:\localtexmf\| or somewhere similar.
110 \item Your personal |texmf| tree, which is usually located in your home
111 directory at |~/texmf/| or |~/Library/texmf/|.
112 \end{itemize}
113
114 You should install the packages either in the local tree or in your personal
115 tree, depending on whether you have write access to the local tree.
116 Installation in the root tree can cause problems, since an update of the whole
117 \TeX\ installation will replace this whole tree.
118
119
120 \subsubsection{Installation that Keeps Everything Together}
121
122 Once you have located the right texmf tree, you must decide whether you want to
123 install \pgfname\ in such a way that ``all its files are kept in one place'' or
124 whether you want to be ``\textsc{tds}-compliant'', where \textsc{tds} means
125 ``\TeX\ directory structure''.
126
127 If you want to keep ``everything in one place'', inside the |texmf| tree that
128 you have chosen create a sub-sub-directory called |texmf/tex/generic/pgf| or
129 |texmf/tex/generic/pgf-|\texttt{\pgfversion}, if you prefer. Then place all
130 files of the |pgf| package in this directory. Finally, rebuild \TeX's filename
131 database. This is done by running the command |texhash| or |mktexlsr| (they are
132 the same). In MiK\TeX, there is a menu option to do this.
133
134
135 \subsubsection{Installation that is TDS-Compliant}
136
137 While the above installation process is the most ``natural'' one and although I
138 would like to recommend it since it makes updating and managing the \pgfname\
139 package easy, it is not \textsc{tds}-compliant. If you want to be
140 \textsc{tds}-compliant, proceed as follows: (If you do not know what
141 \textsc{tds}-compliant means, you probably do not want to be
142 \textsc{tds}-compliant.)
143
144 The |.tar| file of the |pgf| package contains the following files and
145 directories at its root: |README|, |doc|, |generic|, |plain|, and |latex|. You
146 should ``merge'' each of the four directories with the following directories
147 |texmf/doc|, |texmf/tex/generic|, |texmf/tex/plain|, and |texmf/tex/latex|. For
148 example, in the |.tar| file the |doc| directory contains just the directory
149 |pgf|, and this directory has to be moved to |texmf/doc/pgf|. The root |README|
150 file can be ignored since it is reproduced in |doc/pgf/README|.
151
152 You may also consider keeping everything in one place and using symbolic links
153 to point from the \textsc{tds}-compliant directories to the central
154 installation.
155
156 \vskip1em For a more detailed explanation of the standard installation process
157 of packages, you might wish to consult
158 \href{http://www.ctan.org/installationadvice/}{|http://www.ctan.org/installationadvice/|}.
159 However, note that the \pgfname\ package does not come with a |.ins| file
160 (simply skip that part).
161
162
163 \subsection{Updating the Installation}
164
165 To update your installation from a previous version, all you need to do is to
166 replace everything in the directory |texmf/tex/generic/pgf| with the files of
167 the new version (or in all the directories where |pgf| was installed, if you
168 chose a \textsc{tds}-compliant installation). The easiest way to do this is to
169 first delete the old version and then proceed as described above. Sometimes,
170 there are changes in the syntax of certain commands from version to version. If
171 things no longer work that used to work, you may wish to have a look at the
172 release notes and at the change log.