Bug 176251 - FreeBSD Handbook assumes too much pre-knowledge
Summary: FreeBSD Handbook assumes too much pre-knowledge
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc mailing list
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-02-18 18:30 UTC by torsten.eichstaedt
Modified: 2017-12-31 22:29 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description torsten.eichstaedt 2013-02-18 18:30:00 UTC
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"

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.
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.
Comment 1 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 08:01:35 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped