From owner-freebsd-ports@freebsd.org Sun Feb 7 00:11:30 2016 Return-Path: Delivered-To: freebsd-ports@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 949E3AA0EFA for ; Sun, 7 Feb 2016 00:11:30 +0000 (UTC) (envelope-from grog@lemis.com) Received: from mailman.ysv.freebsd.org (mailman.ysv.freebsd.org [IPv6:2001:1900:2254:206a::50:5]) by mx1.freebsd.org (Postfix) with ESMTP id 7A28C1039 for ; Sun, 7 Feb 2016 00:11:30 +0000 (UTC) (envelope-from grog@lemis.com) Received: by mailman.ysv.freebsd.org (Postfix) id 78484AA0EF9; Sun, 7 Feb 2016 00:11:30 +0000 (UTC) Delivered-To: ports@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 5E493AA0EF8 for ; Sun, 7 Feb 2016 00:11:30 +0000 (UTC) (envelope-from grog@lemis.com) Received: from www.lemis.com (www.lemis.com [208.86.226.86]) by mx1.freebsd.org (Postfix) with ESMTP id 3E4631036 for ; Sun, 7 Feb 2016 00:11:29 +0000 (UTC) (envelope-from grog@lemis.com) Received: from eureka.lemis.com (www.lemis.com [208.86.226.86]) by www.lemis.com (Postfix) with ESMTP id AE3D21B72802 for ; Sun, 7 Feb 2016 00:03:05 +0000 (UTC) Received: by eureka.lemis.com (Postfix, from userid 1004) id 47FA244A5F0; Sun, 7 Feb 2016 11:03:04 +1100 (AEDT) Date: Sun, 7 Feb 2016 11:03:04 +1100 From: Greg 'groggy' Lehey To: ports@freebsd.org Subject: Removing documentation (was: [Bug 206922] Handbook: Chapter 4.5+ changes) Message-ID: <20160207000304.GA71035@eureka.lemis.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="6c2NcOVqGQ03X4Wi" Content-Disposition: inline In-Reply-To: Organization: The FreeBSD Project Phone: +61-3-5346-1370, +61-3-5309-0418 Mobile: 0401 265 606. Use only as instructed. WWW-Home-Page: http://www.FreeBSD.org/ X-PGP-Fingerprint: 9A1B 8202 BCCE B846 F92F 09AC 22E6 F290 507A 4223 User-Agent: Mutt/1.5.24 (2015-08-30) X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Feb 2016 00:11:30 -0000 --6c2NcOVqGQ03X4Wi Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 -- Sent from my desktop computer. Finger grog@FreeBSD.org for PGP public key. See complete headers for address and phone numbers. This message is digitally signed. If your Microsoft MUA reports problems, please read http://tinyurl.com/broken-mua --6c2NcOVqGQ03X4Wi Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAla2ibgACgkQIubykFB6QiObDgCZAe436lNAyFA4nyvW3Xb5Rpi3 PBAAnjngnMxYtCVNjRCsIFGF81xBOJHl =+JxF -----END PGP SIGNATURE----- --6c2NcOVqGQ03X4Wi--