* Opinions on .Dd? @ 2010-07-25 4:30 Sascha Wildner 2010-07-25 6:25 ` Ingo Schwarze 2010-07-25 8:37 ` Jason McIntyre 0 siblings, 2 replies; 8+ messages in thread From: Sascha Wildner @ 2010-07-25 4:30 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-25 4:30 Opinions on .Dd? Sascha Wildner @ 2010-07-25 6:25 ` Ingo Schwarze 2010-07-25 12:08 ` Sascha Wildner 2010-07-25 8:37 ` Jason McIntyre 1 sibling, 1 reply; 8+ messages in thread From: Ingo Schwarze @ 2010-07-25 6:25 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-25 6:25 ` Ingo Schwarze @ 2010-07-25 12:08 ` Sascha Wildner 2010-07-26 13:42 ` Kristaps Dzonsons 0 siblings, 1 reply; 8+ messages in thread From: Sascha Wildner @ 2010-07-25 12:08 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-25 12:08 ` Sascha Wildner @ 2010-07-26 13:42 ` Kristaps Dzonsons 2010-07-26 14:50 ` Jason McIntyre 0 siblings, 1 reply; 8+ messages in thread From: Kristaps Dzonsons @ 2010-07-26 13:42 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-26 13:42 ` Kristaps Dzonsons @ 2010-07-26 14:50 ` Jason McIntyre 2010-07-26 14:56 ` Kristaps Dzonsons 0 siblings, 1 reply; 8+ messages in thread From: Jason McIntyre @ 2010-07-26 14:50 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-26 14:50 ` Jason McIntyre @ 2010-07-26 14:56 ` Kristaps Dzonsons 2010-07-26 15:06 ` Jason McIntyre 0 siblings, 1 reply; 8+ messages in thread From: Kristaps Dzonsons @ 2010-07-26 14:56 UTC (permalink / raw) To: discuss >> 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-26 14:56 ` Kristaps Dzonsons @ 2010-07-26 15:06 ` Jason McIntyre 0 siblings, 0 replies; 8+ messages in thread From: Jason McIntyre @ 2010-07-26 15:06 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Opinions on .Dd? 2010-07-25 4:30 Opinions on .Dd? Sascha Wildner 2010-07-25 6:25 ` Ingo Schwarze @ 2010-07-25 8:37 ` Jason McIntyre 1 sibling, 0 replies; 8+ messages in thread From: Jason McIntyre @ 2010-07-25 8:37 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2010-07-26 15:06 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-07-25 4:30 Opinions on .Dd? Sascha Wildner 2010-07-25 6:25 ` Ingo Schwarze 2010-07-25 12:08 ` Sascha Wildner 2010-07-26 13:42 ` Kristaps Dzonsons 2010-07-26 14:50 ` Jason McIntyre 2010-07-26 14:56 ` Kristaps Dzonsons 2010-07-26 15:06 ` Jason McIntyre 2010-07-25 8:37 ` Jason McIntyre
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).