Date: 09 Oct 2002 12:56:51 -0700 From: swear@attbi.com (Gary W. Swearingen) To: Adam Weinberger <adam@vectors.cx> Cc: freebsd-questions@FreeBSD.ORG Subject: Re: help with ln "linking" Please! [attn manpage authors!] Message-ID: <4bvg4b4c8s.g4b@localhost.localdomain> In-Reply-To: <20021009093847.GJ81796@vectors.cx> References: <vgfzvg5acm.zvg@localhost.localdomain> <200210090909.g9999CW2083670@lurza.secnetix.de> <20021009093847.GJ81796@vectors.cx>
next in thread | previous in thread | raw e-mail | index | archive | help
Adam Weinberger <adam@vectors.cx> writes: > >> (10.09.2002 @ 0209 PST): Oliver Fromme said, in 1.2K: << > > Gary W. Swearingen <swear@attbi.com> wrote: > > > ln [-fhinsv] linked_filename [link_filename] > > > ln [-fhinsv] linked_filename ... dir_filename > > > link existing_filename alternate_filename > > "linked" should be avoided. this is the exact problem the current > documentation has. linked from? linked too? The difference between "link" and "linked" seems clear enough to me, but I expected complaints. See below for another try. > i'd explain it like this: i'd give the synopsis, then an immediate > example. i'd LOVE to see a quick sample USEFUL and most common > invocation of a short command right there in the synopsis section. i > think many such utilities' manpages should do that. That might be good, but the convention woule be too likely to be abused, making a messes of synopsis sections. If the help system was improved, one could link to the examples section right up front, for those that want to see them. (I'm sorry that "info" wasn't popular enough to replace manual pages.) But it's easy enough to skip to the Examples section. You're welcome to add one for ln(1), preferably after this change gets through. > ln [-b0rk] link_to [link_from] Of course "link_to" isn't a link. Also, I'd rather see argument names name or describe something rather than seeming to instruct the command. The actual argument (as opposed to the name of the argument) can, of course, be almost anything including instructions to the command. Maybe any use of "link" tends to confuse some readers. And "Link" is already built into the command name. How about: ln [-fhinsv] to_filename [from_filename] ln [-fhinsv] to_filename ... dir_filename link existing_filename alternate_filename The first one's arguments are both descriptive and the whole command reads fairly naturally as a command to the OS. The last one's arguments are different than the first's because it adds helpful information while remaining clear as to what it does (he says). (The info: The first argument's file must exist. The command makes an alternate filename in the directory for what is only one file. This command doesn't create something which is distinguishable as a "link".) To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4bvg4b4c8s.g4b>