Request for Review: pkgng documentation for the Handbook

[Benjamin Kaduk]

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...

% 	<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.

%       <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.

%       <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/ ?

% 
% 	<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.

% 	<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.


Thanks for putting this all together!

-Ben