% ====================================================================== % 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: