path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex

% ======================================================================
% scrdatetime.tex
% Copyright (c) Markus Kohm, 2001-2012
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% 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 and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scrdatetime.tex
% Copyright (c) Markus Kohm, 2001-2012
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Chapter about scrpage2 of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel ueber scrpage2 in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\ProvidesFile{scrdatetime.tex}[{2012/02/23 KOMA-Script guide (chapter:
  scrdate, scrtime)}]
\translator{Markus Kohm\and Gernot Hassenpflug}

% Date of translated German file: 2012/02/23

\chapter{Weekday and Time Using \Package{scrdate} and
  \Package{scrtime}}
\labelbase{datetime}

There are two packages included in {\KOMAScript} to improve and extend
the handling of date\Index{date} and time\Index{time} over and above
what is provided by the standard commands \Macro{today} and
\Macro{date}. Like all the other packages from the {\KOMAScript}
bundle these two packages may be used not only with {\KOMAScript}
classes but also with the standard and many other classes.

Since
\KOMAScript~3.05a\ChangedAt{v3.05a}{\Package{scrdate}\and\Package{scrtime}}
this packages use the common version number of \KOMAScript. This change has
been done, because the packages need the corresponding version of
\Package{scrkbase} and \Package{scrbase}.


\section{The Day of the Week Using
  \Package{scrdate}}
\label{sec:datetime.scrdate}
\BeginIndex{Package}{scrdate}

With version~3.05a the functionality of this package enhanced a lot. Beside of
the current day of the week\Index{day>of the week} this package provides the
day of the week of every date of the Gregorian calendar now.

\begin{Declaration}
  \Macro{CenturyPart}\Parameter{year}\\%
  \Macro{DecadePart}\Parameter{year}%
\end{Declaration}%
\BeginIndex{Cmd}{CenturyPart}%
\BeginIndex{Cmd}{DecadePart}%
The\ChangedAt{v3.05a}{\Package{scrdate}} command \Macro{CenturyPart} offers
the value of the century digits\,---\,hundreds and thousands\,---\,of a
\PName{year}. The command \Macro{DecadePart} in difference offers the other
digits which are the units and tens. The number of digits of \PName{year}
doesn't care. The value may be assigned to a counter or may be used for
calculations, i.\,e., using \Macro{numexpr}\IndexCmd{numexpr}. For output of
an Arabic number of the value prefix it with \Macro{the}\IndexCmd{the}.

\begin{Example}
  You want to calculate and output the century of the current year.
\begin{lstcode}
  The year \the\year\ is the year \the\DecadePart{\year}
  of the \engord{\numexpr\CenturyPart{\year}+1\relax} century.
\end{lstcode}
  The result would be:
  \begin{quote}
    The year \the\year\ is the year \the\DecadePart{\year}
    of the \engordnumber{\numexpr\CenturyPart{\year}+1\relax} century.
  \end{quote}
  Package \Package{engord}\IndexPackage{engord} has been used for this
  example. See \cite{package:engord} for more information.
\end{Example}

Please\textnote{Attention!} note, that within used method of counting the
year~2000 is the year~0\,---\,and therefore the first year\,---\,of the
21st~century.%
\EndIndex{Cmd}{DecadePart}%
\EndIndex{Cmd}{CenturyPart}%

\begin{Declaration}
  \Macro{DayNumber}\Parameter{year}\Parameter{month}\Parameter{day}\\%
  \Macro{ISODayNumber}\Parameter{ISO-date}%
\end{Declaration}%
\BeginIndex{Cmd}{DayNumber}%
\BeginIndex{Cmd}{ISODayNumber}%
These\ChangedAt{v3.05a}{\Package{scrdate}} two commands offers the value of
the number of the day of the week\Index{day>of the week} of any date. The
differ only in the kind of date declaration. Command \Macro{DayNumber} needs
\PName{year}, \PName{month}, and \PName{day} as separate parameters. Command
\Macro{ISODayNumber} expects an \PName{ISO-date} as a single argument. The
expected format of the \PName{ISO-date} is:
\PName{year}\texttt{-}\PName{month}\texttt{-}\PName{day}. It doesn't matter
whether \PName{month} or \PName{day} have one or two digits. The result of
both commands may be assigned to a counter or used for calculations, i.\,e.,
using \Macro{numexpr}\IndexCmd{numexpr}. For output of
an Arabic number of the value prefix it with \Macro{the}\IndexCmd{the}.

\begin{Example}
  You want to know the number of the day of the week of the 1st~May~2027.
\begin{lstcode}
  The 1st~May~2027 has \the\ISODayNumber{2027-5-1}
  as the number of the day of the week.
\end{lstcode}
  The result will be:
  \begin{quote}
    The 1st~May~2027 has \the\ISODayNumber{2027-5-1}
    as the number of the day of the week.
  \end{quote}
\end{Example}

A special feature is to walk a number of days into future or past from a given
date.
\begin{Example}
  You want to know the number of the day of the week, that will be in 12~days
  and that will be 24~days before the 24th~December~2027.
\begin{lstcode}
  In 12~days the number of the day of the week
  will be \the\DayNumber{\year}{\month}{\day+12} and
  24~days before the 24th~December~2027 it will be
  \the\ISODayNumber{2027-12-24-24}.
\end{lstcode}
  The result may be, e.\,g.:
  \begin{quote}
    In 12~days the number of the day of the week
    will be \the\DayNumber{\year}{\month}{\day+12} and
    24~days before the 24th~December~2027 it will be
    \the\ISODayNumber{2027-12-24-24}.
  \end{quote}
\end{Example}

The days of the week are numbered: Sunday\,=\,0, Monday\,=\,1, Tuesday\,=\,2,
Wednesday\,=\,3, Thursday\,=\,4, Friday\,=\,5, and Saturday\,=\,6.%
%
\EndIndex{Cmd}{DayNumber}%
\EndIndex{Cmd}{ISODayNumber}%


\begin{Declaration}
  \Macro{DayNameByNumber}\Parameter{number of the day of the week}\\%
  \Macro{DayName}\Parameter{year}\Parameter{month}\Parameter{day}\\%
  \Macro{ISODayName}\Parameter{ISO-date}%
\end{Declaration}%
\BeginIndex{Cmd}{DayNameByNumber}%
\BeginIndex{Cmd}{DayName}%
\BeginIndex{Cmd}{ISODayName}%
Usually\ChangedAt{v3.05a}{\Package{scrdate}} you don't want to know the number
of the day of the week, but the name of the day of the week. Because of this,
the command \Macro{DayNameByNumber} offers the name of the day of the week
corresponding with a number. The number may be the result of \Macro{DayNumber}
or \Macro{ISODayNumber}. The two commands \Macro{DayName} and
\Macro{ISODayName} directly offer the name of the day of the week of a given
date.

\begin{Example}
  You want to know the name of the day of the week of the 24th~December~2027.
\begin{lstcode}
  Please pay you bill until \ISODayName{2027-12-24},
  24th~December~2027.
\end{lstcode}
  The result will be:
  \begin{quote}
    Please pay you bill until \ISODayName{2027-12-24},
    24th~December~2027.
  \end{quote}
\end{Example}

Again a special feature is to make some calculations inside the argument of
\Macro{DayName}.
\begin{Example}
  You want to know the names of the days of the week, that will be in 12~days
  and that will be 24~days before the 24th~December~2027.
\begin{lstcode}
  In 12~days the name of the day of the week
  will be \DayName{\year}{\month}{\day+12} and
  24~days before the 24th~December~2027 it will be
  \ISODayName{2027-12-24-24}. Nevertheless two weeks
  and three days after a Wednesday a
  \DayNameByNumber{3+2*7+3} will follow.
\end{lstcode}
  The result may be, e.\,g.:
  \begin{quote}
    In 12~days the name of the day of the week
    will be \DayName{\year}{\month}{\day+12} and
    24~days before the 24th~December~2027 it will be
    \ISODayName{2027-12-24-24}. Nevertheless two weeks
    and three days after a Wednesday a
    \DayNameByNumber{3+2*7+3} will follow.
  \end{quote}
\end{Example}%
%
\EndIndex{Cmd}{ISODayName}%
\EndIndex{Cmd}{DayName}%
\EndIndex{Cmd}{DayNameByNumber}%


\begin{Declaration}
  \Macro{ISOToday}\\%
  \Macro{IsoToday}\\
  \Macro{todaysname}\\%
  \Macro{todaysnumber}%
\end{Declaration}%
\BeginIndex{Cmd}{todaysname}%
\BeginIndex{Cmd}{todaysnumber}%
\BeginIndex{Cmd}{ISOToday}%
\BeginIndex{Cmd}{IsoToday}%
In the prior examples the current date have been given cumbersomely and
explicitly using the \TeX{} registers \Macro{year}\IndexCmd{year},
\Macro{month}\IndexCmd{month}, and \Macro{day}\IndexCmd{day}. The commands
\Macro{ISOToday}\ChangedAt{v3.05a}{\Package{scrdate}} and \Macro{IsoToday}
offers the current date in ISO-notation directly. These commands differ in the
number of digits for numbers less than 10 only. \Macro{ISOToday} prefixes
numbers less than 10 for the month and day with a 0. In opposite to this
\Macro{IsoToday} will show numbers less than 10 for the month and day with one
digit only. Command \Macro{todaysname} directly offers the name of the current
day of the week. Command \Macro{todaysnumber} offers the number of that name
instead. More information about usability of this value may be found at
previous description of \Macro{DayNumber} and \Macro{ISODayNumber}.

\begin{Example}
  I want to show you the name of the weekday in which this document has been
  type-set:
  \begin{lstlisting}
    I have done the {\LaTeX} run of this document 
    on a \todaysname.
  \end{lstlisting}
  This will result in, e.\,g.:
  \begin{quote}
    I have done the {\LaTeX} run of this document 
    on a \todaysname.
  \end{quote}
\end{Example}

Note that the package is not able to decline words. The known terms
are the nominative singular that may be used, e.\,g., in the date of a
letter. Given this limitation, the example above can work correctly
only for some languages.

\begin{Explain}
  The\textnote{Hint!} names of the weekdays are saved in capitalized form,
  i.\,e., the first letter is a capital letter, all the others are lowercase
  letters. But for some languages you may need the names completely in
  lowercase. You may achieve this using the standard {\LaTeX} command
  \Macro{MakeLowercase}\IndexCmd{MakeLowercase}%
  \important{\Macro{MakeLowercase}}, e.\,g.:
  % Umbruchkorrektur: listings
\begin{lstcode}[belowskip=\dp\strutbox]
  \MakeLowercase{\todaysname}
\end{lstcode}
  This converts the whole argument into lower case letters. Of course, this
  may be done also using previous described commands
  \Macro{DayNameByNumber}\IndexCmd{DayNameByNumber},
  \Macro{DayName}\IndexCmd{DayName} and
  \Macro{ISODayName}\IndexCmd{ISODayName}.%
\end{Explain}%
\EndIndex{Cmd}{IsoToday}%
\EndIndex{Cmd}{ISOToday}%
\EndIndex{Cmd}{todaysnumber}%
\EndIndex{Cmd}{todaysname}


\begin{Declaration}
  \Macro{nameday}\Parameter{name}
\end{Declaration}%
\BeginIndex{Cmd}{nameday}%
Analogous to how the output of \Macro{today} can be modified using
\Macro{date}\IndexCmd{date}, so the output of \Macro{todaysname} can
be changed to \PName{name} by using \Macro{nameday}.
\begin{Example}
  You change the current date to a fixed value using \Macro{date}. You
  are not interested in the actual name of the day, but want only to
  show that it is a workday. So you set:
\begin{lstlisting}
  \nameday{workday}
\end{lstlisting}
  After this the previous example will result in:
  \begin{quote}\nameday{workday}
    I have done the {\LaTeX} run of this document on a \todaysname.
  \end{quote}
\end{Example}
There's no such command for changing the result of
\Macro{ISOToday}\IndexCmd{ISOToday} or \Macro{IsoToday}\IndexCmd{IsoToday}.
\EndIndex{Cmd}{nameday}


\minisec{Name of the day of the week in different languages}%
Currently the package \Package{scrdate} knows the languages English (english,
american, USenglish, UKenglish and british), German (german, ngerman,
austrian\ChangedAt{v3.08b}{\Package{scrdate}}, and naustrian), French
(french), Italian (italian), Spanish (spanish), Croatian (croatian), Finnish
(finnish), Norwegian (norsk), Swedish (swedish), and Danish (danish). If you
want to configure it for other languages, see \File{scrdate.dtx}.

