datetime2 package FAQ
This is the FAQ for the datetime2 package. See also the datetime2 package documentation.
- General
- Why was a new package made instead of updating datetime.sty?
- Why doesn't datetime2 recognise my language?
- Can I still use the old datetime package?
- What are the main differences between datetime and datetime2?
- How do I change my document from datetime.sty?
- Is there an equivalent to datetime's \textdate and \oclock styles?
- I've written a new date/time style. How can I share it?
- Why is "showdow" a package option rather than a language option?
- How do I add a test for the showdow setting to a style?
- How do I provide for different declension (nominative, genitive etc)?)
- Unexpected Output
General
This is discussed in the datetime2 documentation but briefly there were issues with datetime.sty that couldn't be resolved without breaking backward-compatibility.
Last modified: 2015-03-25 14:05:07.
The language and regional settings are dealt with by the datetime2 modules, which must be independently installed. Check the datetime2-contrib listings. If your language is listed there you can install it. If it's not listed there, the appropriate language module is unavailable, in which case you have the following options: volunteer to write the module or persuade someone to write the module.
See also the section "6. Multi-Lingual Support" in the datetime2 documentation.
Last modified: 2015-04-01 11:47:18.
Obsolete packages remain available in the CTAN obsolete tree. Your TeX distribution may not contain some obsolete packages. If this is the case, you will need to download datetime.sty from CTAN and manually install.
It's your choice if you want to continue to use an obsolete package, but you should be aware that any issues with unmaintained packages won't be fixed.
Last modified: 2015-03-27 05:53:34.
The main changes are:
- All commands except \today and \Today have a prefix to help prevent clashes with other date and time-related packages. For example, \DTMcurrenttime instead of \currenttime.
- Commands like \today are expandable, which means you should be able to use them to write the date/time information to external files, use them in PDF bookmarks or use them in commands like \MakeUppercase. Styles should protect any fragile commands to assist with this. There may, however, be some supplementary styles in contributed packages that can't produce expandable dates or styles. In which case this should be mentioned in the documentation for those supplementary packages.
- Language support is separated into independently installed and maintained modules. This means you only need to install the modules for your own language(s) rather than having to install everything.
Last modified: 2015-04-01 11:50:56.
The default date format in datetime2.sty has changed to ISO so if your old document looked like:
\documentclass{article}
\usepackage{datetime}
\begin{document}
\today
\end{document}
then the date would be formatted in British English style: Saturday 28th March, 2015. If you simply replace datetime with datetime2:
\documentclass{article}
\usepackage{datetime2}
\begin{document}
\today
\end{document}
then the date would be formatted in ISO style: 2015-03-28. If you want to reproduce the British format you need to make sure you have also installed datetime2-english and load it using package options:
\documentclass{article}
\usepackage[en-GB,showdow]{datetime2}
\begin{document}
\today
\end{document}
This now displays the date in the style Saturday 28th March 2015, which is slightly different from the datetime.sty format. You can also use "british" instead of "en-GB", but take care if you try loading it as a document class option. If you try
\documentclass[british]{article}
\usepackage[showdow]{datetime2}
\begin{document}
\today
\end{document}
this once again produces the ISO format 2015-03-28 but you can now switch to the British style using \DTMsetstyle{en-GB} or do
\documentclass[british]{article}
\usepackage[useregional,showdow]{datetime2}
\begin{document}
\today
\end{document}
Similarly if you use babel:
\documentclass[british]{article}
\usepackage{babel}
\usepackage[useregional,showdow]{datetime2}
\begin{document}
\today
\end{document}
If you want the suffix as a superscript you need to add
\DTMlangsetup[en-GB]{ord=raise}
before you display the date. If you additionally want the comma you need to do:
\DTMlangsetup[en-GB]{ord=raise,monthyearsep={,\space}}
datetime2.sty uses different command names to datetime.sty (except for \today) and prefixes them all to prevent clashes with other packages. It also uses an ISO year month day way of specifying dates in command arguments to avoid confusion. For example
\formatdate{28}{3}{2014}% datetime.sty
needs to be replaced with
\DTMdisplaydate{2014}{3}{28}{-1}% datetime2.sty
or
\DTMdate{2014-3-28}% datetime2.sty
Note that \DTMdate isn't expandable (but can calculate the week day, if enabled) whereas \DTMdisplaydate is expandable (but can't calculate the week day).
Saving dates has similarly changed from:
\newdate{mydate}{28}{3}{2015}% datetime.sty
to
\DTMsavedate{mydate}{2015-03-28}% datetime2.sty
Using the dates has changed from:
\displaydate{mydate}% datetime.sty
to
\DTMusedate{mydate}% datetime2.sty
Last modified: 2015-04-02 07:04:23.
Yes, but you need to load the datetime2-en-fulltext package. Example usage:
\documentclass{article}
\usepackage[showdow]{datetime2-en-fulltext}
\begin{document}
Date: \today. Time: \DTMcurrenttime.
\end{document}
See the datetime2-en-fulltext documentation for further details.Last modified: 2015-04-02 07:10:35.
Put it in a package and upload it to CTAN. For the suggested CTAN directory use /macros/latex/contrib/datetime2-contrib/package name where package name is the name of your package. See also the end of section 5.2 "Defining New Styles" in the datetime2 manual.
Last modified: 2017-06-13 03:49:07.
In order to show the day of week (showdow=true), the week day needs to be calculated for commands like \today and \DTMdate. This requires that the datetime2-calc.sty package is loaded. If showdow is used as a package option, it can automatically load datetime2-calc after datetime2 has finished loading, which saves you from remembering to load it. Since the datetime2-calc package additionally requires pgfkeys and pgfcalendar which adds to the overall document build time, it's not loaded unless required.
Last modified: 2015-04-02 07:34:26.
You can use the \ifDTMshowdow conditional to determine the showdow setting, but remember that the style should also check if the day of week index has been set to -1 (which indicates that the day of week name should be ignored for a specific use case). So when you redefine \DTMdisplaydate within \DTMnewstyle or \DTMnewdatestyle the test for the day of week name should look something like:
\ifDTMshowdow
\ifnum##4>-1 % space needed after -1
% code that inserts the day of week name
% where the day of week index is given by ##4
\fi
\fi
If you are writing a language module, you need to define \DTMlangweekdayname where lang is the root language label. For example, datetime2-english defines \DTMenglishweekdayname. This naming scheme is needed in order to work with \DTMweekdayname provided by datetime2-calc.sty. (Similarly define \DTMlangWeekdayname for first letter upper case version, \DTMlangshortweekdayname and \DTMlangshortWeekdayname for abbreviated versions, if required.)
If the week or month names include non-ASCII characters, there should be an ASCII version of \DTMlangweekdayname in the file datetime2-lang-ascii.ldf and a UTF-8 version in the file datetime2-lang-utf8.ldf. You might find it easiest to adapt the code from an existing language module. For example, datetime2-french.dtx.
You might also want to consider providing a command to use as the separator between the day of week name and the rest of the date. For example, datetime2-en-GB.ldf defines:
\newcommand*{\DTMenGBdowdaysep}{\space}
and also provides a key to change this value with \DTMlangsetup[en-GB]{dowdaysep={separator code}}:
\DTMdefkey{en-GB}{dowdaysep}{\renewcommand*{\DTMenGBdowdaysep}{#1}}
Another example is with datetime2-romanian which is regionless, so datetime2-romanian.ldf provides:
\newcommand*{\DTMromaniandowdaysep}{\space}
and
\DTMdefkey{romanian}{dowdaysep}{\renewcommand*{\DTMromaniandowdaysep}{#1}}
Last modified: 2017-06-13 03:27:54.
Provide separate commands for each declension. An example is given in this TeX.SE answer for Czech, which defines \DTMczechnominativemonthname for the nominative case, and \DTMczechgenitivemonthname for the genitive case. The command \DTMczechmonthname needs to be initialised to the most appropriate of these. For example,
\newcommand*{\DTMczechmonthname}{\DTMczechgenitivemonthname}
Remember that if UTF-8 support is needed, an ASCII version needs to be defined in the -ascii.ldf file and the UTF-8 version needs to be defined in the -utf8.ldf file.
You can then provide a key for use with the language module to allow users to switch forms. For example:
\DTMdefchoicekey{czech}{month}[\val\nr]{genitive,nominative}{%
\ifcase\nr\relax
\renewcommand*\DTMczechmonthname{\DTMczechgenitivemonthname}%
\renewcommand*\DTMczechMonthname{\DTMczechgenitiveMonthname}%
\or
\renewcommand*\DTMczechmonthname{\DTMczechnominativemonthname}%
\renewcommand*\DTMczechMonthname{\DTMczechnominativeMonthname}%
\fi
}
Similarly for week day names, if supported.Last modified: 2017-06-13 03:41:40.
Unexpected Output
Not all styles, including some of the language styles, implement the showdow option. Check with the documentation for the relevant package or language module.
Last modified: 2015-11-10 04:54:44.
This is a known bug. Unfortunately the template used to create all the language .ldf files had an uncommented end of line character. I've fixed this in datetime2-english and am working my way through all the modules, fixing the unmaintained ones and contacting the new maintainers of the ones that have been adopted. Unfortunately, due to the large number of modules this is quite time-consuming, so please be patient. If you would like to take over maintenance of any of the unadopted modules, please contact me so that I can notify the CTAN team.
In the mean time, if you are experiencing this problem, here's a fix until the new version is available: modify the appropriate date command \datelanguage to switch the date style. For example:
\documentclass{article}
\usepackage{polyglossia}
\setmainlanguage{french}
\usepackage[useregional]{datetime2}
\renewcommand\datefrench{%
\DTMifcaseregional
{}% do nothing
{\DTMsetstyle{french}}%
{\DTMsetstyle{french-numeric}}%
}
\begin{document}
``\textfrench{\today}''
\end{document}
Update 2019-10-28: I've fixed all unmaintained modules.Last modified: 2019-11-01 09:14:59.