pkg/56656: Improve documentation for pkg_add configuration

[allcoms%gmail.com@localhost]

>Number:         56656
>Category:       pkg
>Synopsis:       Improve documentation for pkg_add configuration
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Jan 23 11:00:00 +0000 2022
>Originator:     Dan MacDonald
>Release:        9.2 / current
>Organization:
>Environment:
N/A
>Description:
Yesterday I tried NetBSD properly for the first time. I have installed and booted NetBSD previously to do a small test but I didn't try to set up a desktop like yesterday.

As a Linux user of 25+ years now, my first instinct after installing NetBSD was to try to update it as you would as if doing an apt/yum upgrade. I was later informed on IRC that NetBSD doesn't do interim security or bug fix releases of packages. This is kinda unrelated but its the back story and this could do well to be mentioned on:

https://wiki.netbsd.org/pkgsrc/how_to_upgrade_packages/

I think it might be worth mentioning this difference between NetBSD and most Linux distros at the top of that page as I expect I'm not the only person who has come to NetBSD with incorrect, Linux-centric expectations about package updates.

All I knew at this stage was that I needed pkgin to install packages. You will note on the above page that it goes straight in with:

"The recommended way to manage your system with binary packages is by using pkgtools/pkgin.

pkg_add pkgin"

If a user (who has configured their network device correctly) tries to run this command on a fresh install of NetBSD, pkg_add will just print an error because pkg_add requires that the user define PKG_PATH within /etc/pkg_install

To fix this, I would recommend three things:

* https://wiki.netbsd.org/pkgsrc/how_to_upgrade_packages/ should be updated as I've described, explaining to the user about the need to define PKG_PATH before they run pkg_add.

* This config step should also be documented clearly near the top of the man page for pkg_add.

* NetBSD should include an example /etc/pkg_install with several of the top NetBSD mirrors pre-configured as PKG_PATH's so all the user has to do is uncomment the one nearest to them to get pkg_add to work.
>How-To-Repeat:
Try to install packages as a NetBSD newb without an experienced NetBSD user at hand.
>Fix:
See full description for what needs to change.