summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tdclock/tdclock-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tdclock/tdclock-doc.tex')
-rw-r--r--macros/latex/contrib/tdclock/tdclock-doc.tex343
1 files changed, 343 insertions, 0 deletions
diff --git a/macros/latex/contrib/tdclock/tdclock-doc.tex b/macros/latex/contrib/tdclock/tdclock-doc.tex
new file mode 100644
index 0000000000..134b1b7634
--- /dev/null
+++ b/macros/latex/contrib/tdclock/tdclock-doc.tex
@@ -0,0 +1,343 @@
+\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}