new latex package progressbar (11oct10)

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

3 files changed, 247 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/progressbar/README b/Master/texmf-dist/doc/latex/progressbar/README
new file mode 100644
index 00000000000..7015a16e9a6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/progressbar/README
@@ -0,0 +1,16 @@
+Description
+===========
+
+This package allows you to easily visualize shares of total amounts in the form of a bar. So basically you can convert any number between 0 and 1 to a progressbar using the command \progressbar{<number>}. Also a lot of customizations are possible, allowing you to create an unique progressbar on your own.
+
+License
+=======
+Copyright 2010 Marcel Jira
+
+This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3c of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt 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'.
+
+The Current Maintainer of this work is Marcel Jira.
+
+This work consists of the files progressbar.sty and progressbar.tex.
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/progressbar/progressbar.pdf b/Master/texmf-dist/doc/latex/progressbar/progressbar.pdf
new file mode 100644
index 00000000000..0e6cdaeada2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/progressbar/progressbar.pdf
diff --git a/Master/texmf-dist/doc/latex/progressbar/progressbar.tex b/Master/texmf-dist/doc/latex/progressbar/progressbar.tex
new file mode 100644
index 00000000000..0b7fa24b4aa
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/progressbar/progressbar.tex
@@ -0,0 +1,231 @@
+%% progressbar.tex
+%% Copyright 2010 Marcel Jira
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%   http://www.latex-project.org/lppl.txt
+% 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'.
+% 
+% The Current Maintainer of this work is Marcel Jira.
+%
+% This work consists of the files progressbar.sty and progressbar.tex.
+%
+\documentclass{ltxdoc}
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage[english]{babel}
+
+\usepackage{listings}
+\lstset{basicstyle=\ttfamily\small\mdseries,linewidth=\linewidth,breaklines=true,escapeinside={(*}{*)},}
+
+\usepackage{progressbar}
+
+\usepackage{hyperref}
+
+\title{\texttt{progressbar}}
+\author{by Marcel Jira}
+\date{2010/10/01}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+This package allows you to easily visualize shares of total amounts in the form of a bar. So basically you can convert a number like $0.735$ to \progressbar{0.735} using the command \lstinline+\progressbar{0.735}+.
+
+Of course also a lot of customizations are possible (like this: \progressbar[emptycolor=yellow,filledcolor=red,linecolor=blue,subdivisions=4,roundnessr=0.5,tickscolor=green,tickswidth=1,ticksheight=1]{0.735}).
+\end{abstract}
+
+\noindent\progressbar[width=\textwidth,heighta=3cm,filledcolor=red,emptycolor=green,borderwidth=5pt,tickswidth=2.5pt,roundnessr=0.5,subdivisions=20]{0.55}
+\begin{lstlisting}[basicstyle=\ttfamily\normalsize\mdseries]
+\progressbar[width=textwidth, heighta=3cm, filledcolor=red, emptycolor=green, borderwidth=5pt, tickswidth=2.5pt, roundnessr=0.5, subdivisions=20]{0.55}
+\end{lstlisting}
+
+\tableofcontents
+
+\section{Installation}
+Make sure the file \texttt{progressbar.sty} is placed somewhere, where \LaTeX can find it. Usually that means, you simply download the package \texttt{progressbar} with the \LaTeX-package-manager of your choice.
+
+\subsection{Dependencies}
+You also have to ensure that all packages needed by \texttt{progressbar} are present (some package-managers do this for you).
+The dependencies are:
+\begin{itemize}
+	\item calc
+	\item kvsetkeys
+	\item kvoptions
+	\item tikz
+\end{itemize}
+\section{How to use \texttt{progressbar}}
+\DescribeMacro{\usepackage\{progressbar\}}
+\DescribeMacro{\usepackage[]\{progressbar\}}
+Like any other package, to use \texttt{progressbar}, you have to load it first. You do this with
+\begin{lstlisting}
+\usepackage{progressbar}
+\end{lstlisting}
+or
+\begin{lstlisting}
+\usepackage[<options>]{progressbar}
+\end{lstlisting}
+(You can find an explanation of all options in the section \ref{options}.)
+
+Once you have loaded \texttt{progressbar}, you can use two different commands, described in the following.
+\subsection{\texttt{\textbackslash{}progressbar}}\label{commandprogressbar}
+\DescribeMacro{\progressbar\{\}}
+\DescribeMacro{\progressbar[]\{\}}
+The command
+\begin{lstlisting}
+\progressbar{<number>}
+\end{lstlisting}
+will draw you a progressbar with the share \texttt{<number>}. For example \lstinline+\progressbar{0.666}+ gives you this \progressbar{0.666}. You would want to use only numbers in the interval $[0,1]$, although other numbers are also possible (but will look just the same as \lstinline+\progressbar{0}+ or \lstinline+\progressbar{1}+).
+
+If you want one specific progressbar to look different than the others, use
+\begin{lstlisting}
+\progressbar[<options>]{<number>}
+\end{lstlisting}
+instead. This command is just the same as \lstinline+\progressbar{<number>}+ but allows you to manipulate the appearance of the current progressbar. So \lstinline+\progressbar[width=5cm,heightr=1,filledcolor=red,emptycolor=blue!30]{0.75}+ would look like this: \progressbar[width=5cm,heightr=1,filledcolor=red,emptycolor=blue!30]{0.75}. In this case the options are only changed locally. (You can find an explanation of all options in the section \ref{options}.)
+
+\subsection{\texttt{\textbackslash{}progressbarchange}}
+\DescribeMacro{\progressbarchange\{\}}
+In principle, the command \lstinline+\progressbar{<number>}+ uses the options specified with \lstinline+\usepackage[<options>]{progressbar}+ or the default options (if an option was not specified). As described in the previous section (\ref{commandprogressbar}), you can override these options with \lstinline+\progressbar[<options>]{<number>}+. However, if you want to change the settings for \emph{all} following progressbar, you can use the command
+\begin{lstlisting}
+\progressbarchange{<options>}
+\end{lstlisting}
+
+So basically
+\begin{lstlisting}
+\progressbar{0.3}\\
+\progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.4}\\
+\progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.5}\\
+\progressbar[roundnessr=0.5,ticksheight=1,tickswidth=1.5pt]{0.6}
+\end{lstlisting}
+gives you the same as
+\begin{lstlisting}
+\progressbar{0.3}\\
+\progressbarchange{roundnessr=0.5,ticksheight=1,tickswidth=1.5pt}
+\progressbar{0.4}\\
+\progressbar{0.5}\\
+\progressbar{0.6}
+\end{lstlisting}
+
+However, keep in mind that in the second case the options are changed globally. Therefore, all following progressbars will keep the changed design (as long as you don't call \lstinline+\progressbarchange{<options>}+ with other options again). (You can find an explanation of all options in the section \ref{options}.)
+
+\section{Options}\label{options}
+\subsection{Global and local options}
+You can set global options when you load the \texttt{progressbar} with \lstinline+\usepackage[options]{progressbar}+ and with the command \lstinline+\progressbarchange{<options>}+. These options affect all following calls of the commands \lstinline+\progressbar{<number>}+ and \lstinline+\progressbar[<options>]{<number>}+.
+
+However, you can override global options with local options specified with \lstinline+\progressbar[<options>]{<number>}+.
+
+\subsection{Options, their defaults and how to change them}
+All listed options can be used globally and locally.
+
+You will notice that some of the options are available with the prefix \texttt{r} (standing for relative) aswell as with the prefix \texttt{a} (standing for absolute). I would recommend you to always use those options with the prefix \texttt{r}, as using absolute values might not interact too well with the rest of your documents settings. But as long as you know what you are doing, it's up to you.
+
+\DescribeMacro{heightr} default=\texttt{1}\\
+	The progressbars height as a fraction of the textheight\footnote{I used the capital letter ``I'' as a reference for the textheight}.
+\begin{lstlisting}
+\progressbar[heightr=1]{0.1}A progressbar that has the same height as the text\\
+\progressbar[heightr=0.5]{0.9}A progressbar that has half the height
+\end{lstlisting}
+	\progressbar[heightr=1]{0.1} A progressbar that has the same height as the text\\
+	\progressbar[heightr=0.5]{0.9} A progressbar that has half the height
+
+\DescribeMacro{heighta} default=\texttt{unused}\\
+	With this option you can define the progressbars height absolutely.
+\begin{lstlisting}
+\progressbar[heighta=2cm]{0.3} A progressbar that has the height 2~cm\\
+\progressbar[heighta=10pt]{0.7} A progressbar that has the height 10~pt\\
+\progressbar[heighta=\heightof{a} + 0.8pt]{0.42} A progressbar whose upper border starts at the same height as the letter "a"
+\end{lstlisting}
+	\progressbar[heighta=2cm]{0.3} A progressbar that has the height 2~cm\\
+	\progressbar[heighta=10pt]{0.7} A progressbar that has the height 10~pt\\
+	\progressbar[heighta=\heightof{a} + 0.8pt]{0.42} A progressbar whose upper border starts at the same height as the letter "a"\footnote{The \texttt{\textbackslash{}heightof} command and the possibility of adding is provided by the package \texttt{calc}}
+
+\DescribeMacro{roundnessr} default=\texttt{0.15}\\
+	\texttt{progressbar} allows rounded corners. With this option you can set them as a fraction of the progressbars height. You would not want to use numbers higher than $0.5$.
+\begin{lstlisting}
+\progressbar[roundnessr=0.25]{0.8} More rounder corners than the default\\
+\progressbar[roundnessr=0.5]{0.5} In fact no more corners -- complete roundness
+\end{lstlisting}
+	\progressbar[roundnessr=0.25]{0.8} More rounder corners than the default\\
+	\progressbar[roundnessr=0.5]{0.5} In fact no more corners -- complete roundness
+
+\DescribeMacro{roundnessa} default=\texttt{unused}\\
+	You can also define the corners radius as absolute values.
+\begin{lstlisting}
+\progressbar[roundnessa=2pt]{0} Rounded corners radius 2~pt\\
+\progressbar[roundnessa=0cm]{1} No rounded corners
+\end{lstlisting}
+	\progressbar[roundnessa=2pt]{0} Rounded corners radius 2~pt\\
+	\progressbar[roundnessa=0cm]{1} No rounded corners
+
+\DescribeMacro{width} default=\texttt{6em}\\
+	The width of the progressbar.
+\begin{lstlisting}
+\progressbar[width=5cm]{0.123} Width: 5~cm\\
+\progressbar[width=20em]{0.785} Width: 20~em
+\end{lstlisting}
+	\progressbar[width=5cm]{0.123} Width: 5~cm\\
+	\progressbar[width=20em]{0.785} Width: 20~em
+
+\DescribeMacro{borderwidth} default=\texttt{0.8pt}\\
+	The linewidth of the progressbars border.
+\begin{lstlisting}
+\progressbar[borderwidth=2pt]{0.6} Borderwidth: 2~pt\\
+\progressbar[borderwidth=0.025em]{0.3} Borderwidth: 0.025~em
+\end{lstlisting}
+	\progressbar[borderwidth=2pt]{0.6} Borderwidth: 2~pt\\
+	\progressbar[borderwidth=0.025em]{0.3} Borderwidth: 0.025~em
+
+\DescribeMacro{subdivisions} default=\texttt{10}\\
+	As you may have noticed, (by default) the progressbar also has ticks. Those ticks splits the progressbar in multiple subdivisions. You can define the number of subdivisions with \texttt{subdivisions=<number>}. Therefore the number of ticks is $\texttt{<number>}-1$.
+\begin{lstlisting}
+\progressbar[subdivisions=3]{0.666667} 3 subdivisions and 2 ticks\\
+\progressbar[subdivisions=15]{0.466667} 15 subdivisions and 14 ticks
+\end{lstlisting}
+	\progressbar[subdivisions=3]{0.666667} 3 subdivisions and 2 ticks\\
+	\progressbar[subdivisions=15]{0.466667} 15 subdivisions and 14 ticks
+
+\DescribeMacro{tickswidth} default=\texttt{0.4pt}\\
+	The linewidth of the ticks.
+\begin{lstlisting}
+\progressbar[tickswidth=1mm]{0.55} Tickswidth: 1~mm\\
+\progressbar[tickswidth=0.1pt]{0.4} Tickswidth: 0.1~pt
+\end{lstlisting}
+	\progressbar[tickswidth=1mm]{0.55} Tickswidth: 1~mm\\
+	\progressbar[tickswidth=0.1pt]{0.4} Tickswidth: 0.1~pt
+
+\DescribeMacro{ticksheight} default=\texttt{0.33}\\
+	The height of the ticks as a fraction of the total progressbars height.
+\begin{lstlisting}
+\progressbar[ticksheight=0.1]{0.22} Ticksheight: 10 ~\% of the total height\\
+\progressbar[ticksheight=1]{0.88} Ticks are end-to-end
+\end{lstlisting}
+	\progressbar[ticksheight=0.1]{0.22} Ticksheight: 10 ~\% of the total height\\
+	\progressbar[ticksheight=1]{0.88} Ticks are end-to-end
+
+\DescribeMacro{linecolor} default=\texttt{black}
+
+\DescribeMacro{tickscolor} default=\texttt{black}
+
+\DescribeMacro{emptycolor} default=\texttt{black!10}
+
+\DescribeMacro{filledcolor} default=\texttt{black!60}\\
+These options should be self-explaining. Just use \texttt{xcolor}-color-definitions (use color names or the syntax \lstinline+<color-name>!<number between 0 and 100>+) for brighter colors).
+\begin{lstlisting}
+\progressbar[linecolor=blue,tickscolor=orange,emptycolor=yellow,filledcolor=red]{0.6}
+\end{lstlisting}
+	\progressbar[linecolor=blue,tickscolor=orange,emptycolor=yellow,filledcolor=red]{0.6}
+
+\section{Acknoledgment}
+A big shoutout to the pros from \url{http://www.mrunix.de/} (it's german). They helped me a lot and made \texttt{progressbar} possible.
+
+\section{Contact}
+If you have any question concerning \texttt{progressbar} or if you miss a feature, please write me a mail: \href{mailto:mails4me@gmx.at}{\texttt{mails4me@gmx.at}}.
+
+\end{document}
\ No newline at end of file