Date: Mon, 23 Jul 2001 05:30:04 -0500 From: Mike Pritchard <mpp@mppsystems.com> To: cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.1 example.3 example.4 Message-ID: <20010723053004.B34672@mppsystems.com> In-Reply-To: <20010723123509.B79427@sunbay.com>; from ru@FreeBSD.org on Mon, Jul 23, 2001 at 12:35:09PM %2B0300 References: <200107181004.f6IA4YU17817@freefall.freebsd.org> <20010722041441.B1683@mppsystems.com> <20010723123509.B79427@sunbay.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jul 23, 2001 at 12:35:09PM +0300, Ruslan Ermilov wrote: > On Sun, Jul 22, 2001 at 04:14:41AM -0500, Mike Pritchard wrote: > > > Modified files: > > > share/examples/mdoc example.1 example.3 example.4 > > > Log: > > > Removed the comment that required all FreeBSD manpages > > > to have the $FreeBSD$ keyword, as this is now enforced > > > by the CVSROOT/commit_prep.pl script. > > > > I think there should still be a comment stating that the FreeBSD id should > > be present. Remember, these examples are intended to be taken and > > edited by others to create new man pages. Since most people do > > not regularly create new files and add them to the repository, > > keeping the comment about the FreeBSD id line (and show where it should > > be placed in the man page) will help them from having commit_prep > > complain at them when they finally do try and check their new man > > page in. > > > The (already existing) $FreeBSD$ in these examples is self-documenting. > If people don't know that commit-prep.pl will complain about missing > $FreeBSD$ line, they are probably also not aware of the fact that > commit-prep.pl will only accept an uninitialized $FreeBSD$, so the > one from skeleton is bogus anyway. :-) An RCSID is self documenting? Since when? I remember when I first started out working with Unix (or is it UNIX? -:), all of the code I saw had something like this in it: #ifndef lint #if 0 static char sccsid[] = "@(#)ls.c 8.5 (Berkeley) 4/2/94"; #else static const char rcsid[] = "$FreeBSD: src/bin/ls/ls.c,v 1.45 2000/08/13 12:17:03 joe Exp $"; #endif #endif /* not lint */ I had *NO* idea what it was for, but I added something similar to all the code I wrote at the start of my Unix days. I later learned why that code was there (and why my adding it without actually using sccs or rcs made it all but moot), but at the time I had no idea. The comments should be fixed to tell the person how commit-prep expects the FreeBSD id line to appear for a new file and why it is there. That is what examples are for. I'm willing to bet a beer to anyone who can show me some actual freebsd documentation, other than the old example man pages, about why we have $FreeBSD$ lines in our files. Pointers to something in the mailing lists don't qualify. > And some of these gratuituous comments are erroneously imported when > a template is applied. > > grep "Note: The date here should be updated" reveals these: > > lib/libc/db/man/dbm.3 > share/examples/mdoc/example.1 > share/examples/mdoc/example.3 > share/examples/mdoc/example.4 > sys/boot/common/loader.8 > sys/boot/i386/pxeldr/pxeboot.8 3 of the above are the example man pages themselves, so they don't count :-). At least this proves that 3 people have used the example man pages to create their own new man pages. I always wondered if anyone actually used them. And if a few extra helpful comments get included by someone using these template man pages, so what? It isn't a big deal. If someone decides to take that man page and turn it into something new, at least they have a little extra info they didn't have if they never looked at the example man pages. When I originally wrote the share/examples/mdoc/example.* man pages, it was because a lot of people asked me "where do I begin? I never wrote a man page before, but 'man xyzzy' is almost what I want, but not quite. All I need is a nice skeleton I can work from and then start adding." That is how the example man pages came to be. -Mike -- Mike Pritchard mpp@FreeBSD.org or mpp@mppsystems.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010723053004.B34672>