From owner-freebsd-doc@FreeBSD.ORG Sat Nov 24 17:27:15 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 2FBD8340; Sat, 24 Nov 2012 17:27:15 +0000 (UTC) (envelope-from gjb@FreeBSD.org) Received: from onyx.glenbarber.us (onyx.glenbarber.us [IPv6:2607:fc50:1000:c200::face]) by mx1.freebsd.org (Postfix) with ESMTP id F22708FC08; Sat, 24 Nov 2012 17:27:14 +0000 (UTC) Received: from glenbarber.us (75.97.144.133.res-cmts.sewb.ptd.net [75.97.144.133]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: gjb) by onyx.glenbarber.us (Postfix) with ESMTPSA id 396D123F75B; Sat, 24 Nov 2012 12:27:14 -0500 (EST) Date: Sat, 24 Nov 2012 12:27:12 -0500 From: Glen Barber To: Benjamin Kaduk Subject: Re: Request for Review: pkgng documentation for the Handbook Message-ID: <20121124172712.GB1470@glenbarber.us> References: <20121116165810.GC1335@glenbarber.us> <20121123173758.GA1282@glenbarber.us> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="TRYliJ5NKNqkz5bu" Content-Disposition: inline In-Reply-To: X-Operating-System: FreeBSD 10.0-CURRENT amd64 User-Agent: Mutt/1.5.21 (2010-09-15) Cc: freebsd-doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 24 Nov 2012 17:27:15 -0000 --TRYliJ5NKNqkz5bu Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Nov 23, 2012 at 11:52:37PM -0500, Benjamin Kaduk wrote: > On Fri, 23 Nov 2012, Glen Barber wrote: >=20 > > Hi, > > > > On Fri, Nov 16, 2012 at 11:58:10AM -0500, Glen Barber wrote: > >> Hi, > >> > >> I would like to get feedback on recent commits to the projects/pkgng/ > >> branch, which adds documentation for pkgng to the Handbook. > >> > >> There are a few sections on my todo list, but I feel what is there now > >> covers the basics for FreeBSD users. > >> > >> The diff is attached, and rendered output is here: > >> > >> http://people.freebsd.org/~gjb/pkgng/data/doc/en/books/handbook/pk= gng-intro.html > >> > >> I would like to merge this into head/ when 9.1-RELEASE is announced. > >> > > > > As 9.1-RELEASE is delayed longer than originally expected with this > > original request for review, I plan to merge this pkgng documentation to > > head/ within the next day so I can continue to use the existing > > projects/pkgng/ branch for further addtitions to the section. >=20 > % > % The pkgng package management > % utility is not supported on > % &os; 7.X or > % &os; 8.0. >=20 > 0 is not exactly replacable... >=20 Erm... Yep. Thanks. > % The package database conversion may emit errors as the > % contents are converted to the new version. Generally, these > % errors can be safely ignored, however a list of third-party > % software that was not successfully converted will be listed > % after pkg2ng has finished. These must be > % fixed by hand. >=20 > Is that "fix by hand" going to be deinstall/reinstall most of the time?= =20 > We might want to say so. >=20 Yes, that is on my todo list for the next set of changes. I want to get this into the Handbook though, so people have some documentation on how things work. Fixing things "by hand" with pkgng is a bit tricky, and can have a number of edge cases, so it will be a large-ish addition. > % > % Installing and Removing Packages with > % <application>pkgng</application> > %=20 > % In general, most &os; users will install binary packages > % by running: > %=20 > % &prompt.root; pkg install packagename<= /replaceable> > %=20 > % pkg install uses repository data, as >=20 > Mentioning once at an arbitrary location; this document has a great deal= =20 > of sentences that start with a markup element (i.e., not a capital=20 > letter). Not sure that it's worth trying to do anything about it now,=20 > though. >=20 Noted. > % > % Automatically Removing Leaf Dependencies with > % <application>pkgng</application> > %=20 > % Removing a package may leave behind unnecessary > % dependencies, like % role=3D"package">security/ca_root_nss in the example > % above. Those packages are still installed, but nothing >=20 > Maybe s/Those/Such/ ? >=20 Yep. I'll change this. Thanks. > %=20 > % By default, pkgng stores > % binary packages in a cache directory as defined by > % PKG_CACHEDIR in pkg.conf(5). When > % upgrading packages with pkg upgrade, old > % versions of the upgraded packages are not automatically > % removed. > %=20 > % To remove the outdated binary packages from the system, >=20 > Perhaps this should be file system instead of just "system"? The current= =20 > text might be a little ambiguous as to whether the outdated package is=20 > actually installed/being used. >=20 With Warren's suggestion noted, I'll remove "from the system" entirely. > % Unlike the % role=3D"package">ports-mgmt/portmaster and > % ports-mgmt/portupgrade > % ports, the order in which the new and old versions are > % listed differ. For pkgng, the > % syntax is pkg set -o >=20 > My broswer puts a line break between the '-' and the 'o', which seems=20 > very odd. I don't know that there's a markup fix for that, though; I jus= t=20 > mention it as odd. >=20 I'll switch this to tags then. The other alternative would be to use  , but that's... ugly. > Thanks for putting this all together! >=20 My pleasure. Thanks for the review. Glen --TRYliJ5NKNqkz5bu Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (FreeBSD) iQEcBAEBCAAGBQJQsQNvAAoJEFJPDDeguUaj+YsH/1nsLNHhe4xoNkLqYvYfwuNz yn2hwvSQJ6Ggz3OKVFGjS6ftny95FIqbGMbKpgykDBdKA6FXp+/iZ1rL5eU6RVyb qC7VR4yaycvVcFAYDiGcQhPajgTEHa/thELWMhV0pyskR2uwoZhoBdiaXHsrjRlC j87hfnzGER73YJa/SnohwNtESYCDXlWwango58vr/+2d1MwE7vC0M/R/01MR3k4c TUgAYuU8bF1Sb8Tt3PmOBA9EV5N/XQ5NMe3pNsKpeptNVIOstwyLPV3tngix4A2R 50R6sR1Yo6wKGEwIlHk749yMnJ10bntuyEIVSktr5Med15/pWCdyjlLd4SJGnvU= =ShOk -----END PGP SIGNATURE----- --TRYliJ5NKNqkz5bu--