Re: Opinions on .Dd?

[Ingo Schwarze <schwarze@usta.de>]

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