path: root/Master/texmf-dist/doc/latex/tdclock/tdclock-doc.tex

\documentclass{article}

\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{xkeyval}
\usepackage[font=Times,timeinterval=10,timeduration=2.0, timewarningfirst=50,timewarningsecond=70,
fillcolorwarningsecond=white!60!yellow, timedeath=0,resetatpages=3]{tdclock}

\title{The Ticking Digital Clock \texttt{tdclock} package v2.3}
\author{Luis R\'{a}ndez \& Juan I. Montijano}
%\affiliation[IUMA]{IUMA \\ Universidad de Zaragoza }
\date{\today}



\begin{document}

\maketitle

\initclock

\section{The package}
The \texttt{tdclock} package is a \LaTeX2e package that
allows the users to insert into a \LaTeX\/ generated pdf document
a ticking digital clock showing the date and/or time at
the moment in which the document
is being read, for example the one next: \quad \tdclock.

\smallskip
The package is loaded by  \texttt{$\backslash$usepackage[``options'']\{tdclock\}}

\medskip

\noindent Options:

\begin{itemize}
\item  timeinterval=$n$
\item[]
$n$ can be any positive integer. The clock will update its internal status every $n$ seconds.  Thus, if we load
the package with \texttt{[timeinterval=120]}, the clock will update its display every 2 minutes.
The default time interval is set to 29 seconds.

Note that for low values of $n$ the memory used by Adobe increases during the time the document remains opened and can
become very high.  Then, values of $n$ below 10 are not recommended.

\item  font=``adobe font''
\item[]
``adobe font''  is one of the following 9 adobe name fonts:\\[5pt]
\begin{tabular}{llllll}
Helv  & HelvI  & HelvBI &
Times & TimesI & TimesBI \\
Cour  & CourI  & CourBI &&&
\end{tabular}

\item[]At the moment no other fonts, like \TeX\ ones, can be used.  This restriction comes from the fact that the
``dynamic'' clock is based on javascript code embedded into the pdf document.

\item  timeduration=``time (in mimutes)''
\item[]
``time'' can be any integer or decimal number. This option is intended to be used in presentations (beamer for example).
Its value specifies the time the presentation should last.  This option has sense in conjunction with the next options.

\item  timewarningfirst= $n$
\item[]
$n$ can be any integer between 1 and 100. With this option set, after $n$\% of the time specified in  timeduration,
the color and background of the tdclock time  will change, according to the next options.
This can be used as a first warning that you are running out time for the presentation.  The default is set to 90.

\item  timewarningsecond= $n$
\item[]
$n$ can be any integer between 1 and 100 (usually greater than timewarningfirst). With this option set, after $n$\% of the time specified in  timeduration,
the color and background of the tdclock time  will change, according to the next options.
This can be used
as a second warning that you have little time to finish the presentation.  The default is set to 95.

\item  colorwarningfirst= ``color''
\item[]
This option specifies the color for the tdclock time after the time specified by
timeduration and timewarningfirst options. The default is orange.

\item  fillcolorwarningfirst= ``color''
\item[]
This option specifies the color background for the tdclock time after the time specified by
timeduration and timewarningfirst options. The default is ``transparent''.
This has only effect on time specified by $\backslash$crono, $\backslash$tdclock and $\backslash$tdtime
time orders.

\item  colorwarningsecond= ``color''
\item[]
This option specifies the color for the tdclock time after the time specified by
timeduration and timewarningsecond options. The default is red.

\item  fillcolorwarningsecond= ``color''
\item[]
This option specifies the color background for the tdclock time after the time specified by
timeduration and timewarningsecond options. The default is ``transparent''.
This has only effect on time specified by $\backslash$crono, $\backslash$tdclock and $\backslash$tdtime
time orders.

\item  timedeath= 0 or 1
\item[]
If this option is set to 1, after 110\% of the time specified in  timeduration,
the pdf document will be closed.  The default is set to 0 (the document is not closed).

\item  resetatpages= ``pages where the crono is reset to zero''
\item[]
\begin{tabular}{lp{6.5cm}}
resetatpages= none  & does nothing  (the default). \\
resetatpages= all   & the crono is reset to zero every time you changes the page. \\
resetatpages= $n$   & the crono is reset to zero every time you go to the page $n$. \\
resetatpages= $\{n1, n2, \ldots \}$  & the crono is reset to zero every time you go to any of the pages $n1, n2, \ldots$
\end{tabular}
\item  pageresetcontrol= ``The way the pages are specified''
\item[]
\begin{tabular}{lp{6.5cm}}
pageresetcontrol= pdfpagelabels  & The pdf labels must be used (the default). You should put the page number or label LaTex puts on the page. 
Usually, this is the number that appears as page number in the final document.  For this page for example is 3.
In beamer, when overlays are used, all sub-slides have the same pdfpagelabel, the one of the frame.\\
pageresetcontrol= pdfpagenumbers   & The internal pdf page number must be used.  First page has page number 0, the second one has 1 and so on. 
In beamer, when overlays are used, every sub-slide have different pdfpagenumber, in consecutive order.  The page number in the document does not 
coincides with the internal pdf page number.  In this docunment, this page 3 has internal pdf page number 2\\
\end{tabular}
\end{itemize}

Some examples of using the options

\begin{itemize}
\item
{\bf $\backslash$usepackage[font=Times, timeinterval=59]\{tdclock\} }

\item[] Only the font (Times) and the time (59 seconds) for updating the clock is specified.  No warning indicating
that the time for the presentation is finishing will be given.

\item
{\bf $\backslash$usepackage[font=Times, timeinterval=30, timeduration=20, \\
timewarningfirst=85, timewarningsecond=90, \\
fillcolorwarningsecond=white!60!yellow]\{tdclock\} }

\item[] In addition to the font (Times) and the time (30 seconds) for updating the clock, a duration of the presentation of 20 minutes is specified.  The color of the clock font will be set to orange after 17 minutes (85\% of 20).  This color will be changed to red,
    and the background to white!60!yellow after 18 minutes(90\% of 20).

\item
{\bf $\backslash$usepackage[timeduration=60, timewarningfirst=90, \\
timewarningsecond=95, colorwarningfirst=blue, \\
fillcolorwarningfirst=white!60!yellow, \\
fillcolorwarningsecond=white!10!yellow, timedeath=1]\{tdclock\} }

\item[] A duration of the presentation of 60 minutes is specified.  The color of the clock font will be set to blue
after 54 minutes (90\% of 60) with a background white!60!yellow.  The font color will be changed to red after
57 minutes and the background to white!10!yellow.  The document will close automatically after 66 minutes
(110\% of 60).

\end{itemize}

\section{Restrictions--requirements}
The package  requires hyperref, xkeyval and xcolor packages. It works with PDF\LaTeX\/ as well as with \LaTeX\/$\to$DviPs$\to$Ps2pdf sequence.
In documents generated by Dvipdfm, the clock does not work properly.

Since it uses javascript code, and not all pdf readers can interpret javascript,
only some of them will display the documents properly.  We have tested the package with
Adobe reader and Adobe acrobat under windows and Linux.

\section{Installation}
Copy the package file tdclock.sty to a directory where \LaTeX\/ can find it.

\section{Getting the package}

The package can be downloaded at  http://pcmap.unizar.es/numerico/software

\section{Macros}

The clock must be initialized with  \texttt{$\backslash$initclock}, usually at the beginning of the document, after
\texttt{$\backslash$begin\{document\}}.

The following macros display dynamically the current date and/or time:

\begin{center}
\begin{tabular}{|l|l|}
\hline
 \bf command & \bf  action \\
\hline
\texttt{ $\backslash$tdclock}       & displays a complete clock  \\ \hline
\texttt{ $\backslash$tdtime}        & displays the current time    \\ \hline
\texttt{ $\backslash$tddate}        & displays the current date    \\ \hline
\texttt{ $\backslash$tdday}         & displays the current day     \\\hline
\texttt{ $\backslash$tdmonth}       & displays the current month   \\\hline
\texttt{ $\backslash$tdyear}        & displays the current year    \\\hline
\texttt{ $\backslash$tdhours}       & displays the current hour   \\\hline
\texttt{ $\backslash$tdminutes}     & displays the current minute \\\hline
\texttt{ $\backslash$tdseconds}     & displays the current second \\\hline
\end{tabular}
\end{center}

The package also provides macros to display a stopwatch.  This can be done
by means of the following macros:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\bf command  & \bf action \\
\hline
\texttt{ $\backslash$crono}              & displays a stopwatch       \\ \hline
\texttt{ $\backslash$cronohours}         & displays a crono (only hours)   \\\hline
\texttt{ $\backslash$cronominutes}       & displays a crono (only minutes) \\\hline
\texttt{ $\backslash$cronoseconds}       & displays a crono (only seconds) \\\hline
\end{tabular}
\end{center}

In addition, the package includes two macros that display buttons. With one of them, by pressing it,
you reset the stopwatch to zero values.  The form of the command is \texttt{$\backslash$resetcrono\{``button''\}}.
For example, \texttt{$\backslash$resetcrono\{$\backslash$fbox\{reset\}\} $\backslash$crono} produces (press the button to see what happens):
\resetcrono{\fbox{reset}} \crono

The other lets you  toggle from current time to stopwatch.  For example,
\texttt{$\backslash$toggleclock\{$\backslash$fbox\{toggleclock\}\} $\backslash$tdtime} produces (press the button to see what happens):
\toggleclock{\fbox{toggle}} \tdtime.

Note that \texttt{$\backslash$toggleclock} only has effect on \texttt{$\backslash$tdtime} command, and not on \texttt{$\backslash$crono}.

\subsection{Formatting the output}

\subsubsection{Size and color}
The size and color of the characters forming the time or date are the \LaTeX\/
current font size and color.  Thus, for example

\noindent\texttt{
$\backslash$centerline\{$\backslash$textcolor\{blue\}\{$\backslash$Huge $\backslash$tdclock\}\}
} gives:

\centerline{\textcolor{blue}{\Huge \tdtime} }

\smallskip

There is another macro,  \texttt{$\backslash$factorclockfont\{``factor''\}}, that increases the size of the clock
by a desired factor.  To set the size of the clock to its original size, use
\texttt{$\backslash$factorclockfont\{1\}}

\subsubsection{Formatting the display}
There are two commands that change the effect of \texttt{$\backslash$time} and
\texttt{$\backslash$crono}.
\begin{itemize}
\item \texttt{$\backslash$hhmmss} redefine the commands to show the hours,minutes and seconds (this is the default),
\item \texttt{$\backslash$hhmm} redefine them so that they will only show hours and minutes.
\end{itemize}

Hours, minutes and seconds are separated by the character defined in the macro \texttt{$\backslash$timeseparator}.
Therefore, the time separator can be set by redefining this macro.  For example,

\centerline{\texttt{$\backslash$renewcommand\{$\backslash$timeseparator\}\{;\}$\backslash$tdtime}}

gives

\centerline{\renewcommand{\timeseparator}{;}\tdtime}

Different types of formats for time can be achieved by means of the macros \texttt{$\backslash$tdhours}, \texttt{$\backslash$tdminutes} and\texttt{$\backslash$seconds}.  For example,

\noindent\texttt{$\backslash$minutes}.\texttt{$\backslash$seconds}
produces:  \quad \tdminutes.\tdseconds

Different types of formats for the stopwatch can be achieved by means of the macros \texttt{$\backslash$cronohours}, \texttt{$\backslash$cronominutes} and\texttt{$\backslash$cronoseconds}.  For example,

\noindent\texttt{$\backslash$cronominutes}.\texttt{$\backslash$cronoseconds}
produces:  \quad \cronominutes.\cronoseconds

In fact, \texttt{$\backslash$tdtime} and \texttt{$\backslash$crono} are defined by default to \\
\texttt{$\backslash$tdhours$\backslash$timeseparator$\backslash$tdminutes$\backslash$timeseparator$\backslash$tdseconds}\\ and \\
\texttt{$\backslash$cronohours$\backslash$timeseparator$\backslash$cronominutes$\backslash$timeseparator$\backslash$cronoseconds}\\ respectively.

\bigskip

Regarding the date, there are two commands that change the effect of \texttt{$\backslash$tddate}.
\begin{itemize}
\item \texttt{$\backslash$ddmmyyyy} redefine the command to show the day,month and year (this is the default),
\item \texttt{$\backslash$mmddyyyy} redefine it to show month, day and year.
\end{itemize}

Day, month and year are separated by the character defined in the macro \texttt{$\backslash$dateseparator}.
Therefore, the date separator can be set by redefining this macro.  For example,

\centerline{\texttt{$\backslash$renewcommand\{$\backslash$dateseparator\}\{;\}$\backslash$tddate}}

gives

\centerline{\renewcommand{\dateseparator}{;}\tddate}

Different types of formats for date can be achieved by means of the macros \texttt{$\backslash$tdday}, \texttt{$\backslash$tdmonth} and\texttt{$\backslash$tdyear}.  For example,

\noindent\texttt{$\backslash$day}--\texttt{$\backslash$month}
produces:  \quad \tdday--\tdmonth

By default, \texttt{$\backslash$tddate} is defined by default to \\
\texttt{$\backslash$tdday$\backslash$dateseparator$\backslash$tdmonth$\backslash$dateseparator$\backslash$tdyear}.

Since the font used to display the dynamic date and time is one of the adobe fonts, we have included two commands \texttt{$\backslash$pdfslash} and \texttt{$\backslash$pdfcolon} to provide the charactrers ``slash'' and ``colon'' so that defining
\texttt{$\backslash$renewcommand\{$\backslash$timeseparator\}\{$\backslash$pdfcolon\}}
the command \texttt{$\backslash$tdtime} will have all their characters in the same font.
The same for \texttt{$\backslash$tddate} if we use \texttt{$\backslash$pdfslash} as separator.

\newpage
\section{Summary of macros}

\bigskip
\centerline{Time-Date macros}
\begin{tabular}{|l|l|l|}
\hline
macro  &  result  &  action \\
\hline
 $\backslash$initclock        &                                      & initialize  clock   \\ \hline
 $\backslash$tdclock     & \tdclock                        & complete clock  \\ \hline
 $\backslash$tdtime      & \tdtime                         & current time    \\ \hline
 $\backslash$tddate      & \tddate                         & current date    \\ \hline
 $\backslash$tdday       & \tdday                          & current day     \\\hline
 $\backslash$tdmonth     & \tdmonth                        & current month   \\\hline
 $\backslash$tdyear      & \tdyear                         & current year    \\\hline
 $\backslash$tdhours     & \tdhours                        & current hours   \\\hline
 $\backslash$tdminutes   & \tdminutes                      & current minutes \\\hline
 $\backslash$tdseconds   & \tdseconds                      & current seconds \\\hline
 $\backslash$crono            & \crono                               & stopwatch       \\ \hline
 $\backslash$cronohours       & \cronohours                          & crono hours   \\\hline
 $\backslash$cronominutes     & \cronominutes                        & crono minutes \\\hline
 $\backslash$tdwarningbox\{$\backslash$cronominutes\}     &  \tdwarningbox{\cronominutes}         & warning boxed crono minutes \\\hline
 $\backslash$cronoseconds     & \cronoseconds                        & crono seconds \\\hline
 $\backslash$resetcrono\{``button''\}       & \resetcrono{\fbox{reset}}     & sets crono time to zero    \\\hline
 $\backslash$toggleclock\{``button''\}      & \toggleclock{\fbox{toggle}}    & toggle time-crono   \\\hline
\end{tabular}

\bigskip

\centerline{Formatting macros}
\begin{tabular}{|l|l|}
\hline
 \texttt{$\backslash$hhmm$\backslash$tdtime}          & \hhmm\tdtime                     \\ \hline
 \texttt{$\backslash$hhmmss$\backslash$tdtime}        & \hhmmss\tdtime                   \\ \hline
 \texttt{$\backslash$mmddyy$\backslash$tddate}        & \mmddyyyy\tddate                \\ \hline
 \texttt{$\backslash$ddmmyy$\backslash$tddate}        & \ddmmyyyy\tddate                   \\ \hline
 \texttt{$\backslash$renewcommand\{$\backslash$dateseparator\}\{--\}$\backslash$tddate}  & \renewcommand{\dateseparator}{--}\tddate     \\ \hline
 \texttt{$\backslash$renewcommand\{$\backslash$timeseparator\}\{.\}$\backslash$tdtime}  & \renewcommand{\timeseparator}{.}\tdtime        \\ \hline
 \texttt{$\backslash$pdfslash}         & \pdfslash                           \\ \hline
 \texttt{$\backslash$pdfcolon}        & \pdfcolon                            \\ \hline
  \texttt{$\backslash$factorclockfont\{2.0\}$\backslash$tdtime}     & \factorclockfont{2.0}\tdtime   \\ \hline
\end{tabular}

\end{document}