Date: 14 Dec 2002 10:52:34 -0800 From: swear@attbi.com (Gary W. Swearingen) To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: freebsd-doc@FreeBSD.org Subject: Re: layered file systems ... Message-ID: <tw65twjuvh.5tw@localhost.localdomain> In-Reply-To: <20021214082058.GC19785@gothmog.gr> References: <20021213095811.A13175-100000@hub.org> <20021213151455.GD92171@blazingdot.com> <20021213113108.B13175-100000@hub.org> <20021213162521.GA96011@blazingdot.com> <20021213133130.S13175-100000@hub.org> <8lel8lk398.l8l@localhost.localdomain> <20021214082058.GC19785@gothmog.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
(Moved to -doc from -questions.) Giorgos Keramidas <keramida@ceid.upatras.gr> writes: > I do remember the thread, but a quick search in my ~/mail archive > didn't show anything about it. An old date in a manpage doesn't > necessarily mean that its text is old. The misunderstanding you > described is valid, but the .Dd tag has been used for 'major > revisions' of the manpages since a long time AFAIK. Which is an even worse practice than "original version", IMO. (And I know that this issue is all about opinion. It's good of you to be considering mine.) The situation is made worse by the absense of a written policy, so that many seemingly-old manpages have very recent dates and many have very old dates, rendering the displayed date worse than useless. > "Some users might be confused" is not a good enough reason for merging > the two date fields, since losing information is bad, but answering a > few questions like "are my manpages old?" once in a while is not > really bad :) What IS bad is a bad impression. Looks matter. This is mostly a "looks" issue. Long-time users know the footer-displayed date is unreliable and know how to find better info. The only people who care about the displayed date are the ignorant newbies and visitors who haven't yet learned to ignore it. They think it indicative of old or broken documentation. These "image" issues are part of "marketing" FreeBSD and as such should resolve around the relatively few people who are in the market for the first time or who might switch brands. These footers (of "ls" and "ps") are bad: FreeBSD 5.0 May 19, 2002 FreeBSD 5.0 FreeBSD 4.6 April 18, 1994 FreeBSD 4.6 They look to the uninformed like dates of the OS release. The one from "ps" obviously isn't the OS date, but the next most obvious assumption is that the manpage hasn't been updated since 1994. And assumptions are important when it comes to newbies; the "man" manpage doesn't even mention dates or footers. Ideally, manpage footers would display a very specific indication of what they are documenting. Eg, Groff Version 1.17.2 6 August 2001 GROFF(1) But since that's too much work for FreeBSD manpages, a practical solution is to not display any date at all. Let users assume that the manpage is current and explain in the "man" manpage that if users want to know the creation and revision history of a manpage, they should first look in the "History" section of the manpage and then look into the source or use the CVS webforms at freebsd.org. And, in the "mdoc" manpage, suggest that authors/maintainers put manpage's history info in the manpage's "History" section. There's no need to loose any info. Furthermore, a ".Dd = last major revision" policy DOES loose info. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?tw65twjuvh.5tw>