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
- 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)?).
- How do I write a datetime2 language module?
- Unexpected Output
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.
Last modified: 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.
Last modified: 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.
Last modified: 2020-07-03 12:24:27.
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.
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.styneeds to be replaced with
\DTMdisplaydate{2014}{3}{28}{-1}% datetime2.styor
\DTMdate{2014-3-28}% datetime2.styNote 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.styto
\DTMsavedate{mydate}{2015-03-28}% datetime2.styUsing the dates has changed from:
\displaydate{mydate}% datetime.styto
\DTMusedate{mydate}% datetime2.sty
Last modified: 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.
Last modified: 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.
Last modified: 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.
Last modified: 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 \fiIf you are writing a language module, you need to define
\DTM
langweekdayname
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 \DTM
langWeekdayname
for first letter upper case version, \DTM
langshortweekdayname
and \DTM
langshortWeekdayname
for abbreviated versions, if required.)
If the week or month names include non-ASCII characters, there should be an ASCII version of \DTM
langweekdayname
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.
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.
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.
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.
Last modified: 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 \date
language 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.
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.