docs/53424: [patch] rework of parts of Porter's Handbook part 4 of 5: catchup patch

[Mark Linimon]

>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:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jun 17 13:50:10 PDT 2003
>Closed-Date:
>Last-Modified:
>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 at 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 at 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 at 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—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:
>Unformatted: