gradientframe (13feb11)

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

1 files changed, 174 insertions, 71 deletions

diff --git a/Master/texmf-dist/source/latex/gradientframe/gradientframe.dtx b/Master/texmf-dist/source/latex/gradientframe/gradientframe.dtx
index f11c2751173..881840956bc 100644
--- a/Master/texmf-dist/source/latex/gradientframe/gradientframe.dtx
+++ b/Master/texmf-dist/source/latex/gradientframe/gradientframe.dtx
@@ -2,7 +2,7 @@
 %<*batchfile>
 {\obeylines\obeyspaces \gdef\thepreamble{
 
-LaTeX package gradientframe for simple gradient frames around objects.
+LaTeX package gradientframe for simple rectangular gradient frames around objects.
 
 Copyright (C) Christian Raue, 2011
 Send feedback to christian°raue@gmail°com (after being exposed to gravity).
@@ -17,7 +17,7 @@ version.  The latest version of this license is in:
 and version 1.3c or later is part of all distributions of
 LaTeX version 2005/12/01 or later.
 
-This work has the LPPL maintenance status 'maintained'.
+This work has the LPPL maintenance status "maintained".
 
 The Current Maintainer of this work is Christian Raue.
 
@@ -40,14 +40,18 @@ gradientframe.sty.
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
 \usepackage{charter}
-\usepackage[margin=1.5in]{geometry}
+\usepackage[%
+	inner=55mm,%
+	outer=10mm,%
+	top=20mm,%
+	bottom=20mm,%
+]{geometry}
 \usepackage{color}
-\usepackage{graphicx}
 \usepackage[%
 	pdftitle={the \jobname{} package},%
 	pdfauthor={Christian Raue},%
 	pdfsubject={LaTeX package documentation},%
-	pdfkeywords={\jobname{} LaTeX gradient frame border around object table figure},%
+	pdfkeywords={\jobname{} LaTeX rectangular gradient frame border around object table figure},%
  	pdfproducer={LaTeX},%
  	pdfcreator={LaTeX},%
 	pdfborder={0 0 0},%
@@ -59,7 +63,7 @@ gradientframe.sty.
 \usepackage{tabularx}
 \usepackage{listings}
 \definecolor{lightgray}{gray}{.95}
-\lstset{
+\lstset{%
 	frame=trbl,%
 	framerule=0pt,%
 	basicstyle=\footnotesize\ttfamily,%
@@ -82,9 +86,9 @@ gradientframe.sty.
 
 %\CodelineIndex
 %\EnableCrossrefs
-\RecordChanges
-\OnlyDescription
-\setcounter{IndexColumns}{2}
+%\RecordChanges
+%\OnlyDescription
+%\setcounter{IndexColumns}{2}
 \GetFileInfo{\jobname.sty}
 
 \newcommand{\supdot}{%
@@ -103,11 +107,16 @@ gradientframe.sty.
 	\end{center}%
 }
 \newcommand{\face}{%
-	\fboxsep=5px
-	\scalebox{2}{\fbox{%
-		\Huge
-		$\ddot\smile$%
-	}}%
+	\begingroup
+		\setlength{\fboxsep}{5px}%
+		\scalebox{2}{\fbox{%
+			\Huge
+			$\ddot\smile$%
+		}}%
+	\endgroup
+}
+\newcommand{\command}[1]{%
+	\texttt{\textbackslash{}#1}%
 }
 
 \title{the \package{\jobname} package\thanks{This document corresponds to \package{\jobname}~\fileversion, dated \filedate.}\\[1em]}
@@ -122,8 +131,8 @@ gradientframe.sty.
 \addcontentsline{toc}{section}{\abstractname}
 \begin{abstract}
 \noindent
-The \package{\jobname} package provides a command, |\gradientframe|, for simple discreet grayscale gradient frames
-around objects, such as images or tables, to set them apart from the surrounding text.
+The \package{\jobname} package provides a command, \command{gradientframe}, for simple and discreet rectangular grayscale
+gradient frames around objects, such as figures or tables, to set them apart from the surrounding text.
 \end{abstract}
 
 
@@ -144,9 +153,18 @@ by the \package{gradientframe} package if not already done so far in the documen
 
 \section{Usage}
 \DescribeMacro\gradientframe
-To frame an object, such as figure, table, etc., use |\gradientframe{|\meta{object}|}|.
-By using |\gradientframe[|\meta{width}|]{|\meta{object}|}|, a space between the frame and the object (in all four
-directions) can be added.
+To frame an object, such as figure, table, etc., use the \command{gradientframe\marg{object}} command.
+By using \command{gradientframe\oarg{name=value,\ldots}\marg{object}}, the result can be influenced by providing the
+following options by name:
+\begin{itemize}
+	\item
+		\texttt{linewidth} (default value: \texttt{0.3px})\\
+		defines each color's line width
+	\item
+		\texttt{padding} (default value: \texttt{0mm})\\
+		defines space between the object and the frame (applies to all four sides)
+\end{itemize}
+Also take a look at the following examples.
 
 
 \section{Examples}
@@ -165,12 +183,24 @@ directions) can be added.
 \subsection{Frame surrounding a figure with additional space}
 \begin{lstlisting}
 	\begin{center}
-		\gradientframe[5mm]{\includegraphics{image.jpg}}
+		\gradientframe[padding=5mm]{\includegraphics{image.jpg}}
+	\end{center}
+\end{lstlisting}
+\resultarrow
+\begin{center}
+	\gradientframe[padding=5mm]{\face}
+\end{center}
+
+
+\subsection{Frame surrounding a figure with thicker frame lines and additional space}
+\begin{lstlisting}
+	\begin{center}
+		\gradientframe[linewidth=1px,padding=5mm]{\includegraphics{image.jpg}}
 	\end{center}
 \end{lstlisting}
 \resultarrow
 \begin{center}
-	\gradientframe[5mm]{\face}
+	\gradientframe[padding=5mm,linewidth=1px]{\face}
 \end{center}
 
 
@@ -215,7 +245,7 @@ this, as shown in lines 2 and 8. Otherwise the result will look like this:
 \clearpage
 \subsection{Frame surrounding a MetaPost figure}
 If you want to draw a frame around a MetaPost (or in the case of this example, MetaUML) generated figure, use the
-|\empuse| command.
+\command{empuse} command.
 \begin{lstlisting}
 	\begin{center}
 		\begin{empfile}
@@ -230,7 +260,7 @@ If you want to draw a frame around a MetaPost (or in the case of this example, M
 				drawObjects(start, end);
 				clink(transition)(start, end);
 			\end{empdef}
-			\gradientframe[5mm]{\empuse{unique_name}}
+			\gradientframe[padding=5mm]{\empuse{unique_name}}
 		\end{empfile}
 	\end{center}
 \end{lstlisting}
@@ -248,11 +278,27 @@ If you want to draw a frame around a MetaPost (or in the case of this example, M
 			drawObjects(start, end);
 			clink(transition)(start, end);
 		\end{empdef}
-		\gradientframe[5mm]{\empuse{unique_name}}
+		\gradientframe[padding=5mm]{\empuse{unique_name}}
 	\end{empfile}
 \end{center}
-Alternatively, you could outsource both, the |empdef| environment and the |\empuse| command to a separate file, and use
-|\input{|\meta{filename}|}| as argument to the |\gradientframe| command.
+Alternatively, you could outsource both, the \texttt{empdef} environment and the \command{empuse} command to a separate
+file, and use \command{input\marg{filename}} as argument to the \command{gradientframe} command.
+
+
+\section{Known issues}
+\DescribeMacro\pagecolor
+When using a page color different than white in combination with a (partially) transparent object, the transparent area
+inside the frame will be white. To avoid this, a \command{colorbox} has to be drawn around the object. So instead of
+\begin{quote}
+	\command{pagecolor\marg{color}}\\
+	\command{gradientframe\marg{object}}
+\end{quote}
+one should use
+\begin{quote}
+	\command{pagecolor\marg{color}}\\
+	\command{gradientframe\{\command{colorbox}\marg{color}\marg{object}\}}
+\end{quote}
+This issue will hopefully be addressed in a future version.
 
 
 \StopEventually{
@@ -275,9 +321,29 @@ Alternatively, you could outsource both, the |empdef| environment and the |\empu
 
 
 \clearpage
-\phantomsection
-\addcontentsline{toc}{section}{Change History}
-\PrintChanges
+%\phantomsection
+%\addcontentsline{toc}{section}{Change history}
+%\PrintChanges
+\section{Change history}
+
+\newlength{\notewidth}
+\settowidth{\notewidth}{Note: }
+\newcommand{\noteindent}{\hspace*{\notewidth}}
+\begin{tabularx}{\textwidth}{|l|l|X|}
+	\hline
+	v0.1	& 2011/02/10	&	Initial version.
+	\\\hline
+	v0.1a	& 2011/02/10	&	Changed file encoding to ISO-8859-1 due to issues on CTAN.
+	\\\hline
+	v0.2	& 2011/02/13	&	Applied several code improvements.\newline
+								Added key/value options for more flexibility.\newline
+								Note: This breaks backward compatibility, so change calls in the form\newline
+								\noteindent \command{gradientframe[\meta{width}]\marg{object}}\newline
+								\noteindent to\newline
+								\noteindent \command{gradientframe[padding=\meta{width}]\marg{object}}\newline
+								\noteindent in case of an update from previous versions.
+	\\\hline
+\end{tabularx}
 
 
 %\phantomsection
@@ -291,57 +357,94 @@ Alternatively, you could outsource both, the |empdef| environment and the |\empu
 %
 % \section{Implementation}
 %
-% \changes{v0.1}{2011/02/10}{Initial version.}
-% \changes{v0.1a}{2011/02/10}{Fixed charset encoding issues on CTAN.}
 %
+% \subsection{Package header}
 %	\begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
-\ProvidesPackage{gradientframe}[2011/02/10 v0.1a simple gradient frames around objects]
+\ProvidesPackage{gradientframe}[2011/02/13 v0.2 simple gradient frames around objects]
 \RequirePackage{color}
+\RequirePackage{keyval}
 %    \end{macrocode}%^^A must be exactly 4 spaces
 %
-% \begin{macro}{\gradientframe}
-% This command defines the grayscale gradient frame around objects, with variable space between object and frame.
+% \subsection{Options for the \command{gradientframe} command}
+% The \package{keyval} package is used to handle options given to the \command{gradientframe} command by name. These
+% options are:
+% \begin{itemize}
+%	\item \texttt{linewidth} -- defines each color's line width
+%	\begin{macrocode}
+\define@key{gradientframe}{linewidth}{%
+	\newdimen\gradientframe@linewidth%
+	\setlength{\gradientframe@linewidth}{#1}%
+}%
+%    \end{macrocode}%^^A must be exactly 4 spaces
+%
+%	\item \texttt{padding} -- defines space between the object and the innermost frame line
 %	\begin{macrocode}
-\newcommand{\gradientframe}[2][0mm]{%
-	% Grayscale colors.
-	\definecolor{gray98}{gray}{.98}%
-	\definecolor{gray96}{gray}{.96}%
-	\definecolor{gray94}{gray}{.94}%
-	\definecolor{gray92}{gray}{.92}%
-	\definecolor{gray90}{gray}{.90}%
-	\definecolor{gray88}{gray}{.88}%
-	\definecolor{gray86}{gray}{.86}%
-	\definecolor{gray84}{gray}{.84}%
-	\definecolor{gray82}{gray}{.82}%
-	\definecolor{gray80}{gray}{.80}%
-	\definecolor{gray78}{gray}{.78}%
-	\definecolor{gray76}{gray}{.76}%
-	\definecolor{gray74}{gray}{.74}%
-	\definecolor{gray72}{gray}{.72}%
-	\definecolor{gray70}{gray}{.70}%
+\define@key{gradientframe}{padding}{%
+	\newdimen\gradientframe@padding%
+	\setlength{\gradientframe@padding}{#1}%
+}%
+%    \end{macrocode}%^^A must be exactly 4 spaces
+% \end{itemize}
 %
-	% Each color's line width.
-	\newdimen\lineWidth%
-	\lineWidth=0.3px%
+%^^A \define@key{gradientframe}{outercolor}{}
+%^^A \define@key{gradientframe}{innercolor}{}
+%
+% \begin{macro}{\gradientframe@defaults}
+% The default values for these options are defined as follows:
+%	\begin{macrocode}
+\newcommand{\gradientframe@defaults}{%
+	\setkeys{gradientframe}{%
+		linewidth=0.3px,%
+		padding=0mm%
+	}%
+}%
+%    \end{macrocode}%^^A must be exactly 4 spaces
+% \end{macro}
 %
-	% Space between object and innermost frame line.
-	\newdimen\borderSpacing%
-	\borderSpacing=#1%
+% \subsection{Commands}
+% \begin{macro}{\gradientframe@origlinewidth}
+% This dimension is used internally to preserve the original line width defined by \command{fboxrule}.
+%	\begin{macrocode}
+\newdimen\gradientframe@origlinewidth%
+%    \end{macrocode}%^^A must be exactly 4 spaces
+% \end{macro}
 %
-	\fboxrule=\lineWidth%
-	\fboxsep=\lineWidth%
-	\fcolorbox{gray98}{gray96}{%
-		\fcolorbox{gray94}{gray92}{%
-			\fcolorbox{gray90}{gray88}{%
-				\fcolorbox{gray86}{gray84}{%
-					\fcolorbox{gray82}{gray80}{%
-						\fcolorbox{gray78}{gray76}{%
-							\fcolorbox{gray74}{gray72}{%
-								\fboxrule=\lineWidth%
-								\fboxsep=\borderSpacing%
-								\fcolorbox{gray70}{white}{%
-									#2%
+% \begin{macro}{\gradientframe@drawbox}
+% This command uses two colors, for border and background, and draws one frame line.
+%	\begin{macrocode}
+\newcommand{\gradientframe@drawbox}[3]{%
+	\fcolorbox[gray]{#1}{#2}{%
+		#3%
+	}%
+}%
+%    \end{macrocode}%^^A must be exactly 4 spaces
+% \end{macro}
+%
+% \begin{macro}{\gradientframe}
+% This command draws the grayscale gradient frame around objects. This is achieved by drawing multiple frame lines side
+% by side, each with a slightly different color.
+%	\begin{macrocode}
+\newcommand{\gradientframe}[2][]{%
+	\gradientframe@defaults% apply defaults
+	\setkeys{gradientframe}{#1}%
+%
+	\begingroup% limit redefinitions to this block
+		% backup original \fboxrule value
+		\setlength{\gradientframe@origlinewidth}{\fboxrule}%
+%
+		\setlength{\fboxrule}{\gradientframe@linewidth}%
+		\setlength{\fboxsep}{\gradientframe@linewidth}% space between frame and object
+		\gradientframe@drawbox{.98}{.96}{%
+			\gradientframe@drawbox{.94}{.92}{%
+				\gradientframe@drawbox{.90}{.88}{%
+					\gradientframe@drawbox{.86}{.84}{%
+						\gradientframe@drawbox{.82}{.80}{%
+							\gradientframe@drawbox{.78}{.76}{%
+								\gradientframe@drawbox{.74}{.72}{%
+									\setlength{\fboxrule}{\gradientframe@origlinewidth}% restore original \fboxrule value
+									\setlength{\fboxsep}{\gradientframe@padding}%
+									\gradientframe@drawbox{.70}{1}{#2}%
 								}%
 							}%
 						}%
@@ -349,7 +452,7 @@ Alternatively, you could outsource both, the |empdef| environment and the |\empu
 				}%
 			}%
 		}%
-	}%
+	\endgroup%
 }%
 %    \end{macrocode}%^^A must be exactly 4 spaces
 % \end{macro}