From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o6P6PAIp029572 for ; Sun, 25 Jul 2010 02:25:12 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1Ocue5-0004tx-7Y; Sun, 25 Jul 2010 08:25:09 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.71) (envelope-from ) id 1Ocue5-0002KW-65 for discuss@mdocml.bsd.lv; Sun, 25 Jul 2010 08:25:09 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1Ocue5-0008LT-3v for discuss@mdocml.bsd.lv; Sun, 25 Jul 2010 08:25:09 +0200 Received: from schwarze by usta.de with local (Exim 4.71) (envelope-from ) id 1Ocue5-00028p-39 for discuss@mdocml.bsd.lv; Sun, 25 Jul 2010 08:25:09 +0200 Date: Sun, 25 Jul 2010 08:25:09 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: Opinions on .Dd? Message-ID: <20100725062509.GA22919@iris.usta.de> References: <4C4BBDE5.8020901@online.de> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4C4BBDE5.8020901@online.de> User-Agent: Mutt/1.5.20 (2009-06-14) 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