Date: Sat, 6 Feb 2016 17:16:35 -0800 From: Kevin Oberman <rkoberman@gmail.com> To: "Greg 'groggy' Lehey" <grog@freebsd.org> Cc: "ports@FreeBSD.org" <ports@freebsd.org> Subject: Re: Removing documentation (was: [Bug 206922] Handbook: Chapter 4.5+ changes) Message-ID: <CAN6yY1vcdXfs_Lwbcfcd8JUgK_LNjXwZzKNzoz2-DBjeM%2BBXcA@mail.gmail.com> In-Reply-To: <20160207000304.GA71035@eureka.lemis.com> References: <bug-206922-273-PXN38rlW5F@https.bugs.freebsd.org/bugzilla/> <bug-206922-273-YnY5vf8jP1@https.bugs.freebsd.org/bugzilla/> <bug-206922-273-kkQfWZPv1w@https.bugs.freebsd.org/bugzilla/> <20160207000304.GA71035@eureka.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, Feb 6, 2016 at 4:03 PM, Greg 'groggy' Lehey <grog@freebsd.org> wrote: > I'm bringing this to the attention of the ports community to try to > come up with a consensus about how to handle existing documentation > for ageing packages, in this case portmaster. > > This bug report suggests removing the documentation for portmaster > because it is out of date and no longer maintained. > > But it's still in the ports tree, and people still use it. The > current wording (4.5.3.1) claims it is the recommended tool, which is > clearly out of date. marino@ (the submitter) writes: > > On Friday, 5 February 2016 at 7:33:33 +0000, > bugzilla-noreply@freebsd.org wrote: > > > > You have a tool presented as "official" that hasn't had it's > > original maintainer in 4 years and was only kept on life support up > > until 9 months ago. > > Agreed, the "official" (the term used is "recommended") status is > gone. But that's a reason to fix the documentation, not remove it. > As I see it, we have three choices, in increasing order of > desirability: > > 1. Remove all mention of portmaster. That's what this PR recommends. > 2. Do nothing. > 3. Update the documentation to indicate the current status, > recommending alternatives if possible. > > The real issue here is that we shouldn't remove documentation for > software that is still available. In addition, wblock@ writes: > > On Friday, 5 February 2016 at 14:48:07 +0000, > bugzilla-noreply@freebsd.org wrote: > > > > At present, portmaster still has no direct competition... > > More generally, the way I see it is simple: we should try to keep the > documentation as up-to-date as possible. This means that we don't > remove documentation for existing packages. It also means that we may > need to change the content of the documentation if the status (not > necessarily the content) of the package changes. > > One of the arguments for removing it from the handbook is that it has > a man page. That has some merit, but it doesn't help the people who > have used portmaster and now don't know what to do. Even if portmgr > is deprecated, the documentation should suggest a replacement. > > Can portmgr@ come up with a clear, easy-to-understand policy? > > Greg > I am not portmgr, but do use portmaster for updating ports on systems running STABLE or HEAD. I still see no tool which provides the features of portmaster. I also realize that this is far from a universal opinion. I believe that the issue of it having a man page is completely irrelevant. The handbook covers pkg, portsnap, and freebsd-update, all of which have very comprehensive man pages and are covered in the handbook because man pages and the handbook serve very different purposes. Every port should have a man page, though I understand why many lack one and ports that support the basic management of a system belong in the handbook. When multiple and popular tools are available for the same job, it would be good to summarize any different capabilities that might make one preferred over another. Of course, someone has to write it. :-( -- Kevin Oberman, Part time kid herder and retired Network Engineer E-mail: rkoberman@gmail.com PGP Fingerprint: D03FB98AFA78E3B78C1694B318AB39EF1B055683
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAN6yY1vcdXfs_Lwbcfcd8JUgK_LNjXwZzKNzoz2-DBjeM%2BBXcA>