From linimon@lonesome.com  Tue Jun 17 13:48:06 2003
Return-Path: <linimon@lonesome.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 329CA37B404
	for <FreeBSD-gnats-submit@FreeBSD.org>; Tue, 17 Jun 2003 13:48:06 -0700 (PDT)
Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 745D843F85
	for <FreeBSD-gnats-submit@FreeBSD.org>; Tue, 17 Jun 2003 13:48:04 -0700 (PDT)
	(envelope-from linimon@lonesome.com)
Received: from lonesome.lonesome.com (cs242746-11.austin.rr.com [24.27.46.11])
	(using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits))
	(No client certificate requested)
	by mail.soaustin.net (Postfix) with ESMTP id 9F602142D7
	for <FreeBSD-gnats-submit@FreeBSD.org>; Tue, 17 Jun 2003 15:48:03 -0500 (CDT)
Received: from lonesome.lonesome.com (localhost.lonesome.com [127.0.0.1])
	by lonesome.lonesome.com (8.12.9/8.12.3) with ESMTP id h5HKqGNa027509
	for <FreeBSD-gnats-submit@FreeBSD.org>; Tue, 17 Jun 2003 15:52:16 -0500 (CDT)
	(envelope-from linimon@lonesome.lonesome.com)
Received: (from linimon@localhost)
	by lonesome.lonesome.com (8.12.9/8.12.6/Submit) id h5HKqGTt027508;
	Tue, 17 Jun 2003 15:52:16 -0500 (CDT)
	(envelope-from linimon)
Message-Id: <200306172052.h5HKqGTt027508@lonesome.lonesome.com>
Date: Tue, 17 Jun 2003 15:52:16 -0500 (CDT)
From: Mark Linimon <linimon@lonesome.com>
Reply-To:
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:
Subject: [patch] rework of parts of Porter's Handbook part 4 of 5: catchup patch
X-Send-Pr-Version: 3.113.1
X-GNATS-Notify:

>Number:         53424
>Category:       docs
>Synopsis:       [patch] rework of parts of Porter's Handbook part 4 of 5: catchup patch
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ceri
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jun 17 13:50:10 PDT 2003
>Closed-Date:    Sun Jan 18 16:16:43 PST 2004
>Last-Modified:  Sun Jan 18 16:16:43 PST 2004
>Originator:     Mark Linimon
>Release:        FreeBSD-4.7
>Organization:
FreeBSD
>Environment:
System: FreeBSD lonesome.lonesome.com 4.7-STABLE FreeBSD 4.7-STABLE #0: Fri Nov 8 23:46:29 CST 2002 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
        The Porter's Handbook is insufficiently clear in some places, and
        needs expanding in others.  As requested I have tried to break
        out the rework that I did into several pieces.  Unfortunately
	the Handbook has been changing underneath me while these patches
	have been circulating.  This patch is necessary to make up for
	the fact that the first set of patches I did several weeks ago
	no longer applies cleanly.  This patch requires parts 1-3 as
	a prerequisite.
>How-To-Repeat:
	n/a
>Fix:

--- book.sgml	Sat May 24 13:56:33 2003
+++ book.sgml.mcl.new	Sat May 24 13:49:49 2003
@@ -82,7 +82,12 @@
 
       <para>When this document is not sufficiently detailed, you should
         refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which
-	all port Makefiles include.  Even if you do not hack Makefiles
+	all port <filename>Makefiles</filename> include.
+	(This is the file that actually
+	controls the actual port build process, so if this document says
+	one thing and <filename>bsd.port.mk</filename> says another,
+	<filename>bsd.port.mk</filename> is correct.)
+	Even if you do not hack <filename>Makefiles</filename>
 	daily, it is well commented, and you will still gain much
 	knowledge from it.  Additionally, you may send specific questions
 	to the &a.ports;.</para>
@@ -4711,24 +4656,35 @@
       <para>When you notice that a port is out of date compared to the latest
         version from the original authors, first make sure you have the latest
         port.  You can find them in the
-        <filename>ports/ports-current</filename> directory of the FTP mirror
+        <filename>ports/ports-current</filename> directory of the FreeBSD FTP mirror
         sites.  You may also use <application>CVSup</application> to keep your whole ports collection
         up-to-date, as described in the <ulink url="../handbook/synching.html#CVSUP-CONFIG">Handbook</ulink>.</para>
 
       <para>The next step is to send an email to the maintainer, if one is
-        listed in the port's <filename>Makefile</filename>.  That person may
+        listed, in the port's <filename>Makefile</filename>.  (Note that
+        unmaintained ports are listed under the name of
+        <literal>ports@FreeBSD.org</literal>; mail to that address
+        probably will not help in this case).  An active maintainer may
         already be working on an upgrade, or have a reason to not upgrade the
         port right now (because of, for example, stability problems of the new
-        version).</para>
+        version), so you will not want to duplicate work in that case.</para>
 
-      <para>If the maintainer asks you to do the upgrade or there is not any
-        such person to begin with, please make the upgrade and send the
-        recursive diff (either unified or context diff is fine, but port
-        committers appear to prefer unified diff more) of the new and old
+      <para>If the maintainer asks you to do the upgrade or the maintainer
+        is <literal>ports@FreeBSD.org</literal>,
+        please make the upgrade and send the recursive <command>diff</command>
+        of the new and old
         ports directories to us (e.g., if your modified port directory is
         called <filename>superedit</filename> and the original is in our tree
         as <filename>superedit.bak</filename>, then send us the result of
-        <command>diff -ruN superedit.bak superedit</command>).  Please examine
+        <command>diff -ruN superedit.bak superedit</command>).
+        Either unified or context diff is fine, but port
+        committers appear to prefer unified diff more.
+        Note the use of the <literal>-N</literal> option&mdash;this is
+        the accepted way to force diff to properly deal with the case of
+        new files being added or old files being deleted.</para>
+
+      <para>Please examine
+
         the output to make sure all the changes make sense.  The best way to
         send us the diff is by including it via &man.send-pr.1; (category
         <literal>ports</literal>).  If you are the maintainer for the port,
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->ceri 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Wed Jun 18 16:19:09 PDT 2003 
Responsible-Changed-Why:  
Force myself to deal with these. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=53424 
State-Changed-From-To: open->closed 
State-Changed-By: ceri 
State-Changed-When: Sun Jan 18 16:16:03 PST 2004 
State-Changed-Why:  
(Mostly) committed in r1.356.  Thanks again. 

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