Re: Opinions on .Dd?

[Kristaps Dzonsons <kristaps@bsd.lv>]

Sascha Wildner wrote:
> On 7/25/2010 8:25, Ingo Schwarze wrote:
>> Maybe porting Mdocdate to DragonFly cvs might help you:  I think
>> is solves exactly the problem you describe.  I just checked on
>> Linux, non-OpenBSD groff auto-detects pages containing Mdocdate
>> as mdoc(7) and formats them nicely.  I'm sorry i don't have a
>> Solaris box and can't check there...
> 
> Well, DragonFly uses git and afaik OpenBSD's way is implemented in rcs.
> 
> Yeah supports as in "just takes today's date if the string makes no
> sense to it". You can write .Dd foo or .Dd $Mdocdate$, doesn't matter.
> mdocml seems to follow this convention.
> 
> I guess the proper way of "nuking .Dd" would probably be to leave it in
> but just "officially" don't care about it any longer, as in, don't
> bother people any longer to update it and tell them "update it if you
> like, but we don't require you to". And explicitly putting something
> else there instead of a date (so the "today's date" default kicks in)
> just to make that point seems silly too.
> 
> Aside from the portability problems, deciding to remove it entirely also
> would just shift the "I have to bother everyone to update it" problem to
> "I have to bother everyone to remove it from imported manual pages", so
> there is no big gain, even if removing it was portable.
> 
> Believe it or not, it's already a comforting thought that others
> sympathize. :)

I think I have no opinion either way, although my first thought was
"burn the witches!" "`Dd' forever!".

Second thought: a manual date is in general ambiguous.  What does it
mean?  Last edit time?  Last checkin?  And what does it matter,
considering it usually can't be corroborated with corresponding binary
(or whatever)?

OpenBSD is the exception, as Mdocdate is used unilaterally.

So I dug around and found that `Dd' accepts no arguments.  It prints
"Epoch" in place of a date (wtf?).  I think an empty `Dd' is less
ambiguous than a bogus date.  (I'm now committing a fix to the effect
that `Dd' can be empty.)

Either way, the mdoc.7 manual explicitly states that only cvs(1) works
with $Mdocdate$, so it's clear it won't work with svn or git.

I'm happy with putting some notes to the extent of "Usage of the `Dd'
field is usually one of convention" and listing that OpenBSD exclusively
uses $Mdocdate$, whilst a general-purpose manual should use a hard-coded
or empty date.

Thoughts?

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv