docs/176251: FreeBSD Handbook assumes too much pre-knowledge

[Torsten Eichstädt]

>Number:         176251
>Category:       docs
>Synopsis:       FreeBSD Handbook assumes too much pre-knowledge
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Feb 18 18:30:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Torsten Eichstädt
>Release:        9.1
>Organization:
>Environment:
FreeBSD paul-lifebook 9.1-RELEASE FreeBSD 9.1-RELEASE #2: Tue Nov 27 03:45:16 UTC 2012     root at darkstar:/usr/obj/pcbsd-build90/fbsd-source/9.1/sys/GENERIC  amd64
>Description:
E.g. chapter 5.4.1 of the FreeBSD Handbook (online version):
"Note: pkg_add [...] of the application [...]
[...] behavior by overriding PACKAGESITE. For example, on a FreeBSD 8.1-RELEASE system, [...]
[..] set PACKAGESITE to ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/."

Assuming PACKAGESITE is an env var used by all package & ports tools, this note should be moved to the beginning of chapter 5 and it should be:

"All package & ports tools [...] of the application available for your computer architecture [...]
[...] by overriding the environment variable PACKAGESITE. For example, on a standard PC with FreeBSD 9.1-RELEASE installed, [...]
[..] do this:
# setenv PACKAGESITE ftp://ftp.freebsd.org/pub/FreeBSD/ports/amd64/packages-9-stable/Latest/
before starting the tool, e.g. pkg_add or portupgrade.
To make this a permanent choice, add it to the system administrators shell startup script, like this:
# cp $HOME/.cshrc $HOME/.cshrc.bak
# echo setenv PACKAGESITE  ftp://ftp.freebsd.org/pub/FreeBSD/ports/amd64/packages-9-stable/Latest/ >> $HOME/.cshrc"
>How-To-Repeat:
Set yourself dumb ("ok for now I'm a newbie, not a nerd") and try to install the FreeBSD docs on a fresh FreeBSD 9.1 system as long the infrastructure is not set up again (status of today, Feb 18, 2013).  Then you realize that you have to jump from doc to doc like Tarzan on LSD, although the info you need was known for sure to the author of the 1st doc you read.
>Fix:
Change developers attitude.  At minimum, commiters to FreeBSD should pass a test about "The UNIX-HATERS Handbook" (http://homes.cs.washington.edu/~weise/uhh-download.html) to assure they read it.

>Release-Note:
>Audit-Trail:
>Unformatted: