Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 23 Nov 2012 23:52:37 -0500 (EST)
From:      Benjamin Kaduk <kaduk@MIT.EDU>
To:        Glen Barber <gjb@freebsd.org>
Cc:        freebsd-doc@freebsd.org
Subject:   Re: Request for Review: pkgng documentation for the Handbook
Message-ID:  <alpine.GSO.1.10.1211232216260.2164@multics.mit.edu>
In-Reply-To: <20121123173758.GA1282@glenbarber.us>
References:  <20121116165810.GC1335@glenbarber.us> <20121123173758.GA1282@glenbarber.us>

next in thread | previous in thread | raw e-mail | index | archive | help
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;&nbsp;7.<replaceable>X</replaceable> or
% 	  &os;&nbsp;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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.GSO.1.10.1211232216260.2164>