From nobody@FreeBSD.org  Tue Sep 18 23:08:06 2012
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 05326106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Sep 2012 23:08:06 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id E5EE48FC20
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Sep 2012 23:08:05 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.5/8.14.5) with ESMTP id q8IN85WW044716
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Sep 2012 23:08:05 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.5/8.14.5/Submit) id q8IN85af044715;
	Tue, 18 Sep 2012 23:08:05 GMT
	(envelope-from nobody)
Message-Id: <201209182308.q8IN85af044715@red.freebsd.org>
Date: Tue, 18 Sep 2012 23:08:05 GMT
From: Paul Hoffman <phoffman@proper.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: portsnap man page is misleading
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         171759
>Category:       docs
>Synopsis:       portsnap man page is misleading
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    issyl0
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Sep 18 23:10:07 UTC 2012
>Closed-Date:    Wed Oct 03 09:17:25 UTC 2012
>Last-Modified:  Wed Oct 03 09:17:25 UTC 2012
>Originator:     Paul Hoffman
>Release:        8.3
>Organization:
>Environment:
FreeBSD hoffman.proper.com 8.3-RELEASE-p3 FreeBSD 8.3-RELEASE-p3 #0: Mon Jun 11 23:52:38 UTC 2012     root@i386-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  i386
>Description:
The first tip in the portsnap man page says:
     o   If your clock is set to local time, adding the line

               0 3 * * * root /usr/sbin/portsnap cron

         to /etc/crontab is a good way to make sure you always have an up-to-
         date snapshot of the ports tree available which can quickly be
         extracted into /usr/ports.

"extracted" is wrong: it should be "updated". However, it is misleading because it doesn't tell you *how* you can quickly update the ports, which is obviously what most people want to do. 
>How-To-Repeat:

>Fix:
     o   If your clock is set to local time, adding the line

               0 3 * * * root /usr/sbin/portsnap cron update

         to /etc/crontab is a good way to make sure you always have an up-to-
         date snapshot of the ports tree in /usr/ports.  

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->issyl0 
Responsible-Changed-By: issyl0 
Responsible-Changed-When: Thu Sep 20 19:30:57 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=171759 

From: Colin Percival <cperciva@freebsd.org>
To: bug-followup@FreeBSD.org, phoffman@proper.com
Cc:  
Subject: Re: docs/171759
Date: Sat, 22 Sep 2012 13:55:30 -0700

 I don't want to give an example of "portsnap cron update" in portsnap(8)
 since people often copy examples blindly and I've had complaints from
 people who have caused themselves problems that way.
 
 Clarifying the text, on the other hand (perhaps by adding "this way it
 will be fast when you next run 'portsnap update'" or something along
 those lines) would be perfectly fine, though.
 
 -- 
 Colin Percival
 Security Officer Emeritus, FreeBSD | The power to serve
 Founder, Tarsnap | www.tarsnap.com | Online backups for the truly paranoid

From: Paul Hoffman <phoffman@proper.com>
To: Colin Percival <cperciva@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/171759
Date: Sat, 22 Sep 2012 17:24:43 -0700

 > I don't want to give an example of "portsnap cron update" in =
 portsnap(8)
 > since people often copy examples blindly and I've had complaints from
 > people who have caused themselves problems that way.
 >=20
 > Clarifying the text, on the other hand (perhaps by adding "this way it
 > will be fast when you next run 'portsnap update'" or something along
 > those lines) would be perfectly fine, though.
 
 This is still a bit misleading for folks who are migrating from cvsup, =
 which many people are about to do (and I just did, which triggered this =
 bug report). In cvsup, the one command pulls *and installs* the changes; =
 portsnap requires two commands.
 
 If you really don't want to update the example to be something that =
 works (albeit unreliably in the extremely rare care where someone is =
 installing a port by hand in the middle of the night), please consider =
 adding the following separate paragraph after the paragraph in the first =
 bullet of the TIPS section:
 
    Note that *portsnap cron* does not apply the changes that were
    received: it only pulls them. To apply the changes, you must
    follow this command with *portsnap update*. The *portsnap update*
    command is normally run by hand at a time when you are sure
    that no one is manually working in the ports tree.
 
 That should cover the normal case of someone reading the doc when they =
 initially set up portsnap, or when the look at the man page in an =
 emergency when they can't figure out why an important security update =
 has not been applied.
 
 --Paul Hoffman=

From: Colin Percival <cperciva@freebsd.org>
To: Paul Hoffman <phoffman@proper.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/171759
Date: Wed, 26 Sep 2012 20:54:26 -0700

 On 09/22/12 17:24, Paul Hoffman wrote:
 > If you really don't want to update the example to be something that works
 (albeit unreliably in the extremely rare care where someone is installing a port
 by hand in the middle of the night), please consider adding the following
 separate paragraph after the paragraph in the first bullet of the TIPS section:
 > 
 >    Note that *portsnap cron* does not apply the changes that were
 >    received: it only pulls them. To apply the changes, you must
 >    follow this command with *portsnap update*. The *portsnap update*
 >    command is normally run by hand at a time when you are sure
 >    that no one is manually working in the ports tree.
 
 This looks great to me, subject to changing "*portsnap cron* does not" to
 "*portsnap cron* and *portsnap fetch* do not" and s/it only pulls them/they
 only download the changes/.
 
 > That should cover the normal case of someone reading the doc when they
 initially set up portsnap, or when the look at the man page in an emergency when
 they can't figure out why an important security update has not been applied.
 
 Agreed.
 
 -- 
 Colin Percival
 Security Officer Emeritus, FreeBSD | The power to serve
 Founder, Tarsnap | www.tarsnap.com | Online backups for the truly paranoid
 

From: Paul Hoffman <phoffman@proper.com>
To: Colin Percival <cperciva@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/171759
Date: Thu, 27 Sep 2012 07:48:54 -0700

 On Sep 26, 2012, at 8:54 PM, Colin Percival <cperciva@freebsd.org> =
 wrote:
 
 > On 09/22/12 17:24, Paul Hoffman wrote:
 >> If you really don't want to update the example to be something that =
 works
 > (albeit unreliably in the extremely rare care where someone is =
 installing a port
 > by hand in the middle of the night), please consider adding the =
 following
 > separate paragraph after the paragraph in the first bullet of the TIPS =
 section:
 >>=20
 >>   Note that *portsnap cron* does not apply the changes that were
 >>   received: it only pulls them. To apply the changes, you must
 >>   follow this command with *portsnap update*. The *portsnap update*
 >>   command is normally run by hand at a time when you are sure
 >>   that no one is manually working in the ports tree.
 >=20
 > This looks great to me, subject to changing "*portsnap cron* does not" =
 to
 > "*portsnap cron* and *portsnap fetch* do not" and s/it only pulls =
 them/they
 > only download the changes/.
 >=20
 >> That should cover the normal case of someone reading the doc when =
 they
 > initially set up portsnap, or when the look at the man page in an =
 emergency when
 > they can't figure out why an important security update has not been =
 applied.
 >=20
 > Agreed.
 
 Looks good to me. You have commit privs and I don't; please make it so.
 
 --Paul Hoffman=
State-Changed-From-To: open->patched 
State-Changed-By: issyl0 
State-Changed-When: Fri Sep 28 11:13:48 UTC 2012 
State-Changed-Why:  
Fix committed in r241024.  Awaiting MFC. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=171759 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/171759: commit references a PR
Date: Fri, 28 Sep 2012 11:11:54 +0000 (UTC)

 Author: issyl0 (doc committer)
 Date: Fri Sep 28 11:11:42 2012
 New Revision: 241024
 URL: http://svn.freebsd.org/changeset/base/241024
 
 Log:
   Add a note to portsnap(8) about the behaviour of the example cron command.
   
   PR:		docs/171759
   Submitted by:	Paul Hoffman (phoffman at proper dot com)
   Approved by:	cperciva, gabor (mentor)
   MFC after:	3 days
 
 Modified:
   head/usr.sbin/portsnap/portsnap/portsnap.8
 
 Modified: head/usr.sbin/portsnap/portsnap/portsnap.8
 ==============================================================================
 --- head/usr.sbin/portsnap/portsnap/portsnap.8	Fri Sep 28 10:49:41 2012	(r241023)
 +++ head/usr.sbin/portsnap/portsnap/portsnap.8	Fri Sep 28 11:11:42 2012	(r241024)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd August 5, 2012
 +.Dd September 28, 2012
  .Dt PORTSNAP 8
  .Os FreeBSD
  .Sh NAME
 @@ -180,6 +180,23 @@ can quickly be extracted into
  If your clock is set to UTC, please pick a random time other
  than 3AM, to avoid overly imposing an uneven load on the
  server(s) hosting the snapshots.
 +.Pp
 +Note that running
 +.Nm
 +.Cm cron
 +or
 +.Nm
 +.Cm fetch
 +does not apply the changes that were received: they only only download
 +them.
 +To apply the changes, you must follow these commands with
 +.Nm
 +.Cm update .
 +The
 +.Nm
 +.Cm update
 +command is normally run by hand at a time when you are sure that
 +no one is manually working in the ports tree.
  .It
  Running
  .Nm
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/171759: commit references a PR
Date: Mon,  1 Oct 2012 16:34:33 +0000 (UTC)

 Author: issyl0 (doc committer)
 Date: Mon Oct  1 16:34:12 2012
 New Revision: 241106
 URL: http://svn.freebsd.org/changeset/base/241106
 
 Log:
   MFC r241024 and r241026 from HEAD:
     - Add a note to portsnap(8) about the behaviour of the example cron command.
     - Change "only only" to "only" in portsnap(8).
   
   PR:		docs/171759
   Approved by:	gjb (mentor)
 
 Modified:
   stable/9/usr.sbin/portsnap/portsnap/portsnap.8
 Directory Properties:
   stable/9/usr.sbin/portsnap/   (props changed)
 
 Modified: stable/9/usr.sbin/portsnap/portsnap/portsnap.8
 ==============================================================================
 --- stable/9/usr.sbin/portsnap/portsnap/portsnap.8	Mon Oct  1 15:50:18 2012	(r241105)
 +++ stable/9/usr.sbin/portsnap/portsnap/portsnap.8	Mon Oct  1 16:34:12 2012	(r241106)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd September 15, 2008
 +.Dd September 28, 2012
  .Dt PORTSNAP 8
  .Os FreeBSD
  .Sh NAME
 @@ -174,6 +174,23 @@ can quickly be extracted into
  If your clock is set to UTC, please pick a random time other
  than 3AM, to avoid overly imposing an uneven load on the
  server(s) hosting the snapshots.
 +.Pp
 +Note that running
 +.Nm
 +.Cm cron
 +or
 +.Nm
 +.Cm fetch
 +does not apply the changes that were received: they only download
 +them.
 +To apply the changes, you must follow these commands with
 +.Nm
 +.Cm update .
 +The
 +.Nm
 +.Cm update
 +command is normally run by hand at a time when you are sure that
 +no one is manually working in the ports tree.
  .It
  Running
  .Nm
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: issyl0 
State-Changed-When: Wed Oct 3 09:17:23 UTC 2012 
State-Changed-Why:  
This is now fixed. 

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