Re: clean up date handling

[Ingo Schwarze <schwarze@usta.de>]

Hi,

this is how i propose to update the manuals:

 - Remove the "Dates" sections in both mdoc(7) and man(7).
   Basically, both languages use dates for one macro each,
   .Dd and .TH, so we can simply document dates there.
 - Regarding mdoc(7) .%D, it doesn't look like formatters
   do any checking, so don't talk about required formats,
   but do informally recommend the two sanest options.
 - Mark the date as required for both mdoc(7) and man(7),
   for two reasons:  Publishing a document without a date
   is a bad idea in general, and formatters tend to behave
   strangely when the date is missing.
 - For mdoc(7), document the proper format right in the .Dd
   synopsis.  Make it clear that anything else is not portable.
 - More details about mdoc(7) .Dd COMPATIBILITY.
 - In man(7), mark up argument placeholders as .Ar, not .Cm.

In case the code changes go in, is this OK as well?

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.65
diff -u -r1.65 mdoc.7
--- mdoc.7	7 Feb 2011 00:02:50 -0000	1.65
+++ mdoc.7	5 Mar 2011 00:00:31 -0000
@@ -197,34 +197,6 @@
 .Ed
 .Pp
 In free-form mode, quotes are regarded as opaque text.
-.Ss Dates
-There are several macros in
-.Nm
-that require a date argument.
-The canonical form for dates is the American format:
-.Pp
-.D1 Cm Month Day , Year
-.Pp
-The
-.Cm Day
-value is an optionally zero-padded numeral.
-The
-.Cm Month
-value is the full month name.
-The
-.Cm Year
-value is the full four-digit year.
-.Pp
-Reduced form dates are broken-down canonical form dates:
-.Pp
-.D1 Cm Month , Year
-.D1 Cm Year
-.Pp
-Some examples of valid dates follow:
-.Pp
-.D1 "May, 2009" Pq reduced form
-.D1 "2009" Pq reduced form
-.D1 "May 20, 2009" Pq canonical form
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
 stipulating a two-inch list indentation with the following:
@@ -886,8 +858,10 @@
 Publication date of an
 .Sx \&Rs
 block.
-This should follow the reduced or canonical form syntax described in
-.Sx Dates .
+Recommended formats of arguments are
+.Ar month day , year
+or just
+.Ar year .
 .Ss \&%I
 Publisher or issuer name of an
 .Sx \&Rs
@@ -1469,17 +1443,34 @@
 manual.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Dd Op Ar date
+.D1 Pf \. Sx \&Dd Ar month day , year
 .Pp
 The
-.Ar date
-may be either
-.Ar $\&Mdocdate$ ,
-which signifies the current manual revision date dictated by
+.Ar month
+is the full english month name, the
+.Ar day
+is an optionally zero-padded numeral, and the
+.Ar year
+is the full four-digit year.
+.Pp
+Other arguments are not portable; the
+.Xr mandoc 1
+utility handles them as follows:
+.Bl -dash -offset 3n -compact
+.It
+To have the date automatically filled in by
 .Xr cvs 1 ,
-or instead a valid canonical date as specified by
-.Sx Dates .
-If a date does not conform or is empty, the current date is used.
+the special string
+.Dq $\&Mdocdate$
+can be given as an argument.
+.It
+A few alternative date formats are accepted as well
+and converted to the standard form.
+.It
+If a date string cannot be parsed, it is used verbatim.
+.It
+If no date string is given, the current date is used.
+.El
 .Pp
 Examples:
 .Dl \&.Dd $\&Mdocdate$
@@ -2771,9 +2762,12 @@
 \*[hist]
 .It
 .Sx \&Dd
-without an argument prints
-.Dq Epoch .
-In mandoc, it resolves to the current date.
+with non-standard arguments behaves very strangely.
+When there are three arguments, they are printed verbatim.
+Any other number of arguments is replaced by the current date,
+but without any arguments, the string
+.Dq Epoch
+is printed.
 .It
 .Sx \&Fl
 does not print a dash for an empty argument.
Index: man.7
===================================================================
RCS file: /cvs/src/share/man/man7/man.7,v
retrieving revision 1.16
diff -u -r1.16 man.7
--- man.7	25 Jan 2011 00:37:39 -0000	1.16
+++ man.7	5 Mar 2011 00:00:31 -0000
@@ -118,15 +118,6 @@
 .Pp
 In macro lines, whitespace delimits arguments and is discarded.
 If arguments are quoted, whitespace within the quotes is retained.
-.Ss Dates
-The
-.Sx \&TH
-macro is the only
-.Nm
-macro that requires a date.
-The form for this date is the ISO-8601
-standard
-.Cm YYYY-MM-DD .
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
 stipulating a two-inch paragraph indentation with the following:
@@ -762,26 +753,27 @@
 Sets the title of the manual page with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&TH
-.Cm title section
-.Op Cm date Op Cm source Op Cm volume
+.Ar title section date
+.Op Ar source Op Ar volume
 .Ed
 .Pp
-At least the upper-case document
-.Cm title
-and the manual
-.Cm section
-arguments must be provided.
-The
-.Cm date
-argument should be formatted as described in
-.Sx Dates ,
-but will be printed verbatim if it is not.
-If the date is not specified, the current date is used.
-The
-.Cm source
+Conventionally, the document
+.Ar title
+is given in all caps.
+The recommended
+.Ar date
+format is
+.Sy YYYY-MM-DD
+as specified in the ISO-8601 standard;
+if the argument does not conform, it is printed verbatim.
+If the
+.Ar date
+is empty or not specified, the current date is used.
+The optional
+.Ar source
 string specifies the organisation providing the utility.
 The
-.Cm volume
+.Ar volume
 string replaces the default rendered volume, which is dictated by the
 manual section.
 .Pp
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv