storebox 1.3 (20dec11)

git-svn-id: svn://tug.org/texlive/trunk@24895 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 348 insertions, 10 deletions

diff --git a/Master/texmf-dist/source/latex/storebox/storebox.dtx b/Master/texmf-dist/source/latex/storebox/storebox.dtx
index b81f06d36dd..cbc7d3b39c4 100644
--- a/Master/texmf-dist/source/latex/storebox/storebox.dtx
+++ b/Master/texmf-dist/source/latex/storebox/storebox.dtx
@@ -15,7 +15,7 @@
 %% The Current Maintainer of this work is Martin Scharrer.
 %%
 %% This work consists of the files storebox.dtx and storebox.ins
-%% and the derived filebase storebox.sty.
+%% and the derived filebase storebox.sty and storebox-pgf.sty.
 %%
 %<=/COPYRIGHT>
 % \fi
@@ -24,10 +24,10 @@
 %<*driver>
 \ProvidesFile{storebox.dtx}[%
 %<=*DATE>
-    2011/10/21
+    2011/12/21
 %<=/DATE>
 %<=*VERSION>
-    v1.1
+    v1.3a
 %<=/VERSION>
     DTX file for storebox]
 \documentclass{ydoc}
@@ -44,7 +44,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{137}
+% \CheckSum{680}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -66,6 +66,9 @@
 % \changes{v0.99}{2011/08/05}{Converted to DTX file.}
 % \changes{v1.0}{2011/09/22}{First release.}
 % \changes{v1.1}{2011/10/21}{Fixed issue with \env{storebox} environment with new \pkg{collectbox} version.}
+% \changes{v1.2}{2011/12/19}{Added PDF resources argument to support transparent material.}
+% \changes{v1.3}{2011/12/20}{Added patch for PDF pdftex driver to fully support transparent material and shadings.}
+% \changes{v1.3a}{2011/12/21}{Made the use of \cs{immediate} optional so that unused storeboxes are not written to the PDF.}
 %
 % \DoNotIndex{\newcommand,\newenvironment}
 %
@@ -95,15 +98,32 @@
 % This package provides ``store boxes'' which have the same user interface like normal \LaTeX{} ``save boxes'', but only
 % store the content once in the output file even if it is used several times.
 % At the moment only PDF output is supported (i.e.\ \texttt{pdflatex} and \texttt{lualatex}).
-% If the stored content is not used in the document after all it is not written to the PDF (at least the \texttt{pdftex} manual says so).
+% If the stored content is not used in the document after all it is not written to the PDF except if the \opt{immediate} option was used.
 % For any other \TeX{} and output format the package simply falls back to use the normal savebox equivalents.
 %
