Bug 69394

 
 Recently I was involved in upgrading of a Linux server to a newer
 hardware (amd64 based). I managed to convince others to give a try
 for FreeBSD 5.2.1-RELEASE. Unfortunately, the hardware was not
 perfectly supported by FreeBSD, so that was the main reason for
 final move to Fedora.
 
 There were also reasonable complains about documentation,
 namely about application installation.
 In general, (almost) all the needed information is in chapter 4.
 But my recomendations and how guys understand what they read in
 the handbook were very far from each other. For example, when
 I told to use 'make search key=...' rather than google for
 searching a port, the anwer was "Why it is not mentioned in
 the handbook?!". I said "Yes, it is", and then it took me
 quite a time to find this command in the handbook, because
 it is not in '4.3 Finding Your Application', but in
 '4.5.2 Installing Ports', hidden in the other stuff.
 
 So I want to write down the biggest things I noticed,
 hoping someone will find time to amend them...
 
> How-To-Repeat:
 Watch a newcomer reading the handbook chapter 4. Or read yourself :)
 
> Fix:
 In '4.1  Synopsis' after "After reading this chapter, you will know:"
 add something like "How to find software".
 
 Rearange '4.2 Overview of Software Installation' in the way that there
 are many ported programs, they are in source and/or binary form in
 ports and packages, and there is portupgrade, which can use both ports
 and packages.
 Then advantages of packages and ports, and finally how not-yet-ported
 program can be installed.  The way it is now this last type of
 installation (first in existing text of the handbook) is percepted as
 a guide for action :-(
 
 Add to beginning of '4.3 Finding Your Application' the description of
 'whereis' and 'make search' from '4.5.2 Installing Ports'. Make a note,
 that whereis will find a program only by full name, while make search
 looks for any substring...
 
 Add at the beginning of both '4.4 Using the Packages System' and
 '4.5 Using the Ports Collection' a reference to portupgrade description,
 currently in '4.5.5 Upgrading Ports', and words that portupgrade does
 the same thing with extra checks, and the described commands are needed
 mainly for gurus (: and when portupgrade fails, which happens! :).
 Probably the description of portupgrade should be moved closer
 to beginning of the chapter 4.
 
 
 I beleave the outlined changes can make the handbook more convenient.
 
 Thanks to everybody for mostly great docs!
 -- 
 V.Chukharev