path: root/macros/latex/contrib/getfiledate/getfiledate-guide.tex

%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
% This is file getfiledate-guide.tex, the documentation for the getfiledate      %
% package.                                                                       %
%                                                                                %
% (c) Ahmed Musa 2009                                                            %
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++%
\documentclass[a4paper,11pt,final]{article}
\usepackage[scaled=0.9]{helvet}
\usepackage{mathpazo}
\usepackage{getfiledate}
\usepackage[left=3.5cm,right=3.5cm,top=3.5cm,bottom=3.5cm]{geometry}
\usepackage{fancyvrb,shortvrb}
\usepackage{array,colortbl}
\usepackage{multicol}
\usepackage{parskip}
\usepackage{xspace}
\usepackage{fancyhdr}
\usepackage{lastpage}
\usepackage{ltablex}
\keepXColumns
\usepackage{hyperref}
\usepackage{doipubmed}
\new\let\TC\textcolor
\xglobal\definecolorset{rgb}{x}{0}{green1,0.00,0.59,0.00;%
  green2,0.84,0.84,0.00;blue1,0.50,0.00,1.00;magenta1,0.50,0.00,0.50;%
  magenta2,0.50,0.00,1.00}
\hypersetup{colorlinks=true,linkcolor=red,pdfpagemode=UseThumbs,
  implicit=true,breaklinks=true,citecolor=purple,pdfview=FitH,
  pdfstartview=FitH}
\CustomVerbatimEnvironment{gfdverbatim}{Verbatim}{numbers=left,
  numberblanklines=false,firstnumber=last,frame=single,
  rulecolor=\color{orange},framerule=2pt,
  framesep=2pt,fillcolor=\color{violet!55},formatcom=\color{xmagenta20},
  xrightmargin=0pc,commandchars=\|\(\),commentchar=\?}
