Opinions on .Dd?

Opinions on .Dd?

[Sascha Wildner]

Hi,

what is people's thought on .Dd in general?

Personally, I've thought about nuking it more than once. Most developers 
forget to update it and honestly both running after people and reminding 
them as well as keeping them up to date myself are a pain.

Also, at least in DragonFly, I see no real benefit in keeping it up to 
date, since nobody goes and checks the date on manpages to decide which 
are worth looking through for new stuff.

We also don't have translations of manpages so that the translators 
would use the date for finding out which need to be checked for 
translating. This was the reason given to me when I asked about .Dd on 
the FreeBSD lists once.

My more specific question is: Would this be possible with mdocml? It 
seems to take .Dd as an indicator for the beginning of the title part so 
I assume not. But then, it's not the latest mandoc(1) I'm using here and 
maybe things have changed.

Regards,
Sascha
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Opinions on .Dd?

[Ingo Schwarze]

Hi Sascha,

Sascha Wildner wrote on Sun, Jul 25, 2010 at 06:30:29AM +0200:

> what is people's thought on .Dd in general?

While there are some mdoc(7) features that are handled differently
by different operating system variants, .Dd so far is one of those
where there is consensus that it is required, and what it means.

I admit conventions differ slightly on how to format the date line:
While OpenBSD uses the Mdocdate mechanism to automatically insert
the date on commit, NetBSD and FreeBSD do not.

This difference is not a problem because mandoc and groff handle
both conventions.  Thus, you can format OpenBSD manuals on NetBSD
and FreeBSD and Linux and vice versa without using a special binary
or special options.

Thus, the situation with respect to .Dd is fine right now.

> Personally, I've thought about nuking it more than once.

Hm, frankly, i recommend against that.  That would break well-
established syntax, weakening portability of DragonFly manuals.
While it would certainly be possibly (though ugly!) to deal with
it in mandoc(1) in the future, you might also wish to consider
compatibility with operating systems that don't provide mandoc
at all.  Some are using groff, some are still using traditional
System V nroff/troff descendants, and you will hardly convince
all of those people to deal with changes of basic mdoc(7) syntax
introduced in DragonFly.  Breaking established syntax at this place
would be particularly bad because it would result in DragonFly
manuals no longer being recognized as mdoc(7) manuals at all...

For example, when i remove the .Dd line from an mdoc(7) manual
on Linux and explicitely call nroff -mdoc, it still works, but
with nroff -mandoc, it is no longer recognized and output is
completely clobbered.  Good luck convincing Werner Lemberg to spend
his time changing that, and after convincing him, be prepared to
wait some years for all distributions to pick it up...  :-/

> Most developers forget to update it and honestly both running after
> people and reminding them as well as keeping them up to date myself
> are a pain.

Right, i understand the problem, and certainly such issues are the
worse the smaller a project is in terms of the number of active
developers.  Developer time is often a scarce resource, both for
hacking and for communication.

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...

> Also, at least in DragonFly, I see no real benefit in keeping it up
> to date, since nobody goes and checks the date on manpages to decide
> which are worth looking through for new stuff.

I admit the usefulness of the date in the footer is marginal:
In particular, it doesn't mean that the page was completely
accurate at that date.  Maybe somebody only fixed a typo on that
date.  The main advantage seems to be that you can figure out
the version in case people mail manuals around, which indeed
doesn't happen that often.

> We also don't have translations of manpages

*shudder*

[...]
> This was the reason given to me when I asked about .Dd
> on the FreeBSD lists once.

I have a hard time buying that it would be needed or even helpful
for that purpose.  I mean, when the last checkin in the master repo
is more recent than the last checkin in the translation repo, you
need to check the translation, right?  The .Dd macro, on the other
hand, is not reliable; what if the developer updating the manual
forgot about the .Dd line?  What if there were several checkins
on the same day?

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Opinions on .Dd?

[Sascha Wildner]

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. :)

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

Re: Opinions on .Dd?

[Kristaps Dzonsons]

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

Re: Opinions on .Dd?

[Jason McIntyre]

On Mon, Jul 26, 2010 at 03:42:34PM +0200, Kristaps Dzonsons wrote:
> 
> 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.

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

> 
> 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.

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

Re: Opinions on .Dd?

[Kristaps Dzonsons]

>> 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

Re: Opinions on .Dd?

[Jason McIntyre]

On Mon, Jul 26, 2010 at 04:56:42PM +0200, Kristaps Dzonsons wrote:
> 
> % 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.
> 

ah. i like it!

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

ah, ok. just w/o args gets you Epoch. i was confused because i thought
you were trying to say that Dd did not accept arguments.

> > 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.
> 

well, it's a great one. please don;t remove it. "Epoch" is exactly the
correct thing to do.

> 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 don;t see the point of that. a ton of work to make things less useful.

> > 
> > 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?
> 

my previous mail listed some between netbsd and openbsd. there are
probably not too many, i think, but that doesn;t mean there won;t be
more. single page is the easiest way to go for sure. but like, will
freebsd dudes want a list of openbsd's differences in their man page(s)?
and vice versa?

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

Re: Opinions on .Dd?

[Jason McIntyre]

On Sun, Jul 25, 2010 at 06:30:29AM +0200, Sascha Wildner wrote:
> Hi,
> 
> what is people's thought on .Dd in general?
> 
> Personally, I've thought about nuking it more than once. Most developers 
> forget to update it and honestly both running after people and reminding 
> them as well as keeping them up to date myself are a pain.
> 
> Also, at least in DragonFly, I see no real benefit in keeping it up to 
> date, since nobody goes and checks the date on manpages to decide which 
> are worth looking through for new stuff.
> 

my thoughts are "i sympathise" ;)

openbsd uses an mdocdate tag now, which takes all the work out it. but
before that, my attitude was to ignore it - if people update it, fine;
if not, it's not worth worrying about.

but it is useful. even if it doesn;t tell you anything exactly, it gives
an impression that, say, no one has touched this page for seven years. i
think a date can be useful for readers.

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