update sparklines 1.3 from ctan

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

4 files changed, 215 insertions, 52 deletions

diff --git a/Master/texmf-dist/doc/latex/sparklines/README b/Master/texmf-dist/doc/latex/sparklines/README
new file mode 100644
index 00000000000..37830cdc4d0
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/sparklines/README
@@ -0,0 +1,17 @@
+                        Sparkline.sty
+
+Sparklines are intense, simple, wordlike graphics (so named by Edward
+Tufte). In lieu of a more detailed introduction, Professor Tufte's site
+has an early release of a chapter on sparklines, see
+www.edwardtufte.com. A PHP implementation can be found at
+http://sparkline.sourceforge.net/.
+
+A sparkline can be added using the sparkline environment. Also, you can
+add sparkling rectangles for the median and special sparkling dots in
+red or blue. Only use sparklines with pdflatex, or with PostScript
+output; sparklines cannot appear in a dvi-file. The sparklines package
+uses pgf, and does not work with pictex. It but might work if
+pictexwd.sty is used, but that has not been tested.
+
+Read sparklines.pdf for more details including history.
+
diff --git a/Master/texmf-dist/doc/latex/sparklines/sparklines.pdf b/Master/texmf-dist/doc/latex/sparklines/sparklines.pdf
index e62084c7810..f0cacec5eea 100644
--- a/Master/texmf-dist/doc/latex/sparklines/sparklines.pdf
+++ b/Master/texmf-dist/doc/latex/sparklines/sparklines.pdf
diff --git a/Master/texmf-dist/doc/latex/sparklines/sparklines.tex b/Master/texmf-dist/doc/latex/sparklines/sparklines.tex
index a29aac04883..29f357960e1 100644
--- a/Master/texmf-dist/doc/latex/sparklines/sparklines.tex
+++ b/Master/texmf-dist/doc/latex/sparklines/sparklines.tex
@@ -1,58 +1,171 @@
 \documentclass{article}
+
 \usepackage{sparklines}
+
 \renewcommand{\baselinestretch}{1.25}
+\let\env=\texttt
+\let\pkg=\textsf
+
+\definecolor{sparkrectanglecolor}{rgb}{0.8,.95,0.8}
+\definecolor{sparkspikecolor}{rgb}{1,0,0}
+\setlength{\sparkdotwidth}{1.3pt}
+\setlength{\sparklinethickness}{.3pt}
 
 \begin{document}
+
 \title{Sparklines}
