Date: Thu, 1 Jul 1999 12:44:30 -0700 (PDT) From: Doug <Doug@gorean.org> To: Tim Vanderhoek <vanderh@ecf.utoronto.ca> Cc: Doug <Doug@gorean.org>, freebsd-ports@FreeBSD.org, nik@nothing-going-on.demon.co.uk Subject: Re: ports/12463: Update: Fvwm2 to 2.2.2 Message-ID: <Pine.BSF.4.05.9907011229590.13256-100000@dt054n86.san.rr.com> In-Reply-To: <19990701152359.C48778@mad>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 1 Jul 1999, Tim Vanderhoek wrote: > On Thu, Jul 01, 1999 at 02:09:22PM -0400, Doug wrote: > > > > > The "A " seems to add very little to the comment. > > > > It adds nothing to the comment, but it does add a great deal of > > readability for just two characters. My vote == bad idea. s/comment/content/ > Are you reading it in context, or are you just reading the comment? I've done several ports myself, so I feel qualified to judge it in context. In particular, the COMMENT is most important (IMO) in the sysinstall case, where they are viewed one at a time. I submit that you are looking at them en masse, which a typical user would never do. > Try having a look through one of the categories at > http://www.FreeBSD.org/ports/. It's not so bad now because a lot of > the ports don't include a preceeding "A" or similar, but notice that > reading them quickly becomes annoying (not at first, though). I didn't see anything wrong with the examples you quoted. > And notice that it's possible to add "A " to a _lot_ of the comments > that currently don't have it, using the same argument that use just > used. *Nod* There are a lot of things that you could add or subtract if you really wanted to. This is why I believe that within reasonable limts you should leave it up to the port author. I believe that "start with a cap" is a reasonable limit, and "no period at the end" probably is too. I don't believe that legislating the use of articles at the beginning of the sentence adds utility in comparison to the pita factor of trying to enforce it. > But, read the comments in the games category. Notice that it's > possible to add "A " in front of virtually every comment. Every > comment. I'm not convinced that doing so would increase the > readability one bit. > > The ideal pkg/COMMENT, I think, is a type of verb phrase, in the > imperitive. > > [462]luna-1.9 > Display her phase This comment is inadequate on several levels. A better example would be, "Display the current phase of the moon". > [585]unclutter-8 > Remove idle cursor image from screen Should be, "Removes an idle cursor image from the screen". > [1396]wget-1.5.3 > Retrieve files from the 'net via HTTP and FTP Should be, "Retrieves . . ." etc. The examples you quote are improper uses of the imperative mood. > As an example of a verb phrase using the wrong tense, > > [1290]tcplist-2.2 > Lists tcp connections to/from the local machine (+username on > both sides) Hmmm... I'm not sure what you mean here. > I'm willing to accept that I'm just unusual with respect to really > detesting all the "A "s, but you've got to work a little harder than > that to convince me. My main point is that having the A/An there DOES improve the readability, at a very low cost. I don't see a compelling reason to change them one way (all A's) or the other (no A's). We have more than enough examples of crusty, uniform techno-speak in the system now, there is no reason not to allow a little creativity/variety in an area that has no signficant impact one way or the other. > I'm also considering that maybe I should've made an exception and not > capitalized "perl5" when it appears at the start of a comment. My understanding from the Perl FAQ is that the proper punctuation should be, "Perl 5". Regards, Doug -- On account of being a democracy and run by the people, we are the only nation in the world that has to keep a government four years, no matter what it does. -- Will Rogers To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-ports" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.05.9907011229590.13256-100000>