datetime2 package FAQ
This is the FAQ for the datetime2 package. See also the datetime2 package documentation.
The datetime2 package uses the tracklang package to detect document languages. Related: tracklang package and Localisation with tracklang.tex.
- 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
\textdateand\oclockstyles? - I’ve written a new date/time style. How can I share it?
- Why is
showdowa package option rather than a language option? - How do I add a test for the
showdowsetting to a style? - How do I provide for different declension (nominative, genitive etc)?)
- How do I write a datetime2 language module?
- Unexpected Output
- Localisation
General
This is discussed in the datetime2 documentation but briefly there were issues with datetime.sty that couldn’t be resolved without substantially breaking backward-compatibility.
2020-07-03 12:22:23
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.
2020-07-03 12:23:55
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.
2020-07-03 12:24:27
The main changes are:
- All commands except
\todayand\Todayhave a prefix to help prevent clashes with other date and time-related packages. For example,\DTMcurrenttimeinstead of\currenttime. - Commands like
\todayare designed to be 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. It also means that the language support can be maintained by someone who is actually familiar with the language.
2020-07-03 12:26:38
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
2020-07-03 12:32:05
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.2020-07-03 12:33:01
Put it in a package and upload it to CTAN. (Make sure you first read CTAN’s upload guide.) 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.
2020-07-03 12:36:11
showdow a package option rather than a language option? 🔗
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.
2020-07-03 12:37:29
showdow setting to a style? 🔗
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}}
2020-07-03 12:39: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.2020-07-03 12:40:33
The datetime2 package uses the tracklang package to detect the document languages, so I recommend you read Localisation with tracklang.tex first and then Writing a datetime2 Language Module.
2020-07-03 13:08:28
Unexpected Output
showdow 🔗
Not all styles, including some of the language styles, implement the showdow option. Check with the documentation for the relevant package or language module.
2020-07-03 13:11:28
Update 2019-10-28: I’ve fixed all unmaintained modules.
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}
2020-07-03 13:12:34
Unfortunately babel doesn’t currently provide a list of languages that have been loaded with \babelprovide, there’s no way for tracklang (or any other package) to simply access that information. Related: Localisation with tracklang.tex.
2020-07-03 13:16:13
Localisation
First, you need to make sure that you have the relevant datetime2 language module installed. For example, to display the date in the en-GB style (British English) you need to install the datetime2-english module using your TeX package manager. (This needs to be done in addition to installing datetime2.)
Next you need to ensure that datetime2 picks up the correct locale setting for your document. Unfortunately, this doesn’t always work (see Localisation with tracklang.tex).
You can explicitly set the locale in the datetime2 package option list. For example:
\usepackage[en-GB]{datetime2}
If the language has been loaded before datetime2 then you need to explicitly switch on regional support. For example:
\documentclass[british]{article}
\usepackage{babel}
\usepackage[useregional]{datetime2}
If you prefer a numeric regional style then you need useregional=numeric.
Each style comes with its own set of options that are relevant to the particular style. These should be set using \DTMlangsetup. For example:
\documentclass{article}
\usepackage[en-GB,en-US]{datetime2}
\DTMlangsetup[en-GB]{ord=raise,abbr,monthyearsep={,\space}}
\DTMlangsetup[en-US]{dayyearsep={,\space}}
\begin{document}
GB date: \DTMsetstyle{en-GB}\DTMdate{2021-06-31}.
US date: \DTMsetstyle{en-US}\DTMdate{2021-06-31}.
\end{document}
This produces:
GB date: 31st Jun, 2021.US date: June 31, 2021.
2021-05-08 22:01:45
You can use the options that are provided by the style for minor modifications, such as the example given in How do I make the date appear in my regional format instead of the default ISO format? If you have a more significant change that can’t be obtained through the style options, then you can define your own style.
For example, suppose you want the date in the form 2021-Aug-01. This has the year at the start but it uses an abbreviated English month name and a two-digit day. This format can’t be obtained with any of the styles provided by datetime2-english, so a new style is needed.
First you need to make sure that the English month name commands are provided, so you need to load datetime2 with en (the ISO language code for English), but you don’t want to switch to that style so you also need useregional=false:
\usepackage[en,useregional]{datetime2}
Now you can define a style that uses the English commands:
\DTMnewdatestyle
{yyyyMonthdd}% label
{% style commands
\renewcommand{\DTMdisplaydate}[4]{%
\number##1 % year
-% separator
\DTMenglishshortmonthname{##2}% abbreviated month
-% separator
\DTMtwodigits{##3}% two-digit day
}%
\renewcommand{\DTMDisplaydate}[4]{%
\DTMdisplaydate{##4}{##3}{##2}{##1}%
}%
}
Remember that you need to set the style once it’s defined:
\DTMsetdatestyle{yyyyMonthdd}2021-05-08 22:13:14