From nobody@FreeBSD.org  Tue Oct 24 19:28:00 2006
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id AEEB716A412
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 24 Oct 2006 19:28:00 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 3938E43D91
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 24 Oct 2006 19:28:00 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id k9OJRxCD085328
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 24 Oct 2006 19:27:59 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id k9OJRxCo085326;
	Tue, 24 Oct 2006 19:27:59 GMT
	(envelope-from nobody)
Message-Id: <200610241927.k9OJRxCo085326@www.freebsd.org>
Date: Tue, 24 Oct 2006 19:27:59 GMT
From: Paul Brian<paulb@pirc.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Suggest make diff. between src and ports clearer in CVSUP manual pages 
X-Send-Pr-Version: www-3.0

>Number:         104767
>Category:       docs
>Synopsis:       Suggest make diff. between src and ports clearer in CVSUP manual pages
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Oct 24 19:30:13 GMT 2006
>Closed-Date:    Sat Nov 04 09:20:56 GMT 2006
>Last-Modified:  Sat Nov 04 09:20:56 GMT 2006
>Originator:     Paul Brian
>Release:        RELENG_6
>Organization:
PIRC Ltd
>Environment:
FreeBSD pbrian.office.pirc.co.uk 6.1-RELEASE FreeBSD 6.1-RELEASE #0: Sun May  7 04:32:43 UTC 2006     root@opus.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC  i386

>Description:
I am a newbie to FreeBsd but not Linux/programming and the following feels a little embarrassing, but I may have noticed a blind spot for people immersed in FreeBSD.

I have been struggling to truly "get" CVSUP, and have recently had a flash of the blidingly obvious that I suspect others (reading newgroups) also struggle to see.

Could you add a paragraph explaining in words of one syllable the difference between src-all and ports-all to the intro section of books/handbook/cvsup.html

Until just now I did not realise that src was the src for code developed by FreeBSD and ports where make instructions for third party code. This makes the brach/release tag more obvious as well.  THis seems not an uncommon issue in the groups [1]. Now it is pretty embarrassing to say that, but I have been reading carefully. Twice. Honest.

So I would suggest a paragraph explaining very clearly that src and ports come from different places, so when ports breaks it is easier to work out why.

Suggested phrases

"It is helpful to note that src collection will download the code created by the FreeBSD volunteers as part of the FreeBSD project, and is kept as a tree in /usr/src. The ports collection (/usr/ports) is the better known part, and is in essence make instructions for 3rd party software, compatible with FreeBSd but not produced by the volunteers who create the operating system and tools.
- you do not download 3rd party code when doing a cvsup.

Now all you have to worry about is choosing the right release tag.
"







[1] http://www.freebsdforums.org/forums/printthread.php?t=36509, http://lists.freebsd.org/pipermail/freebsd-questions/2005-April/084604.html

>How-To-Repeat:

>Fix:

>Release-Note:
>Audit-Trail:

From: Tom Rhodes <trhodes@FreeBSD.org>
To: Paul Brian<paulb@pirc.co.uk>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/104767: Suggest make diff. between src and ports clearer
 in CVSUP manual pages
Date: Tue, 24 Oct 2006 16:49:05 -0400

 On Tue, 24 Oct 2006 19:27:59 GMT
 Paul Brian<paulb@pirc.co.uk> wrote:
 
 Hi Paul,
 
 > 
 > >Number:         104767
 > >Category:       docs
 > >Synopsis:       Suggest make diff. between src and ports clearer in CVSUP manual pages
 > >Confidential:   no
 > >Severity:       non-critical
 > >Priority:       low
 > >Responsible:    freebsd-doc
 > >State:          open
 > >Quarter:        
 > >Keywords:       
 > >Date-Required:
 > >Class:          change-request
 > >Submitter-Id:   current-users
 > >Arrival-Date:   Tue Oct 24 19:30:13 GMT 2006
 > >Closed-Date:
 > >Last-Modified:
 > >Originator:     Paul Brian
 > >Release:        RELENG_6
 > >Organization:
 > PIRC Ltd
 > >Environment:
 > FreeBSD pbrian.office.pirc.co.uk 6.1-RELEASE FreeBSD 6.1-RELEASE #0: Sun May  7 04:32:43 UTC 2006     root@opus.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC  i386
 > 
 > >Description:
 > I am a newbie to FreeBsd but not Linux/programming and the following feels a little embarrassing, but I may have noticed a blind spot for people immersed in FreeBSD.
 > 
 > I have been struggling to truly "get" CVSUP, and have recently had a flash of the blidingly obvious that I suspect others (reading newgroups) also struggle to see.
 > 
 > Could you add a paragraph explaining in words of one syllable the difference between src-all and ports-all to the intro section of books/handbook/cvsup.html
 > 
 > Until just now I did not realise that src was the src for code developed by FreeBSD and ports where make instructions for third party code. This makes the brach/release tag more obvious as well.  THis seems not an uncommon issue in the groups [1]. Now it is pretty embarrassing to say that, but I have been reading carefully. Twice. Honest.
 > 
 > So I would suggest a paragraph explaining very clearly that src and ports come from different places, so when ports breaks it is easier to work out why.
 > 
 > Suggested phrases
 > 
 > "It is helpful to note that src collection will download the code created by the FreeBSD volunteers as part of the FreeBSD project, and is kept as a tree in /usr/src. The ports collection (/usr/ports) is the better known part, and is in essence make instructions for 3rd party software, compatible with FreeBSd but not produced by the volunteers who create the operating system and tools.
 > - you do not download 3rd party code when doing a cvsup.
 > 
 > Now all you have to worry about is choosing the right release tag.
 > "
 
 I think that the CVSup explanation found here:
 
 http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/cvsup.html
 
 while not easy to find, does explain "src-all" as "entire main source
 tree for the FreeBSD" in an early paragraph and later on as "The main
 FreeBSD sources, including the cryptography code."
 
 It also explains the ports option.  With large "WARNING" comments,
 
 I'm not sure how the confusion could occur unless there is much
 skipping with the eyes.
 
 -- 
 Tom Rhodes

From: Daniel Gerzo <danger@FreeBSD.org>
To: bug-followup@FreeBSD.org, paulb@pirc.co.uk
Cc:  
Subject: Re: docs/104767: Suggest make diff. between src and ports clearer in CVSUP manual pages
Date: Wed, 1 Nov 2006 10:46:08 +0100

 Hello bug-followup,
 
   I agree with Tom, it's well described.
 
 -- 
 Best regards,
  Daniel                          mailto:danger@FreeBSD.org
 
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Nov 4 09:20:04 UTC 2006 
State-Changed-Why:  
The use of CVSup is well described in both the handbook 
and the installed example files.  Thanks! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Sat Nov 4 09:20:04 UTC 2006 
Responsible-Changed-Why:  
Over to me. 

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