Re: Opinions on .Dd?

[Kristaps Dzonsons <kristaps@bsd.lv>]

>> 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)?
>>
> 
> yes, one of the original problems was that you could never be sure what
> the date related to. some said it was for when the page was created
> (which i felt was useless), others that it got bumped only on
> "significant" updates, and so on.
> 
>> 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.)
>>
> 
> what do you mean it accepts no arguments? it accepts the date. and does
> it really print "Epoch"? i thought if you messed the date up it just
> printed the current date. maybe i am wrong about that though.

Yes:

% cat foo.3
.Dd
.Dt FOO 1
.Os
.Sh NAME
.Nm foo
.Nd bar
.Sh DESCRIPTION
Moo.
% nroff -mandoc foo.3
FOO(1)             BSD General Commands Manual            FOO(1)

NAME
     foo - bar

DESCRIPTION
     Moo.

BSD                           Epoch                          BSD

(Note groff output chopped, as they don't have our awesome -Owidth
argument.)  This is on GNU/Linux (groff 1.18.1).  I also tested on
OpenBSD and NetBSD.  Same.

If you enter an invalid string, say, `.Dd urgle', then you get the
current date.

> even so, i think it would be great to print "Epoch". there is no
> difference between "Epoch" and "", except a little humour.

I actually think it's a bug.

What I was getting at, regarding (e.g.) DFBSD and what to put in the
`Dd' field, is maybe they're best off leaving it blank.

>> 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?
>>
> 
> this ties in with how do we handle OS differences... different pages, or
> a single page which notes differences. the latter might seem sane, but
> it could make the page unwieldy.

Single page, I think.  Are there really so many differences?

Thanks,

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