From 6bc1f5497cfb2f56d65c80a4c36ea3bad6dc046c Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 29 Oct 2010 00:31:31 +0000
Subject: pgf 2.10 (28oct10)

git-svn-id: svn://tug.org/texlive/trunk@20236 c570f23f-e606-0410-a88d-b1316a301751
---
 .../tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex  | 414 +++++++++++++++++++++
 1 file changed, 414 insertions(+)
 create mode 100644 Master/texmf-dist/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex

(limited to 'Master/texmf-dist/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex')

diff --git a/Master/texmf-dist/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex b/Master/texmf-dist/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex
new file mode 100644
index 00000000000..e507d30e85c
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex
@@ -0,0 +1,414 @@
+%--------------------------------------------
+%
+% Package pgfplots
+%
+% Provides a user-friendly interface to create function plots (normal
+% plots, semi-logplots and double-logplots).
+% 
+% It is based on Till Tantau's PGF package.
+%
+% Copyright 2007/2008/2009 by Christian Feuersänger.
+%
+% This program is free software: you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or
+% (at your option) any later version.
+% 
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+% GNU General Public License for more details.
+% 
+% You should have received a copy of the GNU General Public License
+% along with this program.  If not, see <http://www.gnu.org/licenses/>.
+%
+%--------------------------------------------
+
+% This file provides an interface to the
+% pgfmanual.prettyprint.code.tex thing -- it allows to 
+%  *generate pdf crossrefs inside of codeexamples automatically*
+% without any user input.
+%
+% Thus, you write
+% \begin{codeexample}[]
+% \begin{tikzpicture}[options]
+% \end{tikzpicture}
+% \end{codeexample}
+% and pdf cross references to the definitions of 'tikzpicture'
+% and any options will be generated automatically.
+%
+% Furthermore, pdf cross references will be generated for everything
+% within vertical bars, |....|.
+%
+%
+%
+%
+%
+% The only necessary thing is that \pgfmanualpdflabel has been called
+% for every (fully qualified) key, control sequence, environment or
+% whatever.
+
+\newif\ifpgfmanualpdfwarnings
+\pgfmanualpdfwarningstrue
+
+\newif\ifpgfmanualshowlabels
+
+\pgfkeys{%
+	/codeexample/prettyprint/cs arguments/pgfkeys/.initial=1,
+	/codeexample/prettyprint/cs/pgfkeys/.code 2 args={\pgfmanualpdfref{#1}{#1}\{\pgfmanualprettyprintpgfkeys{#2}\pgfmanualclosebrace},
+	%
+	/codeexample/prettyprint/autolinks/.style={%
+		/codeexample/prettyprint/key name/.code={\pgfmanualpdfref{##1}{##1}},
+		/codeexample/prettyprint/key name with handler/.code 2 args={\pgfmanualpdfref{##1}{##1}/\pgfmanualpdfref{/handlers/##2}{##2}},
+		/codeexample/prettyprint/key value display only/.code={\pgfmanualprettyprintcode{##1}},
+		/codeexample/prettyprint/cs/.code={\pgfmanualpdfref{##1}{##1}},
+		/codeexample/prettyprint/cs with args/.code 2 args={\pgfmanualpdfref{##1}{##1}\{\pgfmanualprettyprintcode{##2}\pgfmanualclosebrace},
+		/codeexample/prettyprint/cs arguments/pgfkeys/.initial=1,
+		/codeexample/prettyprint/cs/pgfkeys/.code 2 args={\pgfmanualpdfref{##1}{##1}\{\pgfmanualprettyprintpgfkeys{##2}\pgfmanualclosebrace},
+		/codeexample/prettyprint/cs arguments/begin/.initial=1,
+		/codeexample/prettyprint/cs/begin/.code 2 args={##1\{\pgfmanualpdfref{##2}{##2}\pgfmanualclosebrace},
+		/codeexample/prettyprint/cs arguments/end/.initial=1,
+		/codeexample/prettyprint/cs/end/.code 2 args={##1\{\pgfmanualpdfref{##2}{##2}\pgfmanualclosebrace},
+		/codeexample/prettyprint/word/.code={\begingroup\pgfkeyssetvalue{/pdflinks/search key prefixes in}{}\pgfmanualpdfref{##1}{##1}\endgroup},
+		/codeexample/prettyprint/point/.code={##1},%
+		/codeexample/prettyprint/point with cs/.code 2 args={(\pgfmanualpdfref{##1}{##1}:##2},%
+	},%
+	/codeexample/prettyprint/autolinks,
+}%
+
+\pgfkeys{
+	%
+	% Enables or disables the parsing of codeexamples.
+	/pdflinks/codeexample links/.is if=pgfmanualprettyenabled,
+	/pdflinks/codeexample links/.default=true,
+	%
+	% whenever an unqualified key is found, the following key prefix
+	% list is tried to find a match.
+	/pdflinks/search key prefixes in/.initial={/tikz/,/pgf/},
+	%
+	% Enables or disables warnings for failed auto links:
+	/pdflinks/warnings/.is if=pgfmanualpdfwarnings,
+	/pdflinks/warnings/.default=true,
+	%
+	% Shows the autogenerated labels. This is useful to check if the
+	% 'search key prefixes in' worked as it ought to.
+	/pdflinks/show labels/.is if=pgfmanualshowlabels,
+	/pdflinks/show labels/.default=true,
+	/pdflinks/show labels=false,
+	% will be invoked with '#1' set to the generated label.
+	/pdflinks/show labels code/.code={
+		\hbox to 0pt{%
+			\vbox to 0pt{\hsize=0pt
+				\vskip-\baselineskip
+				\hbox to \hsize{%
+					\hss
+					{\footnotesize\ttfamily\textcolor{red}{#1}}%
+					\hss
+				}%
+				\vss
+			}%
+			\vbox to 0pt{\hsize=0pt
+				\vss
+				\hbox to \hsize{%
+					\hss
+					{\footnotesize\ttfamily\textcolor{red}{$\vert$}}%
+					\hss
+				}%
+			}%
+			\vsize=0pt
+		}%
+	},
+	%
+	% the link prefix written to the pdf file:
+	/pdflinks/internal link prefix/.initial=pgf,
+}
+
+\gdef\pgfmanualpdf@installreplacements{%
+	\def\marg##1{{##1}}%
+	\def\oarg##1{[##1]}%
+	\def\meta##1{<##1>}%
+	\def\x{x}%
+	\def\textbackslash{<CS>}%
+	\def\\{\textbackslash}%
+	\def\space{:}%
+	\edef\ {\space}%
+	\edef\#{}%
+	\def\printanat{@}%
+	\def\protect{}%
+	\def\textasciicircum{o}%
+	\expandafter\edef\pgfmanual@verb@activebar{\pgfmanual@verb@bar}%
+}%
+
+% Defines a new pdf cross ref label for use with \pgfmanualpdfref.
+%
+% Usage:
+% 	\pgfmanualpdflabel{<label>}{<text>}
+% #1: the label.
+% The text #2 will be shown in the resulting pdf (if it is not empty).
+%
+% There is also support for catcode changes if <label> contains
+% something which shouldn't be written as-is into .aux files:
+% 	\pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}
+% -> this will write
+% \begingroup \catcode `\|=12 
+%   <code to deal with the label |-  >
+% \endgroup 
+% into the .aux file.
+%
+\def\pgfmanualpdflabel{\pgfutil@ifnextchar[{\pgfmanualpdflabel@opt}{\pgfmanualpdflabel@opt[]}}%
+\def\pgfmanualpdflabel@opt[#1]#2#3{%
+	\begingroup
+	%
+	\def\pgfmanualpdf@catcode{#1}%
+	\pgfmanualpdf@catcode
+	%
+	\pgfmanualpdflabel@generate{#2}{#3}%
+	%
+	% this is pgfplots-specific: pgfplots supports generic styles which
+	% contain '\x' where '\x' iterates through 'x,y,z'.
+	\pgfutil@in@\x{#2}%
+	\ifpgfutil@in@
+		\def\x{y}%
+		\pgfmanualpdflabel@generate{#2}{#3}%
+		\def\x{z}%
+		\pgfmanualpdflabel@generate{#2}{#3}%
+	\fi
+	\endgroup
+}%
+\def\pgfmanualpdflabel@generate#1#2{%
+	\pgfmanual@handlespeciallabeltokens@in{#1}%
+	%
+	\def\pgfmanualpdflabel@generateone{0}%
+	\pgfutil@ifundefined{pgfd@lbl@\pgfmanualpdflabel@@}{%
+		% ok, no such label is known.
+		\def\pgfmanualpdflabel@generateone{1}%
+	}{%
+		\if\csname pgfd@lbl@\pgfmanualpdflabel@@\endcsname a% "a"ux
+			% ah, it is "just" known from a previous run, but there is
+			% no code in the pdf! Write it!
+			\def\pgfmanualpdflabel@generateone{1}%
+		\else
+			% ok, we already wrote one before. Skip.
+		\fi
+	}%
+	\if\pgfmanualpdflabel@generateone1%
+		\ifpgfmanualshowlabels
+			\pgfkeysvalueof{/pdflinks/show labels code/.@cmd}{\pgfmanualpdflabel@@}\pgfeov
+		\fi
+		%
+		\if@filesw
+		\ifx\pgfmanualpdf@catcode\pgfutil@empty
+		\else
+			\toks0=\expandafter{\pgfmanualpdf@catcode}%
+			\immediate\write\@auxout{%
+				\noexpand\begingroup
+				\the\toks0
+			}%
+		\fi
+		\immediate\write\@auxout{%
+			\noexpand\expandafter\noexpand\gdef
+			\noexpand\csname pgfd@lbl@\pgfmanualpdflabel@@\noexpand\endcsname{a}% a = known in "a"ux file
+		}%
+		\ifx\pgfmanualpdf@catcode\pgfutil@empty
+		\else
+			\immediate\write\@auxout{\noexpand\endgroup}%
+		\fi
+		\fi
+		\expandafter\gdef\csname pgfd@lbl@\pgfmanualpdflabel@@\endcsname{w}% 1. remember the label AND remember that we "w"rote it into the pdf.
+		\edef\pgfmanualpdflabel@@{\pgfkeysvalueof{/pdflinks/internal link prefix}.\pgfmanualpdflabel@@}%
+		\expandafter\hypertarget\expandafter{\pgfmanualpdflabel@@}{#2}%
+	\else
+		#2%
+	\fi
+}%
+
+% A pdf reference to label `#1' with (TeX) text `#2'.
+% @see also \verbpdfref.
+\def\pgfmanualpdfref#1#2{%
+	\begingroup
+	\pgfmanual@handlespeciallabeltokens@in{#1}%
+	%
+	\ifcsname pgfd@lbl@\pgfmanualpdflabel@@\endcsname
+	\else
+		\global\let\pgfmanual@glob=\pgfmanualpdflabel@@
+		\def\pgfmanual@tempa{\foreach \prefix in }%
+		\pgfkeysgetvalue{/pdflinks/search key prefixes in}\pgfmanual@tempb
+		\expandafter\pgfmanual@tempa\expandafter{\pgfmanual@tempb}{%
+			\edef\pgfmanualpdflabel@@{\prefix\pgfmanualpdflabel@@}%
+			\expandafter\pgfmanual@handlespeciallabeltokens@in\expandafter{\pgfmanualpdflabel@@}%
+			\ifcsname pgfd@lbl@\pgfmanualpdflabel@@\endcsname
+				\xdef\pgfmanual@glob{\pgfmanualpdflabel@@}%
+				\breakforeach
+			\fi
+		}%
+		\let\pgfmanualpdflabel@@=\pgfmanual@glob
+		\ifcsname pgfd@lbl@\pgfmanualpdflabel@@\endcsname
+		\else
+			\ifpgfmanualpdfwarnings
+				\begingroup
+					\toks0={#1}%
+					\pgfmanual@warning{pgfmanualpdfref{\the\toks0 }: target label does not exist.}%
+				\endgroup
+			\fi
+			#2%
+			\let\pgfmanualpdflabel@@=\pgfutil@empty
+		\fi
+	\fi
+	\ifx\pgfmanualpdflabel@@\pgfutil@empty
+	\else
+		\expandafter\pgfmanualpdfref@\expandafter{\pgfmanualpdflabel@@}{#2}%
+	\fi
+	\endgroup
+}%
+\def\pgfmanualpdfref@#1#2{%
+	\pgfkeysgetvalue{/pdflinks/internal link prefix}\pgfmanual@temp
+	\expandafter\hyperlink\expandafter{\pgfmanual@temp.#1}{#2}%
+	\ifpgfmanualshowlabels
+		\pgfkeysvalueof{/pdflinks/show labels code/.@cmd}{#1}\pgfeov
+	\fi
+}%
+
+% Handles special tokens in a pdf label which should be treated with
+% care.
+%
+% For example, backslashes might produce problems. 
+% This occurs quite frequently with automatically generated hyperrefs 
+% inside of codeexamples where \pgfmanualpdfref will be invoked - 
+% there, we get the catcode 12 backslashes. 
+% Check for them!
+%
+% #1: a token list which shall be used either as cross ref or as
+% label.
+%
+% On output, the macro \pgfmanualpdflabel@@ will be '\edef'ed to the
+% new, possibly modified value.
+\def\pgfmanual@handlespeciallabeltokens@in#1{%
+	\begingroup
+	\pgfmanualpdf@installreplacements
+	\expandafter\pgfutil@in@\pgfmanual@pretty@backslash{#1}%
+	\ifpgfutil@in@
+		% assume the backslash is the first char and substitute it:
+		\pgfmanualpdfref@substitute@backslash#1\relax
+	\else
+		\edef\pgfmanualpdflabel@@{#1}%
+	\fi
+	\def\pgfmanual@tmp{\pgfutilstrreplace{ }{\space}}%
+	\expandafter\pgfmanual@tmp\expandafter{\pgfmanualpdflabel@@}%
+	\edef\pgfmanualpdflabel@@{\pgfretval}%
+	\pgfmath@smuggleone\pgfmanualpdflabel@@
+	\endgroup
+}%
+
+\expandafter\def\expandafter\pgfmanualpdfref@substitute@backslash\expandafter#\expandafter1\pgfmanual@pretty@backslash#2\relax{%
+	\edef\pgfmanualpdflabel@@{#1\textbackslash #2}%
+}%
+
+% Typesets '#1' in red,\texttt like every declaration. It will also
+% generate a pdf cross ref anchor for #1.
+%
+% WARNING: this changes catcodes! In case this is not acceptable in
+% your context, you will need to generate a \pgfmanualpdflabel
+% manually.
+%
+% \declareandlabel{\controlsequence}  can be used as |\controlsequence|
+\def\declareandlabel{%
+	\begingroup
+	\pgfmanual@verb@preparecatcodes@
+	\def\pgfmanualprettyprinterhandlecollectedargs##1{%
+		\pgfmanualpdflabel##1{\texttt{\declare##1}}% mark: '##1' contains already braces.
+		\endgroup
+	}%
+	\pgfmanualprettyprintercollectargcount1{\relax}%
+}
+
+% 
+% \verbpdfref{\controlsequence more stuff}
+% is the same as writing |\controlsequence more stuff|, but the
+% *complete* argument is supposed to be one label.
+% 
+% The difference to \pgfmanualpdfref{...}{} is that the argument is
+% supposed to be verbatim text.
+\def\verbpdfref{%
+	\begingroup
+	\pgfmanual@verb@preparecatcodes@
+	\def\pgfmanualprettyprinterhandlecollectedargs##1{%
+		\pgfmanualpdfref##1{\texttt{##1}}% mark: '##1' contains already braces.
+		\endgroup
+	}%
+	\pgfmanualprettyprintercollectargcount1{\relax}%
+}
+
+% Prepare active vertical bars, |....| for auto-pretty cross
+% referencing.
+%
+% Example: 
+%  |\pgfkeys| -> will generate a hyperref!
+{
+	\catcode`\|=12
+	\gdef\pgfmanual@verb@bar{|}%
+%	\gdef\pgfmanual@verb@collect#1|{%
+%		% this command will also handle control sequences.
+%		\texttt{\pgfmanualprettyprintpgfkeys{#1}}%
+%		\endgroup
+%	}%
+	\catcode`\|=13
+	\gdef\pgfmanual@verb@activebar{|}%
+}
+\def\pgfmanual@verb{%
+	\begingroup
+	\pgfmanual@verb@preparecatcodes@
+	\toksdef\t@pgfmanual@verb=0
+	\t@pgfmanual@verb={}%
+	\pgfmanual@verb@collect
+}
+% this version of \pgfmanual@verb@collect is less efficient than the
+% one uncommented above. BUT: it can auto-detect the case when
+% |...| has been provided somewhere where I can't change catcodes!
+% The other one would simply fail to compile.
+\def\pgfmanual@verb@collect#1{%
+	\def\pgfmanual@temp{#1}%
+	\ifx\pgfmanual@temp\pgfmanual@verb@bar
+		% ok, finish:
+		\edef\pgfmanual@verb@collect@next{%
+			% this command will also handle control sequences.
+			\noexpand\endgroup
+			\noexpand\texttt{\noexpand\pgfmanualprettyprintpgfkeys{\the\t@pgfmanual@verb}}%
+		}%
+	\else
+		\ifx\pgfmanual@temp\pgfmanual@verb@activebar
+			% ohoh... that should not happen! It means someone invoked
+			% |...| within an argument; I couln't change catcodes.
+			% Ok, resort to a simple fallback solution.
+			% FIXME : I have just realized that THIS DOESN'T PRESERVE SPACES
+			\edef\pgfmanual@verb@collect@next{%
+				\noexpand\endgroup
+				\noexpand\texttt{\the\t@pgfmanual@verb}%
+			}%
+		\else
+			\t@pgfmanual@verb=\expandafter{\the\t@pgfmanual@verb #1}%
+			\let\pgfmanual@verb@collect@next=\pgfmanual@verb@collect
+		\fi
+	\fi
+	\pgfmanual@verb@collect@next
+}%
+
+\AtBeginDocument{%
+	\ifpgfmanualprettyenabled
+		\catcode`\|=13
+		\expandafter\let\pgfmanual@verb@activebar=\pgfmanual@verb
+	\fi
+}%
+
+\def\pgfmanual@verb@preparecatcodes@{%
+	\let\do\@makeother%
+	\dospecials%
+	\catcode`\%=12 % THATS IMPORTANT! Do *not* handle comments!
+	% these catcodes are expected by the pretty printer...
+	%\catcode`\^^M=13
+	\catcode`\ =13
+	\catcode`\^^I=13
+	\expandafter\def\pgfmanual@pretty@activespace{\space}%
+	\expandafter\def\pgfmanual@pretty@activetab{\space\space\space\space}%
+}%
+\endinput
+% vi: ts=4 sw=4
-- 
cgit v1.2.3