-\author{Andreas L\"{o}ffler}
-\date{21.~April 2005}\maketitle
+\author{Andreas Loeffler \and Dan Luecking}
+\date{updated 3.~April 2007}\maketitle
 
 \section{What are sparklines?}
 
- Sparklines are intense, simple, wordlike
-graphics (so named by Edward Tufte). In lieu of a more detailed introduction,
-Professor Tufte's site has an early release of a chapter on sparklines, see
+Sparklines are intense, simple, wordlike graphics (so named by Edward
+Tufte). In lieu of a more detailed introduction, Professor Tufte's site
+has an early release of a chapter on sparklines, see
 www.edwardtufte.com. A PHP implementation can be found at
 http://sparkline.sourceforge.net/.
 
+A sparkline can be added using the \env{sparkline}--environment.
+Also, you can add sparkling rectangles for the median and special
+sparkling dots in red or blue. Sparklines do not appear within a
+dvi-file, they require either pdflatex or conversion to postscript with
+dvips. The \textsf{sparklines} package requires the \pkg{pgf} package.
+This makes it incompatible with \pkg{pictex}: the combination both
+require too many dimension parameters. It is possible \pkg{sparklines}
+can be used with \pkg{pictexwd}; they can at least be loaded together
+without using too many dimensions, but no other test was conducted.
 
-A sparkline can be added using the \texttt{sparkline}--environment. Also, you
-can add sparkling rectangles for the median and special sparkling dots in red
-or blue. \textbf{Only use sparklines with pdflatex}, sparklines do not appear
-within a dvi-file. \texttt{Sparklines} does not work with \texttt{pictex}.
+If we want to add a sparkline, be careful not to leave an empty line
+between the text left of the sparkline and the environment itself,
+since otherwise the sparkline starts a new paragraph.
 
-If we want to add a sparkline, be careful not to leave an empty line between
-the text left from the sparkline and the environment itself (starting with the
-sparkline environment)
-% This now starts the sparkline of length 10 times the width of the letter x
+This is an example of sparkline:
 \begin{sparkline}{10}
 % This environment has now an own coordinate system. x and y run from 0 to 1.
-
-% This draws a sparkling-rectangle with lower level y=0.3 and upper level y=0.5
+%
+% This draws a sparkling-rectangle with lower level y=0.3 and upper
+% level y=0.5
 \sparkrectangle 0.3 0.5
-
+%
 % This draws a blue colored sparkling-dot at x=0.5, y=0.8
 \sparkdot 0.5 0.62 blue
-
+%
 % This draws a red colored sparkling-dot at x=1, y=0.2
 \sparkdot 1 0.2 red
-
-% draws a sparkline with ten values starting at x=0.1 and y=0.95, then x=0.2 and y=0.8 etc.
-% drawing finishes if / appears
- \spark 0.1 0.95 0.2 0.8 0.3 0.3 0.4 0.52 0.5 0.62 0.6 0.7 0.7 0.5 0.8 0.4 0.9 0.25 1 0.2 /
+%
+% This draws a sparkline with ten values starting at x=0.1 and
+% y=0.95, then x=0.2 and y=0.8 etc.  Drawing finishes if / appears
+\spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
+       0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
 \end{sparkline}
- Daimler Chrysler, 12\%, {\color{red} 129}, since otherwise the sparkline starts
- at a new line.
+Daimler Chrysler, 12\%, \textcolor{red}{129})
+%
+
+\section{Usage}
+
+The sparkline at the end of the previous section was created with the
+following:
+\begin{verbatim}
+  \begin{sparkline}{10}
+    \sparkrectangle 0.3 0.5
+    \sparkdot 0.5 0.62 blue
+    \sparkdot 1 0.2 red
+    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
+           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
+  \end{sparkline}
+\end{verbatim}
+
+The argument of the environment gives the width of the graphic as a
+multiple of the dimension unit \texttt{ex} (approximately the height of
+the lowercase `x' in the current font). Within the environment,
+$x$-coordinates run from 0 (extreme left of the graphic) to 1 (extreme
+right).
+
+The height of the graphic is given by the \emph{macro}
+\verb$\sparklineheight$, defined to produce \texttt{1.75} by default.
+The units are the same as for the width: the \texttt{ex} of the current
+font. You can redefine that macro (with \verb$\renewcommand$) to force
+another height. Within the graphic, the $y$-coordinate runs from 0
+(lowermost point) to 1 (uppermost).
+
+The \verb$\sparkrectangle$ command produces a background rectangle. It
+must be followed by two numbers, each followed by a space or the end of
+the line. They are the $y$-coordinates of the bottom and top of the
+rectangle. This is supposed to show the `normal range' of the $y$-data,
+so that a point outside that rectangle represents a departure from
+normal. The color of the rectangle is `\texttt{sparkrectanglecolor}',
+which the user may redefine (with
+\verb$\definecolor$). The initial definition is given by \\
+\indent\verb$\definecolor{sparkrectanglecolor}{gray}{0.9}$\\
+In the above example, it was first changed to a light green.
+
+The colored dots are produced by \verb$\sparkdot$, the diameter of the
+dot is the value of the length \verb$\sparkdotwidth$, which the user may
+change (with \verb$\setlength$). The default value is \texttt{1.2pt};
+the above example was created a value of \texttt{1.3pt}. The command
+takes three parameters, each of which must be followed by a space or the
+end of the line. The first two are the coordinates of the center of the
+dot, the third is the color.
+
+Each pair of numbers after the macro \verb$\spark$ represents a
+coordinate pair, giving the location of a point in the above described
+coordinate system. The macro draws a line from each point to the next.
+Each number must be followed by a space, and the list is terminated by a
+\texttt{/}. Be careful that there are an even number of coordinates. The
+thickness of the line that is created is the value of the length
+\verb$\sparklinethickness$, which the user may change (with
+\verb$\setlength$). The default value is \texttt{0.2pt}; the above
+example was created with the value \texttt{0.3pt}.
+
+Bar graphs can be drawn easily:
+\begin{sparkline}{5}
+\sparkspike .083 .18
+\sparkspike .25 .55
+\sparkspike .417 1
+\sparkspike .583 .62
+\sparkspike .75 .42
+\sparkspike .917 .5
+\end{sparkline}.
+This was created by the code:
+\begin{verbatim}
+  \begin{sparkline}{4}
+    \sparkspike .083 .18
+    \sparkspike .25 .55
+    \sparkspike .417 1
+    \sparkspike .583 .62
+    \sparkspike .75 .42
+    \sparkspike .917 .5
+  \end{sparkline}.
+\end{verbatim}
+The macro \verb$\sparkspike$ must be followed by a pair of numbers, each
+followed by a space or the end of the line. The first of the pair is the
+horizontal location of the bar and the second is the height. The bars
+are drawn in color `\texttt{sparkspikecolor}' which the user may
+redefine (with \verb$\definecolor$). The default is \texttt{black}; the
+above example was drawn with it changed to \texttt{red}. The width of
+each bar is the value of the length \verb$\sparkspikewidth$, which the
+user may change (with \verb$\setlength$). The default is \texttt{2pt}.
 
 \section*{Version history}
 \begin{description}
+\item[] Mar 21, 2007
+
+    version 1.3: User adjustable colors and parameters added by Dan
+    Luecking $\langle$luecking@uark.edu$\rangle$
+
+\item[] Mar 19, 2007
+
+    version 1.2: Sparkbars added thanks to Harlan Harris
+    $\langle$harlan@harris.name$\rangle$
+
 \item[] Apr 21, 2005
 
- version 1.1: bug removed thanks to Mathias Hofmann <mathias.hofmann@web.de>
+    version 1.1: bug removed thanks to Mathias Hofmann
+    $\langle$mathias.hofmann@web.de$\rangle$
 
 \item[] Dec 12, 2004
 
- version 1.0: first version of sparklines
+    version 1.0: first version of sparklines
 \end{description}
 
 \end{document}
diff --git a/Master/texmf-dist/tex/latex/sparklines/sparklines.sty b/Master/texmf-dist/tex/latex/sparklines/sparklines.sty
index 6a7307bd138..e81202b098c 100644
--- a/Master/texmf-dist/tex/latex/sparklines/sparklines.sty
+++ b/Master/texmf-dist/tex/latex/sparklines/sparklines.sty
@@ -1,4 +1,4 @@
-%%% sparklines.sty Version 1.0
+%%% sparklines.sty Version 1.3
 %%%
 %%% What Are Sparklines?
 %%% Sparklines are intense, simple, wordlike graphics (so named by Edward Tufte).
@@ -6,8 +6,6 @@
 %%% release of a chapter on sparklines, see www.edwardtufte.com. A PHP
 %%% implementation can be found at http://sparkline.sourceforge.net/.
 %%%
-%%% Notice that the package does NOT run with pictex!
-%%%
 %%% Copyright 2005 Andreas Loeffler
 %%% ========================================================================
 %%% LICENCE:
@@ -18,47 +16,82 @@
 %%% al@wacc.de
 %%%
 %%% MODIFICATION HISTORY:
+%%% Mar 21, 2007
+%%% version 1.3: Dan Luecking (luecking@uark.edu) added user-changeable
+%%% parameters, and expanded documentation
+%%% Mar 19, 2007
+%%% version 1.2: Harlan Harris (harlan@harris.name) added positive-value-only bars
 %%% Apr 21, 2005
 %%% version 1.1: bug removed thanks to Mathias Hofmann <mathias.hofmann@web.de>
 %%% Dec 12, 2004
 %%% version 1.0: first version of sparklines
 
-\RequirePackage{pgf} \ProvidesPackage{sparklines}
-      [2005/01/01 v1.0 Sparklines (see more on sparklines at www.EdwardTufte.com)]
+\ProvidesPackage{sparklines}
+    [2005/01/01 v1.3 Sparklines (see more on sparklines at www.EdwardTufte.com)]
+\RequirePackage{pgf}
+
+% We define the colors of two features: the background rectangle and
+% the spikes in a bar graph
+\definecolor{sparkrectanglecolor}{gray}{0.9}
+\definecolor{sparkspikecolor}{named}{black}
+
+% We define parameters for changing the sizes. These are
+%   \sparklinethickness -- thickness of the line drawn by \spark,
+%   \sparkdotwidth -- diameter of the dot drawn by \sparkdot,
+%   \sparkspikewidth -- width of bar drawn in \sparkspike,
+%   \sparklineheight -- macro, number of ex for the height of picture.
+% Defaults equal old hard-coded values.
+\newlength\sparklinethickness
+\newlength\sparkdotwidth
+\newlength\sparkspikewidth
+\setlength\sparklinethickness{0.2pt}
+\setlength\sparkdotwidth{1.2pt}
+\setlength\sparkspikewidth{2pt}
+\providecommand{\sparklineheight}{1.75}
 
 % defines sparkline environment
-\newenvironment{sparkline}[1]{\begin{pgfpicture}{0ex}{0ex}{#1 ex}{1.75ex}
- \pgfsetlinewidth{0.2pt} %line width of 0.2 pt
- \pgfsetxvec{\pgfpoint{#1 ex}{0pt}} % says that on unit on the x axes is #1 times the size of x
- \pgfsetyvec{\pgfpoint{0pt}{1.75ex}} % says that on unit on the y axes is 1.75 times the size of x
- } {\pgfstroke \end{pgfpicture} }
+% Replace hard coded line thickness and picture height with above
+% defined parameters.
+\newenvironment{sparkline}[1]{\pgfpicture{0ex}{0ex}{#1 ex}{\sparklineheight ex}
+  \pgfsetlinewidth{\sparklinethickness}
+  \pgfsetxvec{\pgfpoint{#1 ex}{0pt}}
+  \pgfsetyvec{\pgfpoint{0pt}{\sparklineheight ex}}
+} {\pgfstroke \endpgfpicture}
 
 % defines sparkdot with color
+% Replace hard-coded diameter with previously defined parameter.
 \def\sparkdot #1 #2 #3 {%
-    {\pgfmoveto{\pgforigin}\color{#3}\pgfcircle[fill]{\pgfxy(#1,#2)}{1.2pt}}%
+  {\pgfmoveto{\pgforigin}\color{#3}\pgfcircle[fill]{\pgfxy(#1,#2)}{\sparkdotwidth}}%
 }
 
-% definies sparkrectangle
+% defines sparkrectangle
+% Replace hard-coded rgb value with with previously defined color value.
 \def\sparkrectangle #1 #2 {%
-    {\pgfmoveto{\pgforigin}\color[rgb]{0.9,0.9,0.9} \pgfrect[fill]{\pgfxy(0, #1)}{\pgfxy(1, #2)}}}
-
-% taken from pictex
-\def\@shouldIstop#1#2{%
-  \def\first{#1}%
-  \def\second{#2}%
-  \futurelet\nextchar\@testnext}
-\def\@testnext{%
-    \ifx \nextchar /
-      \let\next=\first
-    \else
-      \let\next=\second
-    \fi
-  \next}
+  {\pgfmoveto{\pgforigin}\color{sparkrectanglecolor}
+   \pgfrect[fill]{\pgfxy(0, #1)}{\pgfxy(1, #2)}}}
 
 % defines sparkline-plot
+% Replace \@shouldIstop hack with equivalent \@ifnextchar code.
 \def\spark #1 #2 {%
   \pgfmoveto{\pgfxy(#1,#2)} %
   \@SPARK}
 \def\@SPARK#1 #2 {%
   \pgflineto{\pgfxy(#1,#2)} %
-  \@shouldIstop{\pgfstroke\ignorespaces}{\@SPARK}}
+  \@ifnextchar/{\pgfstroke\ignorespaces}{\@SPARK}}
+
+% defines sparkspike
+% Redefine \sparkspike with code that actually detects the color
+% change. The old version had black hard-coded, but even changing that
+% made no difference in the output. The combination of setting stroke
+% color and \pgfusepath{stroke} made it work. In place of hard-coded
+% width and are now previously defined parameters.
+\def\sparkspike #1 #2 {%
+  {%
+    \pgfmoveto{\pgforigin}%
+     \pgfsetlinewidth{\sparkspikewidth}%
+     \pgfsetstrokecolor{sparkspikecolor}%
+        \pgfmoveto{\pgfxy(#1, 0)}%
+        \pgflineto{\pgfxy(#1, #2)}
+     \pgfusepath{stroke}}%
+}
+\endinput