new latex package getfiledate (22jun09)

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

1 files changed, 320 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/getfiledate/getfiledate-guide.tex b/Master/texmf-dist/doc/latex/getfiledate/getfiledate-guide.tex
new file mode 100644
index 00000000000..19141cd4a87
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/getfiledate/getfiledate-guide.tex
@@ -0,0 +1,320 @@
+\documentclass[a4paper,11pt,final]{article}
+\usepackage[scaled=0.9]{helvet}
+\usepackage{getfiledate}
+\usepackage[left=3.5cm,right=3.5cm,top=3.5cm,bottom=3.5cm]{geometry}
+\usepackage{fancyvrb,shortvrb}
+\usepackage{array,longtable,colortbl}
+\usepackage{calc}
+\usepackage{multicol}
+\usepackage{parskip}
+\usepackage{xspace}
+\usepackage{fancyhdr}
+\usepackage{lastpage}
+\usepackage{hyperref}
+\usepackage{doipubmed}
+\definecolor{amagenta}{rgb}{0.50,0.00,0.50}
+\definecolor{adarkgreen}{rgb}{0.00,0.59,0.00}
+\definecolor{bmagenta}{rgb}{0.50,0.00,1.00}
+\hypersetup{colorlinks=true,linkcolor=red,pdfpagemode=UseThumbs,
+  implicit=true,breaklinks=true,citecolor=purple}
+\CustomVerbatimEnvironment{gfdverbatim}{Verbatim}{numbers=left,
+  numberblanklines=false,firstnumber=last,frame=single,
+  rulecolor=\color{orange},framerule=2pt,
+  framesep=2pt,fillcolor=\color{violet!55},formatcom=\color{bmagenta},
+  xrightmargin=0pc,commandchars=\|\(\),commentchar=\?}
+\newcommand*\tezt[1]{\textcolor{adarkgreen}{\texttt{#1}}}
+\newcommand*\temt[1]{\textcolor{teal}{\texttt{#1}}}
+\def\ie{i.e.\xspace}
+\newcounter{examplecnt}[section]
+\newcommand\example[1]{%
+  \refstepcounter{examplecnt}
+  \par\vspace*{.5\baselineskip}
+  \textcolor{purple}{\textbf{Example~\theexamplecnt}}
+  \par%
+}
+\date{\textcolor{purple}{June 10, 2009}\vadjust{\kern2ex\hrule}}
+\def\helv{\fontfamily{phv}\selectfont\color{amagenta}}
+\def\eg{e.g.\xspace}
+\def\ie{i.e.\xspace}
+\def\etc{etc.\xspace}
+\fancyhf{}
+\fancyhfoffset[R,L]{\marginparsep+\marginparwidth}
+\lhead{\helv The \texttt{\textcolor{blue}{getfiledate}} Package}
+\rhead{\helv Page~\thepage~of~\pageref*{LastPage}}
+\renewcommand\headrule{\color{blue}\hrule height1pt width\headwidth\relax
+  \vspace{2pt}\hrule height1pt width\headwidth\vspace{-2pt}}
+\renewcommand\footrule{\color{green}\hrule height1pt width\headwidth\relax
+  \vspace{2pt}\hrule height1pt width\headwidth\vspace{2pt}}
+\pagestyle{fancyplain}
+
+\begin{document}
+\MakeShortVerb{\+}
+\title{{\bfseries The \textcolor{blue}{\texttt{getfiledate}} Package}\\[1ex]
+Version 0.1}
+\author{Ahmed Musa\\[.5ex]University of Central Lancashire\\
+  Preston, UK\\[1ex]\url{a.musa@rocketmail.com}
+}
+\maketitle
+
+\columnseprule=0.5pt\premulticols=2cm
+\begin{multicols}{2}
+  \bgroup\small\tableofcontents\egroup
+\end{multicols}
+\bigskip
+
+\begin{center}
+\fboxsep3pt\fboxrule2.5pt
+\fcolorbox{red}{yellow}{\fcolorbox{bmagenta}{gray!15}{%
+\parbox{\hsize-4\fboxsep-4\fboxrule}{%
+\hfil\fcolorbox{cyan}{white}{\hspace{1cm}\textbf{Summary}\hspace{1cm}}\hfill\\[.5ex]
+The \tezt{getfiledate} package fetches from the system the date of last modification or opening of a resident file. It is based on an idea by Heiko Oberdiek \citeurl{oberdiek@uni-freiburg.de} that appeared in February 2009 on the discussion/newsgroup website \url{comp.text.tex}, namely, using the \tezt{\string\pdffilemoddate} command of pdf\TeX. My contribution has been to create a user-friendly interface for obtaining and presenting the needed filedate in several formats.
+}}}
+\end{center}
+
+\section{User interface}
+The package may be loaded without options as in
+\begin{gfdverbatim}
+\usepackage{getfiledate}
+\end{gfdverbatim}
+or with options as in
+\begin{gfdverbatim}
+\usepackage[option=value]{getfiledate}
+\end{gfdverbatim}
+The options include the filename for which you want to print the date of last modification. The options and their default values are described in section~\ref{PackageOptions}. It is advisable to first load the package by \tezt{\string\usepackage\{getfiledate\}} and then use the macro \tezt{\string\getfiledate} to dynamically determine and print the date of last modification of the filename. This macro sets the various options.
+
+\section{Package options\label{PackageOptions}}
+The package options are listed in Table~\ref{tab:Package-options} below.
+
+\begingroup
+\small
+\rowcolors{3}{yellow!20}{gray!25}
+\extrarowheight2pt
+\arrayrulecolor{purple}
+\begin{longtable}{m{3cm}m{3.5cm}m{\hsize-8cm}}
+\caption{Package options\label{tab:Package-options}}\\
+\rowcolor{green!55}
+\bfseries Option&\bfseries Default&\bfseries Meaning\\
+\endfirsthead
+\multicolumn{3}{|l|}{\emph{Continued from last page}}\\
+\bfseries Option&\bfseries Default&\bfseries Meaning\\
+\endhead
+\multicolumn{3}{|r|}{\emph{Continued on next page}}\\
+\endfoot
+\endlastfoot
++file+ & +getfiledate.sty+ & The file for which the date of last modification is required.\\
++prefix+ & The date of last modification of file & The prefix of filedate.\\
++width+ & +\hsize+ & The width of the parbox or boxedminipage containing the filedate.\\
++head+ & +0ex+ & The vertical separation between the paragraph before the filedate and the filedate itself. When this option is passed to package without value, its default becomes the +\baselineskip+.\\
++foot+ & +0ex+ & The vertical skip between the filedate's line and the paragraph after filedate. When this option is passed to package without value, its default becomes the +\baselineskip+.\\
++marker+ & +\blacktriangle-+ +right+ & The mark before the filedate, on the same line with the filedate.\\
++markercolor+ & +blue+ & The color of the marker.\\
++filenamecolor+ & +blue+ & The color of the filename.\\
++datecolor+ & +blue+ & The color of filedate.\\
++inlinespace+ & +1em+ & The horizontal separation between the marker and the filedate.\\
++separator+ & +\textbullet+ & The marker between the filedate and filetime.\\
++separatorcolor+ & +black+ & The color of the separator.\\
++framecolor+ & +black+ & The color of the boxrule for the boxedminipage.\\
++framesep+ & +3pt+ & The +\fboxsep+ for the boxedminipage.\\
++framerule+ & +0.4pt+ & The +\fboxrule+ for the boxedminipage.\\
++align+ & +justified+ & Alignment of the boxedminipage (possible values are \tezt{center}, \tezt{left}, \tezt{right} and \tezt{justified}).\\
+\end{longtable}
+\endgroup
+
+\section{Examples}
+\example{}
+
+The simplest example is to use the \tezt{\string\getfiledate} macro in the following way:
+\begin{gfdverbatim}
+\getfiledate{file={dir/filename.ext}}
+\end{gfdverbatim}
+for which the default values of the package options will be used. For the sample file \temt{test1.tex}, the outcome of this will be:
+
+\getfiledate{file={test1.tex}}
+
+\bigskip
+You can, however, use package options to customize the format of the result. The following examples illustrate the most important issues in using this package.
+
+\example{}
+%\section{Example}
+The example in this section was obtained with the following settings. There are values specified for \tezt{head} and \tezt{foot}.
+\begin{gfdverbatim}
+\getfiledate{file={test1.tex},head=.1\baselineskip,
+  foot=2\baselineskip,markercolor=magenta,filenamecolor=brown,
+  datecolor=orange,inlinespace=.5em,marker=$\blacktriangleright$,
+  separator
+}
+\end{gfdverbatim}
+
+The outcome of this is:
+\getfiledate{file={test1.tex},head=.1\baselineskip,
+  foot=2\baselineskip,
+  markercolor=magenta,filenamecolor=brown,datecolor=orange,
+  inlinespace=.5em,marker=$\blacktriangleright$,separator
+}
+
+If you don't need the \tezt{marker}, you can set \tezt{marker=\{\}} as follows
+\begin{gfdverbatim}
+\getfiledate{file={test1.tex},head=\baselineskip,
+  foot=\baselineskip,width=.6\hsize,filenamecolor=brown,
+  prefix=The date of final changes to file,
+  datecolor=orange,inlinespace=.5em,boxed=false,
+  separator=$\spadesuit$,separatorcolor=green,
+  |color(red)marker={}|color(bmagenta),align=center
+}
+\end{gfdverbatim}
+to get:
+\getfiledate{file={test1.tex},head=\baselineskip,
+  foot=\baselineskip,width=.6\hsize,
+  prefix=The date of final changes to file,
+  marker={},filenamecolor=brown,datecolor=orange,
+  inlinespace=.5em,align=center,boxed=false,
+  separator=$\spadesuit$,separatorcolor=green
+}
+If you simply remove \tezt{marker} from the key-value list, the \tezt{marker} will retain the last value you set for it rather than the default value (which is nil). 
+
+The user should note:
+
+\begin{itemize}
+\item The inclusion of the \tezt{width} (\tezt{=0.6\string\hsize}) in the above example. The \tezt{width} will maintain this value until it is changed again, as in the following example.
+
+\item The change of \tezt{prefix} here. The default value of \tezt{prefix} is \tezt{The date of last modification of file}. The \tezt{prefix} will maintain this value until it is changed in the next call (see the next example).
+
+\item The use of the key-value \tezt{align=center} above. The key \tezt{align} can assume values of \tezt{center}, \tezt{left}, \tezt{right}, and \tezt{justified}. Any other value for \tezt{align} will be rejected by the package.
+\end{itemize}
+
+\example{}
+%\section{Example}
+The example in this section was obtained with the following settings:
+\begin{gfdverbatim}
+\colorlet{redgreen}{red!55!green!65}
+
+\getfiledate{file={test2.tex},head=0ex,foot=\baselineskip,
+  prefix,width=\hsize,markercolor=magenta,filenamecolor=red,
+  datecolor=violet,inlinespace=.5em,marker=$\triangleright$,
+  separator=$\clubsuit$,separatorcolor=redgreen
+}
+\end{gfdverbatim}
+
+The outcome is:
+\getfiledate{file={test2.tex},head=0ex,
+  foot=1ex,width=\hsize,prefix,
+  markercolor=magenta,filenamecolor=red,datecolor=violet,
+  inlinespace=.5em,marker=$\triangleright$,
+  separator=$\clubsuit$,separatorcolor=red!55!green!65
+}
+Here we simply passed the \tezt{prefix} without value so that its default value was used.
+
+\example{}
+%\section{Example}
+The example in this section was obtained with the following settings:
+\begin{gfdverbatim}
+\getfiledate{file={test3.tex},head=\baselineskip,
+  foot=2\baselineskip,markercolor=red!65,filenamecolor=blue,
+  datecolor=orange,inlinespace=.5em,marker={$\star$},
+  separator=$\Diamond$,separatorcolor=red
+}
+\end{gfdverbatim}
+
+The outcome is:
+\getfiledate{file={test3.tex},head=\baselineskip,
+  foot=\baselineskip,markercolor=red!65,filenamecolor=blue,
+  datecolor=orange,inlinespace=.5em,marker={$\star$},
+  separator=$\Diamond$,separatorcolor=red
+}
+
+\example{}
+The example in this section was obtained with the following settings:
+\begin{gfdverbatim}
+\getfiledate{file={test4.tex},head=\baselineskip,foot=2ex,
+  markercolor=cyan,filenamecolor=blue,datecolor=orange,
+  inlinespace=.5em,marker={$\blacktriangleright$},
+  markercolor=cyan,separator=$\heartsuit$,separatorcolor
+}|color(black) % Use default separatorcolor
+\end{gfdverbatim}
+
+The outcome is:
+\getfiledate{file={test4.tex},head=\baselineskip,foot=2ex,
+  markercolor=cyan,filenamecolor=blue,datecolor=orange,
+  inlinespace=.5em,marker={$\blacktriangleright$},
+  markercolor=cyan,separator=$\heartsuit$,separatorcolor
+}
+
+\example{}
+%\section{Example}
+The example in this section was obtained with the following settings:
+\begin{gfdverbatim}
+\getfiledate{file={test5.tex},head=1ex,foot=1ex,
+  markercolor=purple,filenamecolor=blue,
+  datecolor=orange,inlinespace=.5em,
+  marker={$\blacktriangleright$},separator={}
+}|color(black) % The separator is nil here.
+\end{gfdverbatim}
+
+The outcome of this is:
+\getfiledate{file={test5.tex},head=1ex,foot=1ex,
+  markercolor=purple,filenamecolor=blue,datecolor=orange,
+  inlinespace=.5em,marker={$\blacktriangleright$},
+  separator={}
+}
+
+\example{}
+%\section{Example}
+Instead of keeping \tezt{head} and \tezt{foot}, you may instead decide to frame your result, as follows:
+\begin{gfdverbatim}
+\getfiledate{file={test5.tex},head=.5\baselineskip,
+  foot=.5\baselineskip,width=12.5cm,framesep=5pt,framerule=.4pt,
+  align=center,markercolor=purple,filenamecolor=blue,
+  datecolor=orange,marker={$\blacktriangleright$},
+  separator=$\heartsuit$,boxed
+}|color(black) % marker has no effect here.
+\end{gfdverbatim}
+
+The outcome is:
+\getfiledate{file={test5.tex},head=.5\baselineskip,foot=.5\baselineskip,
+  width=12.5cm,framesep=3pt,framerule=.4pt,align=center,
+  markercolor=purple,filenamecolor=blue,datecolor=orange,
+  marker={$\blacktriangleright$},separator=$\heartsuit$,
+  boxed
+}
+
+The boolean option \tezt{boxed} has the default value of \tezt{true} when listed in the key-value list. If you set the key \tezt{boxed(=true)} in one call to the \tezt{\string\getfiledate} macro, and you don't want the filedate to be boxed subsequently, you have to turn it off (\ie, enter \tezt{boxed=false}) in the next call to \tezt{\string\getfiledate}. The choice \tezt{boxed(=true)} automatically turns off \tezt{marker} irrespective of whether or not you have submitted  a value to this key in \tezt{\string\getfiledate} macro. In the above example, the reader will notice that the setting \tezt{marker=\string\blacktriangleright} has no effect on the outcome.
+
+For the boxed filedates, you can set the options \tezt{framesep} and \tezt{framerule} (equivalents of \LaTeX's native \temt{\string\fboxsep} and \temt{\string\fboxrule}) as follows:
+\begin{gfdverbatim}
+\getfiledate{file={test5.tex},head=\baselineskip,
+  foot=1ex,marker={$\blacktriangleright$},markercolor=purple,
+  filenamecolor=blue,width=.9\hsize,datecolor=orange,
+  inlinespace=.5em,align=left,boxed,separator=$\blacklozenge$,
+  |color(red)framesep=5pt,framerule=2pt|color(bmagenta)
+} |color(black) % marker has no effect here.
+\end{gfdverbatim}
+
+The outcome of this is:
+\getfiledate{file={test5.tex},head=\baselineskip,foot=1ex,
+  markercolor=purple,filenamecolor=blue,datecolor=orange,
+  inlinespace=.5em,marker={$\blacktriangleright$},width=.9\hsize,
+  align=left,boxed,framesep=5pt,framerule=2pt,separator=$\blacklozenge$
+}
+
+The default values of \tezt{framesep} and \tezt{framerule} are 3pt and 0.4pt (\LaTeX's native values for \temt{\string\fboxsep} and \temt{\string\fboxrule}). The user should note that the keys \tezt{framesep} and \tezt{framerule} should, of course, be submitted without backslashes (\eg, \tezt{framesep=5pt} and \tezt{framerule=2pt}).
+
+You can change the box color as in
+\begin{gfdverbatim}
+\getfiledate{file={test5.tex},head=\baselineskip,
+  foot=\baselineskip,markercolor=purple,filenamecolor=blue,
+  datecolor=orange,width=8cm,align=right,boxed,framesep=5pt,
+  framerule=2pt,separator=$\Diamond$,|color(red)framecolor=green|color(bmagenta)
+}
+\end{gfdverbatim}
+
+The outcome of this is:
+\getfiledate{file={test5.tex},head=\baselineskip,foot=\baselineskip,
+  markercolor=purple,filenamecolor=blue,datecolor=orange,width=8cm,
+  inlinespace=.5em,marker={$\blacktriangleright$},align=right,
+  boxed,framesep=5pt,framerule=2pt,separator=$\Diamond$,
+  framecolor=green
+}
+
+This box color will remain in force until it is changed again. The default value of \tezt{framecolor} is \tezt{black}.
+
+\end{document} 
\ No newline at end of file