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 FAQ and Localisation with tracklang.tex.

General
Unexpected Output

General

Why was a new package made instead of updating datetime.sty? 🔗

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.

Last modified: 2020-07-03 12:22:23.

Top

Why doesn’t datetime2 recognise my language? 🔗

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: 2020-07-03 12:23:55.

Top

Can I still use the old datetime package? 🔗

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: 2020-07-03 12:24:27.

Top

What are the main differences between datetime and datetime2? 🔗

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 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.

Last modified: 2020-07-03 12:26:38.

Top

How do I change my document from datetime.sty? 🔗

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 28^th 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

\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

\DTMsavedate{mydate}{2015-03-28}% datetime2.sty

Using the dates has changed from:

\displaydate{mydate}% datetime.sty

\DTMusedate{mydate}% datetime2.sty

Last modified: 2020-07-03 12:32:05.

Top

Is there an equivalent to datetime’s \textdate and \oclock styles? 🔗

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: 2020-07-03 12:33:01.

Top

I’ve written a new date/time style. How can I share it? 🔗

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.

Last modified: 2020-07-03 12:36:11.

Top

Why is 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.

Last modified: 2020-07-03 12:37:29.

Top

How do I add a test for the 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}}

Last modified: 2020-07-03 12:39:54.

Top

How do I provide for different declension (nominative, genitive etc)?) 🔗

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: 2020-07-03 12:40:33.

Top

How do I write a datetime2 language module? 🔗

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.

Last modified: 2020-07-03 13:08:28.

Top

Unexpected Output

The day of week doesn’t show when I use 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.

Last modified: 2020-07-03 13:11:28.

Top

Unwanted space occurs after language change 🔗

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}

Last modified: 2020-07-03 13:12:34.

Top

datetime2 doesn’t recognise babel’s \babelprovide 🔗

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.

Last modified: 2020-07-03 13:16:13.

Top