In the current implementation it does not matter whether you load
\Package{scrdate} before or after
\Package{german}\IndexPackage{german},
\Package{ngerman}\IndexPackage{ngerman},
\Package{babel}\IndexPackage{babel} or similar packages. In both cases the
correct language will be used.

\begin{Explain}
  To explain a little bit more exactly: while you are using a language
  selection which works in a compatible way to
  \Package{babel}\IndexPackage{babel} or
  \Package{ngerman}\IndexPackage{ngerman}, the correct language will be used
  by \Package{scrdate}. If you are using another language selection you will
  get (US-)English names.
\end{Explain}
\EndIndex{Package}{scrdate}


\section{Getting the Time with Package}
\label{sec:datetime.scrtime}
\BeginIndex{Package}{scrtime}

The second problem is the question of the current time. The solution
may be found using package \Package{scrtime}.

\begin{Declaration}%
  \Macro{thistime}\OParameter{delimiter}\\
  \Macro{thistime*}\OParameter{delimiter}
\end{Declaration}%
\BeginIndex{Cmd}{thistime}\BeginIndex{Cmd}{thistime*}%
\Macro{thistime} results in the current time\Index{time}. The
delimiter between the values of hour, minutes and seconds can be given
in the optional argument. The default symbol of the delimiter is
``\PValue{:}''.

\Macro{thistime*} works in almost the same way as \Macro{thistime}.
The only difference is that unlike with \Macro{thistime}, with
\Macro{thistime*} the value of the minute field is not preceded by a
zero when its value is less than 10. Thus, with \Macro{thistime} the
minute field has always two places.
\begin{Example}
  The line
\begin{lstlisting}
  Your train departs at \thistime.
\end{lstlisting}
  results, for example, in:
  \begin{quote}
    Your train departs at \thistime.
  \end{quote}
  or:
  \begin{quote}
    Your train departs at 23:09.
  \end{quote}
  \bigskip
  In contrast to the previous example a line like:
\begin{lstlisting}
  This day is already \thistime*[\ hours and\ ] minutes old.
\end{lstlisting}
  results in:
  \begin{quote}
    This day is already \thistime*[\ hours and\ ] minutes old.
  \end{quote}
  or:
  \begin{quote}
    This day is already 12 hours and 25 minutes old.
  \end{quote}
\end{Example}
\EndIndex{Cmd}{thistime}\EndIndex{Cmd}{thistime*}

\begin{Declaration}%
 \Macro{settime}\Parameter{time}
\end{Declaration}%
\BeginIndex{Cmd}{settime}%
\Macro{settime} sets the output of \Macro{thistime} and
\Macro{thistime*} to the value \PName{time}.  Now the optional
parameter of \Macro{thistime} or \Macro{thistime*} is ignored, since
the result of \Macro{thistime} or \Macro{thistime*} was completely
determined using \Macro{settime}.%
\EndIndex{Cmd}{settime}

\begin{Declaration}
  \KOption{12h}\PName{simple-switch}%
\end{Declaration}%
\BeginIndex{Option}{12h~=\PName{simple switch}}%
\BeginIndex{Option}{24h}%
With option \Option{12h}\ChangedAt{v3.05a}{\Package{scrtime}} one can select
whether the result of \Macro{thistime} and \Macro{thistime*} is in 12- or in
24-hour format. The option understands the values for simple-switch listed in
\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The option
without a value is same like \OptionValue{12h}{true} and therefore
12-hour-format will be used. The default is \Option{24h}.

You may use this option either as a global option in the optional argument of
\Macro{documentclass}, as a package option in the optional argument of
\Macro{usepackage} or after loading the package using \Macro{KOMAoptions} or
\Macro{KOMAoption} (see, e.\,g., \autoref{sec:typearea.options},
\autopageref{desc:typearea.cmd.KOMAoptions}).  The option has no effect on the
results of \Macro{thistime} and \Macro{thistime*} if \Macro{settime} is used.

Only\textnote{Attention!} for compatibility with former releases of
\Package{scrtime} also option \Option{24h} will switch to 24-hour format if
used in the optional argument of \Macro{documentclass} or
\Macro{usepackage}. Nevertheless, you should not use this option any longer.%
\EndIndex{Option}{24h}%
\EndIndex{Option}{12h~=\PName{simple switch}}%
%
\EndIndex{Package}{scrtime}

\endinput

%%% Local Variables: 
%%% mode: latex
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: