Date: Sat, 24 Nov 2012 12:27:12 -0500 From: Glen Barber <gjb@FreeBSD.org> To: Benjamin Kaduk <kaduk@MIT.EDU> Cc: freebsd-doc@freebsd.org Subject: Re: Request for Review: pkgng documentation for the Handbook Message-ID: <20121124172712.GB1470@glenbarber.us> In-Reply-To: <alpine.GSO.1.10.1211232216260.2164@multics.mit.edu> References: <20121116165810.GC1335@glenbarber.us> <20121123173758.GA1282@glenbarber.us> <alpine.GSO.1.10.1211232216260.2164@multics.mit.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 > % <note> > % <para>The <application>pkgng</application> package management > % utility is not supported on > % &os; 7.<replaceable>X</replaceable> or > % &os; 8.<replaceable>0</replaceable>.</para> >=20 > 0 is not exactly replacable... >=20 Erm... Yep. Thanks. > % <para>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 <command>pkg2ng</command> has finished. These must be > % fixed by hand.</para> >=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. > % <sect3 id=3D"pkgng-installing-deinstalling"> > % <title>Installing and Removing Packages with > % <application>pkgng</application></title> > %=20 > % <para>In general, most &os; users will install binary packages > % by running:</para> > %=20 > % <screen>&prompt.root; <userinput>pkg install <replaceable>packagename<= /replaceable></userinput></screen> > %=20 > % <para><command>pkg install</command> 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. > % <sect3 id=3D"pkgng-autoremove"> > % <title>Automatically Removing Leaf Dependencies with > % <application>pkgng</application></title> > %=20 > % <para>Removing a package may leave behind unnecessary > % dependencies, like <filename > % role=3D"package">security/ca_root_nss</filename> in the example > % above. Those packages are still installed, but nothing >=20 > Maybe s/Those/Such/ ? >=20 Yep. I'll change this. Thanks. > %=20 > % <para>By default, <application>pkgng</application> stores > % binary packages in a cache directory as defined by > % <envar>PKG_CACHEDIR</envar> in pkg.conf(5). When > % upgrading packages with <command>pkg upgrade</command>, old > % versions of the upgraded packages are not automatically > % removed.</para> > %=20 > % <para>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. > % <para>Unlike the <filename > % role=3D"package">ports-mgmt/portmaster</filename> and > % <filename role=3D"package">ports-mgmt/portupgrade</filename> > % ports, the order in which the new and old versions are > % listed differ. For <application>pkgng</application>, the > % syntax is <command>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 <screen> 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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121124172712.GB1470>