Guide's "Configuring" chapter is rather misleading than helpful

[Aleksej Saushev <asau%inbox.ru@localhost>]

  Hello!

I want to point that "Configuring pkgsrc" chapter in the Guide is
rather misleading than helpful in any way. It should be rewritten
almost completely, if we want to provide really useful documentation.

First, it doesn't stress how pkgsrc is configured, the location of mk.conf
is hard to grasp. The Guide misleads bootstrapping user when calling real
bootstrap-generated mk.conf "an example configuration file."

Second, it is _highly_undesirable_ that Guide mentions such variables as
LOCALBASE, X11BASE, and a couple of other ones. User shouldn't touch them
before he learns how pkgsrc works inside. In other words, this information
is only for rather advanced pkgsrc users, it shouldn't be present in entry
level documentation. If we do want to expose these settings to any user,
all of them should carry caution signs.

Third, the Guide sends user to mk/defaults/mk.conf without explanation
that this is _not_ example file, that this file is _not_ meant to be
copied in place of mk.conf and modified there. Thus the Guide misleads
user of effective ways to configure pkgsrc.

As result, the chapter overloads user with useless and dangerous
information without discussing essential issues of using vulnerable
packages and separation of pkgsrc's and system's variables with
famous ".ifdef BSD_PKG_MK". It is much easier to guide novice user
on IRC channel than to point to relevant place in documentation.

It is the pkgsrc Guide in its current state that presents incarnation
of usability nightmare rather than wrongly placed pkgsrc's mk.conf.
Moving mk.conf isn't such a big deal, but it doesn't prevent misuse of
configurable parameter to misconfigure it, which is most likely with
the sort of documentation we have now.


-- 
HE CE3OH...