Request for Review: pkgng documentation for the Handbook

[Glen Barber]

On Fri, Nov 16, 2012 at 10:34:57AM -0700, Warren Block wrote:
> On Fri, 16 Nov 2012, Glen Barber wrote:
> 
> > 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
> 
> Nice!  I do have some suggestions:
> 
>    pkgng is not a replacement for port management tools like
>    ports-mgmt/portmaster or ports-mgmt/portupgrade.
> 
> That sentence ends a little abruptly.  A second sentence could elaborate 
> a little on why those two tools still work or are needed.
> 

Ok, thanks.

> 
> "Getting Started with pkgng"
> Markup on bootstrap should be <quote> tags.
> 

Hmm.  I didn't think <quote> tags actually worked.

> "Existing FreeBSD installations require conversion of the pkg_install 
> package database"
> pkg_install should be a man page ref.

There actually is no pkg_install manual page.

>    To ensure the FreeBSD Ports Collection registers new software with
>    pkgng, and not pkg_install, add the following lines to /etc/make.conf:
> 
> pkg_install should be a man page ref.  I'd also suggest "these" or 
> "this" instead of "the following".
> 

Ok, thanks.

> The visually-disruptive Note at the end of that step about it not being 
> required on 10.x could be added to the preceding paragraph:
> 
>    For versions of &os; before 10.X, add this line to /etc/make.conf:
> 
> 
> 
> "Configuring the pkgng Environment" is kind of confusing, and could be 
> simplified.  Is it necessary to mention the environment variable at all?
> 
>    The pkgng package management system uses a package repository for most
>    operations.  The default package repository location is
>    defined in /usr/local/etc/pkg.conf or the PACKAGESITE environment
>    variable which overrides the configuration file.
> 

Looks good to me.  Thanks.

> 
> "Basic pkgng Operations"
> pkg(8) should be a man page ref.
> 

There are no manref entries for pkg* since it is from ports.  I had to
convert these from &man.pkg.*.N; to hard-coded text to unbreak the
build.

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/20121116/24cda48a/attachment.sig>