Re: Mdocdate

["Dag-Erling Smørgrav" <des@des.no>]

Ingo Schwarze <schwarze@usta.de> writes:
> Dag-Erling Smørgrav <des@des.no> writes:
> >  - in a2time():
> > 
> >    Skip past "$Mdocdate: " if it exists instead of relying on the
> >    caller to specify it in the format string.
> No, that would introduce a bug.  The format is different depending
> on whether or not Mdocdate is used.  Maybe deplorable, but about a
> decade too late to change.  Well, it could be changed with a lot of
> churn in the tree, but for what benefit?  People don't need to type
> in the Mdocdate format manually, after all, and even if they do that
> and get it wrong, cvs(1) will helpfully fix it for them.

I would argue that's a feature.  My version will accept several
different formats for $Mdocdate$, including both the existing OpenBSD
format and the format which is possible to achieve with Subversion.

> >    Accept trailing text after a successful match (e.g. "$").
> Why?  That seems like a step backwards, weakening syntax validation.

Postel's law.  In this situation, you're not going for strict
validation, but for maximum flexibility.  You want to give the author
the benefit of the doubt, as long as you're reasonably sure that what
you saw is a date.

> >    If the first character after a successful match is 'Z', use UTC
> >    instead of the local time zone.
> That makes no sense.  Neither .TH nor .Dd syntax allows time formats
> more fine-grained than days, so it makes no sense to worry about
> time zones.

It can make a difference of ± 1 day if a) the commit date was close to
midnight or b) you are relatively close to the date line.  Subversion
timestamps are always in UTC and include the time followed by a Z.

> >  - in mandoc_normdate():
> > 
> >    Fix several logic errors (inverted tests),
> Err, what?  Can you be more specific?  I don't see any logic errors
> in there.  But your changes break several features.

Please explain how

 if (valid_date(str))
    /* we didn't find a valid date */ ;

is a feature.

> > add a test for the Subversion %d format,
> That is not valid mdoc(7) .Dd syntax, so it can't be added.

Says who?  Once again: Postel's law.

> >  - in the man page:
> >    Document how to use Mdocdate with Subversion.
> No.  Please don't introduce yet another format, use something like
>
>   Mdocdate="%b %d %Y "
>
> or whatever the subversion syntax is for svn:keywords.

That's not possible.  Mdocdate=%d is the closest you will get, otherwise
I wouldn't have needed this patch.

> > Given the following test cases:
> > [...]
> These are all invalid and must generate a warning.
> [...]
> These are valid, but not with Mdocdate.
> [...]
> Invalid.
> [...]
> Valid, but not with Mdocdate.
> [...]
> Invalid.

Once again: who says these dates shouldn't be accepted?  Is there some
sort of EU directive I'm not aware of that dictates the precise syntax
of a .Dd statement in an mdoc file?

>> The current code (1.13.3) produces the following output:
>> 
>> % while read d ; do echo ".Dd $d" | mandoc | tail -1 ; done <tests
>>                                 February 7 2036
>>                                 February 7 2036
>>                                February 07 2036
>>                                February 7, 2036
>>                                February 7, 2036
>>                                February 7, 2036
>>                                   Feb 7 2036
>>                                   Feb 7 2036
>>                                   Feb 07 2036
>>                                February 7, 2036
>>                                February 7, 2036
>>                                February 7, 2036
>>                                   2036-02-07
>>                                    2036-02-7
>>                                    2036-2-07
>>                                    2036-2-7
>>                                February 7, 2036
>>                        $Mdocdate: 2036-02-07 06:28:16Z $
>
> Yes, that is correct behaviour.

Not according to what you wrote earlier (the %Y-%m-%d forms should have
been accepted but were not due to the logic bugs I mentioned which you
claim are not bugs)

I must say I'm really surprised by your attitude.  You seem to value
rigid adherence to forty-year-old specifications over flexibility, ease
of use and compatibility with third-party systems, even when the latter
can be achieved without sacrificing the former.  That's laudable when
you're implementing TLS or a message parser in a SOLAS system, but not
when you're writing a text preparation system.  You'll just end up
driving even more people away from mdoc and towards DocBook or Doxygen
or whatever the flavor of the month is, for absolutely no benefit.

DES
-- 
Dag-Erling Smørgrav - des@des.no
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv