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>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] On Fri, Nov 23, 2012 at 11:52:37PM -0500, Benjamin Kaduk wrote: > On Fri, 23 Nov 2012, Glen Barber wrote: > > > 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/pkgng-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. > > % <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> > > 0 is not exactly replacable... > 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> > > Is that "fix by hand" going to be deinstall/reinstall most of the time? > We might want to say so. > 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="pkgng-installing-deinstalling"> > % <title>Installing and Removing Packages with > % <application>pkgng</application></title> > % > % <para>In general, most &os; users will install binary packages > % by running:</para> > % > % <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen> > % > % <para><command>pkg install</command> uses repository data, as > > Mentioning once at an arbitrary location; this document has a great deal > of sentences that start with a markup element (i.e., not a capital > letter). Not sure that it's worth trying to do anything about it now, > though. > Noted. > % <sect3 id="pkgng-autoremove"> > % <title>Automatically Removing Leaf Dependencies with > % <application>pkgng</application></title> > % > % <para>Removing a package may leave behind unnecessary > % dependencies, like <filename > % role="package">security/ca_root_nss</filename> in the example > % above. Those packages are still installed, but nothing > > Maybe s/Those/Such/ ? > Yep. I'll change this. Thanks. > % > % <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> > % > % <para>To remove the outdated binary packages from the system, > > Perhaps this should be file system instead of just "system"? The current > text might be a little ambiguous as to whether the outdated package is > actually installed/being used. > With Warren's suggestion noted, I'll remove "from the system" entirely. > % <para>Unlike the <filename > % role="package">ports-mgmt/portmaster</filename> and > % <filename role="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 > > My broswer puts a line break between the '-' and the 'o', which seems > very odd. I don't know that there's a markup fix for that, though; I just > mention it as odd. > 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! > My pleasure. Thanks for the review. Glen [-- Attachment #2 --] -----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-----help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121124172712.GB1470>