\new\def\stya#1{\TC{xgreen10}{\texttt{#1}}}
\new\def\styb#1{\TC{teal}{\texttt{#1}}}
\new\def\cmda#1{\stya{\string#1}}
\new\def\cmdb#1{\styb{\string#1}}
\new\def\cmdc#1{\stya{#1\string\hsize}}
\newcommand*\email[1]{\href{mailto:#1}{#1}}
\def\ie{i.e.\xspace}
\newcounter{examplecnt}[section]
\new\def\gfdexample{%
  \refstepcounter{examplecnt}
  \endgraf\vspace*{.5\baselineskip}%
  \TC{purple}{\textbf{Example~\thesection.\theexamplecnt}}%
  \endgraf\nobreak
}
\date{\TC{purple}{\today}\vadjust{\kern2ex\hrule}}
\new\def\helv{\fontfamily{phv}\selectfont\color{xmagenta10}}
\def\eg{e.g.\xspace}
\def\ie{i.e.\xspace}
\def\etc{etc.\xspace}
\fancyhf{}
\fancyhfoffset[R,L]{\dimexpr\marginparsep+\marginparwidth}
\lhead{\helv The \texttt{\TC{blue}{getfiledate}} Package}
\rhead{\helv Page~\thepage~of~\pageref*{LastPage}}
\renew\def\headrule{\color{blue}\hrule height1pt width\headwidth\relax
  \vspace{2pt}\hrule height1pt width\headwidth\vspace{-2pt}}
\renew\def\footrule{\color{green}\hrule height1pt width\headwidth\relax
  \vspace{2pt}\hrule height1pt width\headwidth\vspace{2pt}}
\pagestyle{fancyplain}

\begin{document}
\MakeShortVerb{\+}
\title{{\bfseries The \TC{blue}{\texttt{getfiledate}} Package}\\[1ex]
Version 1.2}
\author{Ahmed Musa\\[.5ex]University of Central Lancashire\\
  Preston, United Kingdom\\[1ex]\email{a.musa@rocketmail.com}
}
\maketitle

\columnseprule=0.5pt\premulticols=2cm
\begin{multicols}{2}
  \small\tableofcontents\normalsize
\end{multicols}
\bigskip

\begin{center}
\fboxsep3pt\fboxrule2.5pt
\fcolorbox{red}{yellow}{\fcolorbox{xmagenta20}{gray!15}{%
\parbox{\dimexpr\hsize-4\fboxsep-4\fboxrule}{%
\hfil\fcolorbox{cyan}{white}{\hspace{1cm}\textbf{Summary}\hspace{1cm}}\hfill\\[.5ex]
The \stya{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 \cmda{\pdffilemoddate} command of pdf\TeX. This package creates 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{sec:PackageOptions}. It is advisable to first load the package by \cmda{\usepackage\{getfiledate\}} and then use the macro \cmda{\getfiledate} to dynamically determine and print the date of last modification of filenames. The \cmda{\getfiledate} macro sets the various options. The \cmdb{\documentclass} and \cmda{\usepackage\{getfiledate\}} options lists may, however, be used to set options that apply throughout the document.

\section{Package options\label{sec:PackageOptions}}
The package options are listed in Table~\ref{tab:Package-options} below.

\begingroup
\small
\rowcolors{3}{yellow!20}{gray!25}
\extrarowheight2pt
\begin{tabularx}{\linewidth}{m{3cm}m{3.5cm}X}
\caption{Package options\label{tab:Package-options}}\\
\rowcolor{green!55}
\bf Option & \bf Default & \bf Meaning\\
\endfirsthead
\multicolumn{3}{l}{\emph{Continued from last page}}\\
\bf Option & \bf Default & \bf 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 filename.\\
+postfix+ & +was+ & The postfix of filename, not that of filedate. It has been necessary to provide  both prefix and postfix following user requests.\\
+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+ & +\empty+ & The mark before the filename, 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.\\
+sepcolor+ & +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 \stya{center}, \stya{left}, \stya{right} and \stya{justified}).\\
+putprefix+ & +true+ & The boolean switch for placing prefix and postfix before the filedate. If this option is not entered in the call to \cmda{\getfiledate}, or if it is entered as \stya{putprefix=true}, both prefix and postfix will be inserted. On the other hand, if the user sets \stya{putprefix=false}, then no prefix and postfix will be inserted (even if the user specifies prefix and postfix in the call to \cmda{\getfiledate}). This option has been necessitated by users who just want to get filedate without any prefix, postfix or filename.\\
+notime+ & +false+ & The boolean switch for turning the display of time on or off.\\
+boxed+ & +false+ & The boolean switch for enclosing the filedate in a box. If the user simply enters this option without value, it will be assumed to be +true+. If it doesn't appear in the options list, its value is +false+.
\end{tabularx}
\endgroup

\section{Examples}
\gfdexample

The simplest example is to use the \cmda{\getfiledate} macro in the following way:
\begin{gfdverbatim}
\getfiledate[putprefix]{dir/filename.ext}
\end{gfdverbatim}
for which the default values of the package options will be used. For the sample file \styb{misc-test1.tex}, the outcome of this will be:

\small
\getfiledate{misc-test1.tex}
\normalsize

\bigskip
The prefix and postfix can be turned off as follows:

\begin{gfdverbatim}
\getfiledate[putprefix=false]{dir/filename.ext}
\end{gfdverbatim}

which gives

\small
\getfiledate[putprefix=false]{misc-test1.tex}
\normalsize

\bigskip
If the user needs the prefix and postfix in subsequent calls to \cmda{\getfiledate}, he has to turn them on again---through \stya{putprefix} as follows. Once turned on, they remain in effect until switched off later.

The setting
\begin{gfdverbatim}
\getfiledate[putprefix,marker={$\star$}]{dir/filename.ext}
\end{gfdverbatim}

gives

\small
\getfiledate[putprefix,marker={$\star$}]{misc-test1.tex}
\normalsize

\bigskip
The ability to change both the prefix and postfix automatically provides a +babel+ (\ie, multilingual) support. For example, if I want the postfix to be \cmdb{\mrule}, I can simply enter

\begin{gfdverbatim}
\new\def\mrule{\rule[.2ex]{.5cm}{3pt}}
\getfiledate[putprefix,marker={$\star$},
  postfix=\mrule]{dir/filename.ext}
\end{gfdverbatim}

to get

\new\def\mrule{\rule[.2ex]{.5cm}{3pt}}
\small
\getfiledate[putprefix,marker={$\star$},postfix=\mrule]{misc-test1.tex}
\normalsize

\bigskip
You can use all package options to customize the format of the result. The following examples illustrate the most important issues in using this package.

\gfdexample
The example in this section was obtained with the following settings. There are values specified for \stya{head} and \stya{foot}.
\begin{gfdverbatim}
\getfiledate[putprefix,postfix,head=.1\baselineskip,
  foot=2\baselineskip,markercolor=magenta,
  filenamecolor=purple,datecolor=orange,
  inlinespace=.5em,marker=$\blacktriangleright$,separator
]{misc-test1.tex}
\end{gfdverbatim}

The outcome of this is
\small
\getfiledate[putprefix,postfix,
  head=.1\baselineskip,foot=2\baselineskip,
  markercolor=magenta,filenamecolor=purple,datecolor=orange,
  inlinespace=.5em,marker=$\blacktriangleright$,separator
]{misc-test1.tex}
\normalsize

If you don't need the \stya{marker}, you can simply enter \stya{marker} without value as follows

\begin{gfdverbatim}
\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,filenamecolor=xgreen10,
  prefix=The date of final changes to file,
  datecolor=orange,inlinespace=.5em,boxed=false,
  separator=$\spadesuit$,sepcolor=green,|color(red)marker|color(xmagenta20),align=center
]{misc-test1.tex}
\end{gfdverbatim}

to get

\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,
  prefix=The date of final changes to file,
  marker,filenamecolor=xgreen10,datecolor=orange,
  inlinespace=1em,align=center,boxed=false,
  separator=$\spadesuit$,sepcolor=green
]{misc-test1.tex}

If you simply remove \stya{marker} from the key-value list, the \stya{marker} will retain the last value you assigned to it rather than the default value (which is nil).

\gfdexample

Unlike the case of the \stya{marker}, if you don't need the \stya{separator}, you would have to enter \stya{separator=\{\}} or simply \stya{separator=} as follows

\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=\baselineskip,
  width=.6\hsize,filenamecolor=xgreen10,
  prefix=The date of final changes to file,
  datecolor=orange,inlinespace=.5em,boxed=false,
  |color(red)separator=,|color(xmagenta20)sepcolor=green,marker,align=center
]{misc-test1.tex}
\end{gfdverbatim}

to get

\getfiledate[head=\baselineskip,
  foot=\baselineskip,width=.6\hsize,
  prefix=The date of final changes to file,
  marker,filenamecolor=xgreen10,datecolor=orange,
  inlinespace=2em,align=center,boxed=false,
  separator=,sepcolor=green
]{misc-test1.tex}

The same trick can be applied to some other keys. If you simply remove the \stya{separator} from the key-value list, the \stya{separator} will retain the last value you assigned to it rather than the default value (which is \cmda{\textbullet}). If in the subsequent calls to \cmda{\getfiledate}, you need the \stya{separator}, you would have to specify it or (to use the default value) simply enter \stya{separator} without value.

\textbf{Notes}: The user should note the following:
\begin{itemize}
\item The inclusion of the \stya{width} (\cmdc{0.6}) in the above example. The \stya{width} will maintain this value until it is changed again, as in the following examples.

\item If you enter \stya{putprefix=false} and you want the outcome centered, you should remember to set the right \stya{width}. For example, the following will not be centered, simply because the value of \stya{width} is \cmdc{0.8}:

    \begin{gfdverbatim}
    \getfiledate[putprefix=false,align=center,
      width=0.8\hsize,separator]{dir/filename.ext}
    \end{gfdverbatim}

    which gives

    \getfiledate[putprefix=false,align=center,width=0.8\hsize,separator]{misc-test1.tex}

    Setting \cmdc{width=.3} gives the desired result:

    \getfiledate[putprefix=false,align=center,width=0.3\hsize,separator]{misc-test1.tex}

\item The assignment to keys can be localized by enclosing the \cmda{\getfiledate} command in a group (\eg, \cmdb{\bgroup} ... \cmdb{\egroup}).

\item The change of \stya{prefix} here. The default value of \stya{prefix} is \stya{The date of last modification of file}. The \stya{prefix} will maintain this value until it is changed in the next call (see the next example).
\item The ability to change the \stya{prefix} and \stya{postfix} provides a babel (\ie, multilingual) support, since the user can specify suitable values of these keys.

\item The use of the key-value \stya{align=center} above. The key \stya{align} can assume values of \stya{center}, \stya{left}, \stya{right}, and \stya{justified}. Any other value for \stya{align} will be rejected by the package.
\item Some of the package options (\eg, \stya{putprefix}, \stya{notime}) can be submitted globally via the options list of \cmdb{\documentclass}.
\end{itemize}

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=0ex,foot=\baselineskip,
  prefix,width=\hsize,markercolor=magenta,filenamecolor=red,
  datecolor=violet,inlinespace=.5em,marker=$\triangleright$,
  separator=$\clubsuit$,sepcolor=xbgreen1
]{misc-test2.tex}
\end{gfdverbatim}

The outcome is:
\getfiledate[head=0ex,
  foot=1ex,width=\hsize,prefix,
  markercolor=magenta,filenamecolor=red,datecolor=violet,
  inlinespace=.5em,marker=$\triangleright$,
  separator=$\clubsuit$,sepcolor=red!55!green!65
]{misc-test2.tex}
Here we simply passed the \stya{prefix} without value so that its default value was used.

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=\baselineskip,
  markercolor=red!65,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,marker={$\star$},
  separator=$\Diamond$,sepcolor=red
]{misc-test3.tex}
\end{gfdverbatim}

