Request for Review: pkgng documentation for the Handbook

[Glen Barber]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20121124/3a8920fa/attachment.sig>