Date: Mon, 23 Jul 2001 15:04:27 +0300 From: Ruslan Ermilov <ru@FreeBSD.org> To: Mike Pritchard <mpp@mppsystems.com> Cc: cvs-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.1 example.3 example.4 Message-ID: <20010723150427.F90121@sunbay.com> In-Reply-To: <20010723053004.B34672@mppsystems.com>; from mpp@mppsystems.com on Mon, Jul 23, 2001 at 05:30:04AM -0500 References: <200107181004.f6IA4YU17817@freefall.freebsd.org> <20010722041441.B1683@mppsystems.com> <20010723123509.B79427@sunbay.com> <20010723053004.B34672@mppsystems.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jul 23, 2001 at 05:30:04AM -0500, Mike Pritchard wrote: > 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. > See style(9). Please send me a beer. :-) > > 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. > Or "blindly" used? > 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. > The fact that these people removed a comment surrounding a $FreeBSD$ tag but did not remove the comment preceding the .Dd line sounds to me like people know what the $FreeBSD$ thing is, but don't probably bother for .Dd. Uhh, too many assumptions. > 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. > Sure, I understand that these are skeletons. But if we ever need the comment surrounding the $FreeBSD$ like here, it should be reformulated. When this comment was first written, I bet commit_prep.pl did not require the $FreeBSD$ tag, and the only valid reason was: .\" Note: All FreeBSD man pages should have a FreeBSD revision .\" control id to make it easier for translation teams to track .\" changes. But now this is enforced by commit_prep script. If anyone has a better wording about $FreeBSD$, documenting that it should be empty for a new manpage, and this comment should be removed when template is applied, I am 100% would be comfortable with this change. Sorry, I am going on a vacation tomorrow, so I won't be able to do it myself. I'm sure you can do this, Mike. Cheers, -- Ruslan Ermilov Oracle Developer/DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age 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?20010723150427.F90121>