The outcome is:
\getfiledate[head=\baselineskip,
  foot=\baselineskip,markercolor=red!65,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,marker={$\star$},
  separator=$\Diamond$,sepcolor=red
]{misc-test3.tex}

\gfdexample

The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=\baselineskip,foot=2ex,
  filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  markercolor=cyan,separator=$\heartsuit$,sepcolor
]{misc-test4.tex}|color(black) % Use default sepcolor
\end{gfdverbatim}

The outcome is:
\getfiledate[head=\baselineskip,foot=2ex,
  markercolor=cyan,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  separator=$\heartsuit$,sepcolor
]{misc-test4.tex}

\gfdexample
The example in this section was obtained with the following settings:
\begin{gfdverbatim}
\getfiledate[head=1ex,foot=1ex,
  markercolor=purple,filenamecolor=blue,
  datecolor=orange,inlinespace=.5em,
  marker={$\blacktriangleright$},separator={}
]{misc-test5.tex}|color(black) % The separator is nil here.
\end{gfdverbatim}

The outcome of this is:
\getfiledate[head=1ex,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},
  separator={}
]{misc-test5.tex}

\gfdexample
Instead of keeping \stya{head} and \stya{foot}, you may instead decide to frame your result, as follows:
\begin{gfdverbatim}
\getfiledate[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
]{misc-test5.tex}|color(black) % marker has no effect here.
\end{gfdverbatim}

