From chu@h33.erkki.ton.tut.fi  Wed Jul 21 20:38:40 2004
Return-Path: <chu@h33.erkki.ton.tut.fi>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 9A5E716A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 21 Jul 2004 20:38:40 +0000 (GMT)
Received: from h33.erkki.ton.tut.fi (h33.erkki.ton.tut.fi [193.166.84.86])
	by mx1.FreeBSD.org (Postfix) with ESMTP id C45A343D46
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 21 Jul 2004 20:38:39 +0000 (GMT)
	(envelope-from chu@h33.erkki.ton.tut.fi)
Received: from h33.erkki.ton.tut.fi (chu@h33.erkki.ton.tut.fi [10.10.1.1])
	by h33.erkki.ton.tut.fi (8.12.9p2/8.12.8) with ESMTP id i6LKYNwD090483
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 21 Jul 2004 23:34:24 +0300 (EEST)
	(envelope-from chu@h33.erkki.ton.tut.fi)
Received: (from chu@localhost) by svak.h33.erkki.ton.tut.fi (8.12.11/8.12.11/Submit) id i6KL4KF2048109; Wed, 21 Jul 2004 00:04:20 +0300 (EEST) (envelope-from chu)
Message-Id: <200407202104.i6KL4KF2048109@svak.h33.erkki.ton.tut.fi>
Date: Wed, 21 Jul 2004 00:04:20 +0300 (EEST)
From: "Vladimir I. Chukharev" <chu@h33.erkki.ton.tut.fi>
To: FreeBSD-gnats-submit@freebsd.org
Subject: Clarify handbook on application installation
X-Send-Pr-Version: 3.113

>Number:         69394
>Category:       docs
>Synopsis:       Clarify handbook on application installation
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jul 21 20:40:26 GMT 2004
>Closed-Date:    Mon Aug 02 04:52:46 GMT 2004
>Last-Modified:  Mon Aug 02 04:52:46 GMT 2004
>Originator:     Vladimir I. Chukharev
>Release:        FreeBSD 4.10-STABLE i386
>Organization:
>Environment:

 System: FreeBSD svak.h33.erkki.ton.tut.fi 4.10-STABLE FreeBSD 4.10-STABLE  
 #3: Sun Jul 18 16:37:15 EEST 2004  
 root@svak.h33.erkki.ton.tut.fi:/usr/obj/usr/src/sys/SVAK i386

>Description:
 
 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

>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:
Class-Changed-From-To: sw-bug->doc-bug 
Class-Changed-By: keramida 
Class-Changed-When: Thu Jul 22 10:20:40 GMT 2004 
Class-Changed-Why:  
Misfiled docs PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=69394 
Responsible-Changed-From-To: gnats-admin->freebds-docs 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Thu Jul 22 10:24:07 GMT 2004 
Responsible-Changed-Why:  
Misfiled docs PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=69394 
Responsible-Changed-From-To: freebds-docs->freebsd-doc 
Responsible-Changed-By: dannyboy 
Responsible-Changed-When: Sun Jul 25 03:11:37 GMT 2004 
Responsible-Changed-Why:  
Spell freebsd-doc correctly. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=69394 
State-Changed-From-To: open->closed 
State-Changed-By: murray 
State-Changed-When: Mon Aug 2 04:50:45 GMT 2004 
State-Changed-Why:  
I moved the information about whereis and make search into 4.3 Finding 
your aplication as you suggested.  I also added a new item to the 
chapter synopsis.  I did not move the portupgrade section as it's not 
really clear to me what you are proposing. 

If you still think the portupgrade section should be moved, please 
provide more detail and some text updates.  Thanks for the submission! 
It may take up to 24 hours for the website to be updated with this 
change. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=69394 
>Unformatted:
