macro (document date) is the first macro in every mdoc(7)
document. This page discusses date formats in detail, in the order of decreasing preference.
Standard mdoc date format
In manuals for portable software, always use this format:
.Dd month day, year
This format works with mandoc, GNU troff, and the Heirloom Doctools.
Note that month
, and year
are separate arguments, and the comma follows the day
argument without intervening whitespace.
Giving the whole date as a single argument, for example by quoting it, is strongly discouraged. It fails with both GNU troff and Heirloom and only works with mandoc:
.Dd “month day, year” \" NOT PORTABLE!
Even though many other macros require giving punctuation as separate arguments, the Dd
macro does not accept that. Separating the comma from the day fails with both GNU troff and Heirloom and even misformats slightly with mandoc:
.Dd month day
OpenBSD base system date format
In OpenBSD base system manuals, always use this special format:
When committing, the cvs(1)
server will rewrite this line as follows:
.Dd $Mdocdate: month day year $
Note that this format does not
have a comma after the day
As usual with cvs(1)
, any text between the substitution keyword Mdocdate
and the trailing dollar sign is removed and replaced at commit time.
This format is not fully portable. It is fully supported by mandoc, but GNU troff only supports it since version 1.22.3 (November 2014), and the Heirloom Doctools don't support it at all.
Traditional man date format
In the past, many man(7)
pages used the traditional format:
-day \" NOT PORTABLE!
This format is no longer recommended. Neither GNU troff nor the Heirloom Doctools support it; only mandoc accepts it for backward compatibility.
While mandoc renders any non-empty arguments as given on the Dd
line, relying on that behaviour is strongly discouraged; it is not at all portable.
If they do not support the format, both GNU troff and the Heirloom Doctools show the current date instead of whatever arguments are given. When no arguments are given at all, even mandoc shows the current date.