The outcome is:
\getfiledate[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
]{misc-test5.tex}

The boolean option \stya{boxed} has the default value of \stya{true} when listed in the key-value list. If you set the key \stya{boxed(=true)} in one call to the \cmda{\getfiledate} macro, and you don't want the filedate to be boxed subsequently, you have to turn it off (\ie, enter \stya{boxed=false}) in the next call to \cmda{\getfiledate}. The choice \stya{boxed(=true)} automatically turns off \stya{marker} irrespective of whether or not you have submitted  a value to this key in \cmda{\getfiledate} macro. In the above example, the reader will notice that the setting \stya{marker=\string\blacktriangleright} has no effect on the outcome.

For the boxed filedates, you can set the options \stya{framesep} and \stya{framerule} (equivalents of \LaTeX's native \cmdb{\fboxsep} and \cmdb{\fboxrule}) as follows:
\begin{gfdverbatim}
\getfiledate[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(xmagenta20)
]{misc-test5.tex} |color(black) % marker has no effect here.
\end{gfdverbatim}

The outcome of this is:
\getfiledate[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$
]{misc-test5.tex}

The default values of \stya{framesep} and \stya{framerule} are 3pt and 0.4pt (\LaTeX's native values for \cmdb{\fboxsep} and \cmdb{\fboxrule}). The user should note that the keys \stya{framesep} and \stya{framerule} should, of course, be submitted without backslashes (\eg, \stya{framesep=5pt} and \stya{framerule=2pt}).

You can change the box frame color as in
\begin{gfdverbatim}
\getfiledate[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(xmagenta20)
]{misc-test5.tex}
\end{gfdverbatim}

The outcome of this is:
\getfiledate[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
]{misc-test5.tex}

This frame color will remain in force until it is changed again. The default value of \stya{framecolor} is \stya{black}.

\gfdexample

The display of time can be avoided by using the switch \stya{notime}, as follows.
\begin{gfdverbatim}
\getfiledate[notime,head=\baselineskip,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},width=.8\hsize,
  align=center,boxed,framecolor=olive!25
]{misc-test5.tex}
\end{gfdverbatim}

The outcome of this is:
\getfiledate[notime,head=\baselineskip,foot=1ex,
  markercolor=purple,filenamecolor=blue,datecolor=orange,
  inlinespace=.5em,marker={$\blacktriangleright$},width=.8\hsize,
  align=center,boxed,framecolor=olive!25
]{misc-test5.tex}

Notice here that the immediate past values of \stya{framerule} and \stya{framesep} are still in effective.

\section{Postamble}
The record of filedates can be logged in a file (say, \cmdb{\jobname.fds}), but I haven't encountered a real need for it.

\end{document}