From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p250Fj4f015285 for ; Fri, 4 Mar 2011 19:15:47 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1Pvf9o-0005ir-NP; Sat, 05 Mar 2011 01:15:43 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Pvf9o-0000dU-TI; Sat, 05 Mar 2011 01:15:40 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1PvfA8-0007h3-Q5; Sat, 05 Mar 2011 01:16:00 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1Pvf9o-000234-RO; Sat, 05 Mar 2011 01:15:40 +0100 Date: Sat, 5 Mar 2011 01:15:40 +0100 From: Ingo Schwarze To: tech@mdocml.bsd.lv Cc: Tim van der Molen , jmc@openbsd.org Subject: Re: clean up date handling Message-ID: <20110305001540.GC21838@iris.usta.de> References: <20110304001451.GA8690@iris.usta.de> <20110304222437.GA21838@iris.usta.de> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20110304222437.GA21838@iris.usta.de> User-Agent: Mutt/1.5.21 (2010-09-15) 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