I think `tar` is a great analogy for date formatting -- "Here is a few examples, one of which is probably what you want."
`tar cvzf archive_to_write.tar.gz dirname`
`tar xvf archive_to_unpack.tar`
Cf
"%Y-%m-%d %H:%M:%S" -> "2001-01-31 23:59:61"
That's a nice example. A four digit year, an hour past 12, months padded, two leap seconds. (:00 would be good for seconds too, as would 01 for the day.)
Maybe a short note, then next example -- 12 hour clocks, AM/PM, string months, truncated year. Then the next example, maybe this "week-based" date format. Or maybe just leave that for the end "reference" section.
Lead with two or three short examples that cover 95% of usage. It'll make the document a handful of lines longer, but it'll save these bugs and it'll save people time.
`tar cvzf archive_to_write.tar.gz dirname`
`tar xvf archive_to_unpack.tar`
Cf
"%Y-%m-%d %H:%M:%S" -> "2001-01-31 23:59:61"
That's a nice example. A four digit year, an hour past 12, months padded, two leap seconds. (:00 would be good for seconds too, as would 01 for the day.)
Maybe a short note, then next example -- 12 hour clocks, AM/PM, string months, truncated year. Then the next example, maybe this "week-based" date format. Or maybe just leave that for the end "reference" section.
Lead with two or three short examples that cover 95% of usage. It'll make the document a handful of lines longer, but it'll save these bugs and it'll save people time.