+% \section{Known issues}
+% There are some known side effects with advanced graphic elements, namely transparencies and shadings.
+% These elements require special driver code which adds the required PDF instructions. For TikZ/PGF drawings this is done
+% by the |pdftex| driver of TikZ/PGF. However, due to a
+% \href{https://sourceforge.net/tracker/?func=detail&atid=752792&aid=3462542&group_id=142562}{bug in this driver}
+% transparent material is not supported, but shown fully opaque if the storebox also holds PDF shadings.
+% This affects \file{pgfsys-pdftex.def} in v1.26 from 2009/05/22 and earlier versions.
+% Since \pkg{storebox} v1.3 from 2011/12/20 a set of patches for the PGF |pdftex| driver is loaded (as support package \pkg{storebox-pgf}),
+% so that both transparencies and shadings are supported together. The patches are not loaded if a new version of the driver is detected.
+% Please report all issues with this patches to the \pkg{storebox} author, not to the TikZ/PGF authors.
+%
 % \section{Options}
-% The package should be loaded without any options and then automatically checks for PDF output (using the \pkg{ifpdf} package).
+% The package allows to enable and disable the storebox feature. Normally this is selected automatically dependent if PDF output is used (using \pkg{ifpdf}).
 % It also provides two options \opt{enable} and \opt{disable} to explicitly switch the storebox feature on or off.
 % The \opt{disable} option is useful to see the resulting file size difference.
 % The usage of the \opt{enable} option should not be required and will lead to errors if used with unsupported \TeX{} formats.
 %
+% Two further complementary options \opt{delayed} (default) and \opt{immediate} are provided.
+% They control if a storebox (i.e.\ the underlying \Macro\pdfxform) is written to the PDF immediately or only after it gets referenced, i.e.\ is inserted into the document using
+% \Macro\usestorebox. With \opt{immediate} the storebox is always written into the PDF, even if it is not used. By default \opt{delayed} is used, but
+% it is possible that \opt{immediate} is required if \Macro\storebox is used inside other \Macro\pdfxform\relax's, e.g.\ inside certain TikZ/PGF nodes.
+% If any graphic issues occur in a document the \opt{immediate} option should first be tested before sending any bug reports.
+%
 % \Needspace*{3cm}
 % \section{Macros}
 %
@@ -197,9 +217,11 @@
 %    \begin{macrocode}
 \DeclareOption{disable}{\let\ifstorebox\iffalse}
 \DeclareOption{enable}{\let\ifstorebox\iftrue}
+\DeclareOption{immediate}{\let\storebox@immediate\immediate}
+\DeclareOption{delayed}{\let\storebox@immediate\relax}
+\ExecuteOptions{delayed}
 \ProcessOptions*
-\edef\@tempa{\@ptionlist{\@currname.\@currext}}
-\ifx\@tempa\empty
+\expandafter\ifx\csname ifstorebox\endcsname\relax
     \RequirePackage{ifpdf}
     \expandafter\let\csname ifstorebox\expandafter\endcsname\csname ifpdf\endcsname
 \fi
@@ -235,7 +257,10 @@
 %    \begin{macrocode}
 \def\@storebox#1{%
     \begingroup
-    \@collectboxto\collectedbox{\pdfxform\collectedbox\endgroup\mathchardef#1=\pdflastxform}%
+    \@collectboxto\collectedbox{%
+        \storebox@immediate\pdfxform resources {\the\pdfpageresources}\collectedbox
+        \endgroup\mathchardef#1=\pdflastxform
+    }%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -281,7 +306,7 @@
 \def\@storebox@env@end{%
     \edef\@tempa{%
         \egroup
-        \pdfxform\collectedbox
+        \immediate\pdfxform resources {\the\pdfpageresources}\collectedbox
         \endgroup
         \mathchardef\expandafter\noexpand\the@storebox=\pdflastxform
     }%
@@ -307,6 +332,12 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% Load PGF driver patches if required:
+%    \begin{macrocode}
+\AtBeginDocument{%
+    \@ifpackageloaded{pgf}{\RequirePackage{storebox-pgf}{}}%
+}
+%    \end{macrocode}
 %
 %    \begin{macrocode}
 \else
@@ -365,5 +396,311 @@
 %</storebox.sty>
 % \fi
 %
+%
+% \subsection{PGF patches}
+%
+% \iffalse
+%<*storebox-pgf.sty>
+% \fi
+%    \begin{macrocode}
+%% This support package contains patches for the file 'pgfsys-pdftex.def' file from
+%% the TikZ/PGF bundle. All patches code is copyright by the TikZ/PGF authors
+%% and is used in this file according to the LPPL license.
+%% Please see the copyright and license notices in the 'pgfsys-pdftex.def' file.
+%%
+%% The rest of the code of this file is under the following copyright and licence:
+%%
+%<!COPYRIGHT>
+\ProvidesPackage{storebox-pgf}[%
+%<!DATE>
+%<!VERSION>
+%<*DRIVER>
+    2099/01/01 develop
+%</DRIVER>
+    Patches for PGF to support transparency and shadings inside storeboxes]
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\begingroup
+\let\on@line\@gobble
+%
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\@ifl@ter{def}{pgfsys-pdftex}{2009/05/23}{%
+   \PackageInfo{storebox-pgf}{Newer version of 'pgfsys-pdftex.def' found.\MessageBreak No patches applied.}%
+   \endgroup
+   \endinput
+}{}%
+%    \end{macrocode}
+%
+% \begin{macro}{\storebox@patch}
+%    \begin{macrocode}
+\def\storebox@patch#1#2#3#4{%
+    \ifx#1\@undefined
+        \PackageInfo{storebox-pgf}{Macro \string#1\space not defined.\MessageBreak No patch applied.}%
+    \else
+        \def\@tempa#2{#3}%
+        \ifx#1\@tempa
+            \PackageInfo{storebox-pgf}{Patching macro \string#1.}%
+            \gdef#1#2{#4}%
+        \else
+            \PackageInfo{storebox-pgf}{Macro \string#1\space with unknown definition.\MessageBreak No patch applied.}%
+        \fi
+    \fi
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%    \begin{macrocode}
+\storebox@patch\pgfsys@horishading{#1#2#3}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \pgfmathparse{#2}%
+    \setbox\pgfutil@tempboxa=\hbox to\pgf@max{\vbox to\pgfmathresult pt{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{\pgfpoint{\pgf@max}{#2}}%
+    \pdfxform resources {%
+      /Shading << /Sh << /ShadingType 2
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [\pgf@doma\space0 \pgf@domb\space0]
+      /Function \pgf@pdfparsedfunction
+      /Extend [false false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \pgfmathparse{#2}%
+    \setbox\pgfutil@tempboxa=\hbox to\pgf@max{\vbox to\pgfmathresult pt{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{\pgfpoint{\pgf@max}{#2}}%
+    \immediate\pdfxform resources {%
+      /Shading << /Sh << /ShadingType 2
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [\pgf@doma\space0 \pgf@domb\space0]
+      /Function \pgf@pdfparsedfunction
+      /Extend [false false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\storebox@patch\pgfsys@vertshading{#1#2#3}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \pgfmathparse{#2}%
+    \setbox\pgfutil@tempboxa=\hbox to\pgfmathresult pt{\vbox to\pgf@max{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{\pgfpoint{#2}{\pgf@max}}%
+    \pdfxform resources {%
+      /Shading << /Sh << /ShadingType 2
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [0 \pgf@doma\space0 \pgf@domb]
+      /Function \pgf@pdfparsedfunction
+      /Extend [false false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \pgfmathparse{#2}%
+    \setbox\pgfutil@tempboxa=\hbox to\pgfmathresult pt{\vbox to\pgf@max{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{\pgfpoint{#2}{\pgf@max}}%
+    \immediate\pdfxform resources {%
+      /Shading << /Sh << /ShadingType 2
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [0 \pgf@doma\space0 \pgf@domb]
+      /Function \pgf@pdfparsedfunction
+      /Extend [false false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\storebox@patch\pgfsys@radialshading{#1#2#3}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \setbox\pgfutil@tempboxa=\hbox to2\pgf@max{\vbox to2\pgf@max{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{#2}%
+    \pgf@xa=\pgf@x%
+    \pgf@ya=\pgf@y%
+    \pgf@process{\pgfpoint{\pgf@max}{\pgf@max}}%
+    \advance\pgf@xa by \pgf@x%
+    \advance\pgf@ya by \pgf@y%
+    \pgf@sys@bp@correct{\pgf@x}%
+    \pgf@sys@bp@correct{\pgf@y}%
+    \pgf@sys@bp@correct{\pgf@xa}%
+    \pgf@sys@bp@correct{\pgf@ya}%
+    \pdfxform resources {%
+      /Shading << /Sh << /ShadingType 3
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [\pgf@sys@tonumber{\pgf@xa} \pgf@sys@tonumber{\pgf@ya} \pgf@doma\space \pgf@sys@tonumber{\pgf@x} \pgf@sys@tonumber{\pgf@y} \pgf@domb]
+      /Function \pgf@pdfparsedfunction
+      /Extend [true false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}{%
+  {%
+    \pgf@parsefunc{#3}%
+    \setbox\pgfutil@tempboxa=\hbox to2\pgf@max{\vbox to2\pgf@max{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@process{#2}%
+    \pgf@xa=\pgf@x%
+    \pgf@ya=\pgf@y%
+    \pgf@process{\pgfpoint{\pgf@max}{\pgf@max}}%
+    \advance\pgf@xa by \pgf@x%
+    \advance\pgf@ya by \pgf@y%
+    \pgf@sys@bp@correct{\pgf@x}%
+    \pgf@sys@bp@correct{\pgf@y}%
+    \pgf@sys@bp@correct{\pgf@xa}%
+    \pgf@sys@bp@correct{\pgf@ya}%
+    \immediate\pdfxform resources {%
+      /Shading << /Sh << /ShadingType 3
+      /ColorSpace /DeviceRGB
+      /Domain [\pgf@pdfparseddomain]
+      /Coords [\pgf@sys@tonumber{\pgf@xa} \pgf@sys@tonumber{\pgf@ya} \pgf@doma\space \pgf@sys@tonumber{\pgf@x} \pgf@sys@tonumber{\pgf@y} \pgf@domb]
+      /Function \pgf@pdfparsedfunction
+      /Extend [true false] >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{\leavevmode\noexpand\pdfrefxform\the\pdflastxform}%
+  }%
+}%
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\storebox@patch\pgfsys@functionalshading{#1#2#3#4}{%
+  {%
+    \pgf@process{#2}%
+    \pgf@xa=\pgf@x%
+    \pgf@ya=\pgf@y%
+    \pgf@process{#3}%
+    \pgf@xb=\pgf@x%
+    \pgf@yb=\pgf@y%
+    \advance\pgf@x by-\pgf@xa%
+    \advance\pgf@y by-\pgf@ya%
+    \setbox\pgfutil@tempboxa=\hbox to\pgf@x{\vbox to\pgf@y{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@sys@bp@correct{\pgf@xa}%
+    \pgf@sys@bp@correct{\pgf@ya}%
+    \pgf@sys@bp@correct{\pgf@xb}%
+    \pgf@sys@bp@correct{\pgf@yb}%
+    \pgf@xc=-\pgf@xa%
+    \pgf@yc=-\pgf@ya%
+    % Now build the function
+    \pdfobj
+    stream
+    attr
+    {
+      /FunctionType 4
+      /Domain [\pgf@sys@tonumber{\pgf@xa}\space\pgf@sys@tonumber{\pgf@xb}\space\pgf@sys@tonumber{\pgf@ya}\space\pgf@sys@tonumber{\pgf@yb}]
+      /Range [0 1 0 1 0 1]
+    }
+    {{#4}}%
+    \edef\pgf@temp@num{\the\pdflastobj}%
+    \pdfxform resources {%
+      /Shading << /Sh << /ShadingType 1
+      /ColorSpace /DeviceRGB
+      /Matrix [1 0 0 1 \pgf@sys@tonumber{\pgf@xc}\space\pgf@sys@tonumber{\pgf@yc}]
+      /Domain [\pgf@sys@tonumber{\pgf@xa}\space\pgf@sys@tonumber{\pgf@xb}\space\pgf@sys@tonumber{\pgf@ya}\space\pgf@sys@tonumber{\pgf@yb}]
+      /Function \pgf@temp@num\space 0 R
+      >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{%
+      \leavevmode%
+      \noexpand\pdfrefxform\the\pdflastxform%
+      \noexpand\pdfrefobj\pgf@temp@num%
+    }%
+  }%
+}{%
+  {%
+    \pgf@process{#2}%
+    \pgf@xa=\pgf@x%
+    \pgf@ya=\pgf@y%
+    \pgf@process{#3}%
+    \pgf@xb=\pgf@x%
+    \pgf@yb=\pgf@y%
+    \advance\pgf@x by-\pgf@xa%
+    \advance\pgf@y by-\pgf@ya%
+    \setbox\pgfutil@tempboxa=\hbox to\pgf@x{\vbox to\pgf@y{\vfil\pgfsys@invoke{/Sh sh}}\hfil}%
+    \pgf@sys@bp@correct{\pgf@xa}%
+    \pgf@sys@bp@correct{\pgf@ya}%
+    \pgf@sys@bp@correct{\pgf@xb}%
+    \pgf@sys@bp@correct{\pgf@yb}%
+    \pgf@xc=-\pgf@xa%
+    \pgf@yc=-\pgf@ya%
+    % Now build the function
+    \pdfobj
+    stream
+    attr
+    {
+      /FunctionType 4
+      /Domain [\pgf@sys@tonumber{\pgf@xa}\space\pgf@sys@tonumber{\pgf@xb}\space\pgf@sys@tonumber{\pgf@ya}\space\pgf@sys@tonumber{\pgf@yb}]
+      /Range [0 1 0 1 0 1]
+    }
+    {{#4}}%
+    \edef\pgf@temp@num{\the\pdflastobj}%
+    \immediate\pdfxform resources {%
+      /Shading << /Sh << /ShadingType 1
+      /ColorSpace /DeviceRGB
+      /Matrix [1 0 0 1 \pgf@sys@tonumber{\pgf@xc}\space\pgf@sys@tonumber{\pgf@yc}]
+      /Domain [\pgf@sys@tonumber{\pgf@xa}\space\pgf@sys@tonumber{\pgf@xb}\space\pgf@sys@tonumber{\pgf@ya}\space\pgf@sys@tonumber{\pgf@yb}]
+      /Function \pgf@temp@num\space 0 R
+      >> >>}\pgfutil@tempboxa% <<
+    \expandafter\xdef\csname @pgfshading#1!\endcsname{%
+      \leavevmode%
+      \noexpand\pdfrefxform\the\pdflastxform%
+      \noexpand\pdfrefobj\pgf@temp@num%
+    }%
+  }%
+}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\storebox@patch\pgfsys@fadingfrombox{#1#2}{%
+  {%
+    \pgf@sys@pdf@check@resources%
+    \pgf@x=-.5\wd#2%
+    \pgf@y=-.5\ht#2%
+    \advance\pgf@y by.5\dp#2%
+    \expandafter\xdef\csname pgfsmasktrans@#1\endcsname{%
+      \noexpand\pgftransformcm{1}{0}{0}{1}{\noexpand\pgfqpoint{\the\pgf@x}{\the\pgf@y}}}%
+    \pdfxform resources { \pgf@sys@pdf@possible@resources } #2%
+    \expandafter\xdef\csname pgfsmaskxform@#1\endcsname{\the\pdflastxform}%
+  }%
+}{%
+  {%
+    \pgf@sys@pdf@check@resources%
+    \pgf@x=-.5\wd#2%
+    \pgf@y=-.5\ht#2%
+    \advance\pgf@y by.5\dp#2%
+    \expandafter\xdef\csname pgfsmasktrans@#1\endcsname{%
+      \noexpand\pgftransformcm{1}{0}{0}{1}{\noexpand\pgfqpoint{\the\pgf@x}{\the\pgf@y}}}%
+    \immediate\pdfxform resources { \pgf@sys@pdf@possible@resources } #2%
+    \expandafter\xdef\csname pgfsmaskxform@#1\endcsname{\the\pdflastxform}%
+  }%
+}
+\storebox@patch\pgfsys@transparencygroupfrombox{#1}{%
+  \pgf@sys@pdf@check@resources%
+  \pdfxform
+  attr { /Group << /S /Transparency >> } %<<
+  resources { \pgf@sys@pdf@possible@resources }
+  #1%
+  \setbox#1=\hbox{\pdfrefxform\pdflastxform}%
+}{%
+  \pgf@sys@pdf@check@resources%
+  \immediate\pdfxform
+  attr { /Group << /S /Transparency >> } %<<
+  resources { \pgf@sys@pdf@possible@resources }
+  #1%
+  \setbox#1=\hbox{\pdfrefxform\pdflastxform}%
+}
+\endgroup
+%    \end{macrocode}
+%
+% \iffalse
+%</storebox-pgf.sty>
+% \fi
+%
 % \Finale
 \endinput
diff --git a/Master/texmf-dist/source/latex/storebox/storebox.ins b/Master/texmf-dist/source/latex/storebox/storebox.ins
index 51a9cd38708..087a4c21720 100644
--- a/Master/texmf-dist/source/latex/storebox/storebox.ins
+++ b/Master/texmf-dist/source/latex/storebox/storebox.ins
@@ -4,6 +4,7 @@
 
 \generate{%
   \file{storebox.sty}{\nopreamble\from{storebox.dtx}{storebox.sty}}%
+  \file{storebox-pgf.sty}{\nopreamble\from{storebox.dtx}{storebox-pgf.sty}}%
 }
 \endbatchfile