Date: Tue, 12 Jun 2001 12:43:04 -0700 From: dannyman <dannyman@toldme.com> To: Andrew McKay <andy@openirc.co.uk> Cc: Nik Clayton <nik@FreeBSD.org>, freebsd-doc@FreeBSD.org Subject: Re: Porter's Handbook ambiguity Message-ID: <20010612124304.D99558@toldme.com> In-Reply-To: <Pine.BSF.4.21.0106122009090.397-100000@fluoxetine.openirc.co.uk>; from andy@openirc.co.uk on Tue, Jun 12, 2001 at 08:23:57PM %2B0100 References: <01061214251500.37769@clan.nothing-going-on.org> <Pine.BSF.4.21.0106122009090.397-100000@fluoxetine.openirc.co.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Jun 12, 2001 at 08:23:57PM +0100, Andrew McKay wrote: > I was trying to point out that, whilst clarification is probably possible > in pretty much every page of the documentation, at some point you have to > draw a line on how much hand-holding you give users. This 'problem' was > apparent in the Porter's Handbook. I don't think it's unreasonable to > expect anybody who is intending to use the information in the porter's > handbook (i.e. people intending to make ports) to be able to install a > port from the ports collection with relative ease. After cvsup it was the > first thing I learnt to do in my FreeBSD career. I'm all for encouraging > people to submit ports (and anything else) to the project but shouldn't > they first know how to install ports? Or am I missing something? I have a degree in English Rhetoric, and I have been installing and submitting the occasional port for more than half a decade now. I was confused by the wording. As an experienced user, the text could be phrased more clearly. As an experienced user I hit up the appropriate mailing lists, and I know intend to submit a PR to propose a fix to that section of the manual. It is indeed possible that I was confused because of my experience, as I read "part of the ports system" and "is a port" or "in the ports tree" as two different concepts. Not all of us have dug around in /usr/ports/Mk before and understand "the ports system" as more than the ports in that system. :) > Also, if every instance of '<foo> can be installed from the ports > collection' is changed to some more verbose description of how to acheive > this then a) the documentation becomes bloated (unnecessarily imho) and b) > what's the point of section 4 of the FreeBSD handbook which explains in > depth how to install ports? And where exactly do you pitch the level of > verbosity? Do you include information on how to cvsup ports in case their > local copy is not up to date? I never proposed to clarify every instance. I stated that I had been confused by this single instance, and that things could be better worded. It is now on my head to send the PR. If you want to complain about more ambituous projects, you can undertake them first. Then your bleating will be warranted. Perhaps in "The Porter's Handbook" the distinction between "in the ports system" and "is a port" is more sensitive than in other documentation. -danny 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?20010612124304.D99558>