1) Warn about copying pkg/DESCR from a manpage

2)  Include the new port in the PR, a-la current practice (the only
    submitters.sgml modification is to support this).
3)  Enlarge the list of Do's and Dont's.

Preliminary-Linuxdoc-ification-for-number-3:  Eivend
Insistence-that-number-3-not-disappear:  Eivend
Probably-implicit-offers-of-additional-help-for-number-3:  Eivend
All-the-writing:  Me.
Really-smooth-intro-written-by-Eivend-but-unfortunately-not-included-yet: Absent

handbook/porting.sgml

@@ -1,4 +1,4 @@
-<!-- $Id: porting.sgml,v 1.93 1998-03-15 06:03:35 hanai Exp $ -->
+<!-- $Id: porting.sgml,v 1.94 1998-04-27 00:40:14 hoek Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
@@ -248,9 +248,10 @@ A cat chasing a mouse all over the screen.
 	    paragraphs concisely explaining what the port does is
 	    sufficient.  Note: This is <em>not</em> a manual nor an
 	    in-depth description on how to use or compile the port.
-	    In particular, <em>please do not just copy the <tt>README</tt>
+	    <em>Please be careful if you are copying from the
-	    file here</em>, unless, of course, it is a concise description
+	    <tt>README</tt> or manpage</em>; too often they are not a
-	    of the port.
+	    concise description of the port or are in an awkward format
+	    (e.g. manpages have justified spacing).
 
 	  <p>It is recommended that you sign the name at the end of
 	    this file, as in:
@@ -313,22 +314,32 @@ lib/X11/oneko/mouse.xpm
       <sect3>
 	<heading>Submitting the port<label id="porting:submitting"></heading>
 
+	<p>First, make sure you have read the <ref id="porting:dads"
+	   name="Do's and Dont's"> section.
+
 	<p>Now that you are happy with your port, the only thing
 	  remaining is to put it in the main FreeBSD ports tree and
-	  make everybody else happy about it too.  To accomplish this,
+	  make everybody else happy about it too.  We do not need
-	  pack the necessary files (everything described in this
+	  your <tt>work/</tt> directory or the <tt>pkgname.tgz</tt>
-	  section -- in particular do <em>not</em> include the
+	  package, so delete them now.  Next, simply include the
-	  original source tarball, the `<tt>work</tt>' subdirectory or
+	  output of `<tt>shar `find port_dir`</tt>' in a
-	  the package) into a <tt>.tar.gz</tt> file, stick it in the
+	  bug report and send it with the <tt>send-pr(1)</tt>
-	  directory
+	  program.  If the uncompressed port is larger than 20KB,
-<tscreen><verb>
+	  you should compress it into a tarfile and use
-ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
+	  <tt>uuencode(1)</tt> before including it in the bug report
-</verb></tscreen>
+	  (uuencoded tarfiles are acceptable even if the report is
-	  and send mail to us using <tt>send-pr(1)</tt> (please
+	  smaller than 20KB but are not preferred).  Be sure to classify
-	  classify it as category `ports' and class `change-request').
+	  the bug report as category `ports' and class `change-request'.
-	  There is no need to upload the package, we will build it by
+
-	  ourselves.
+	<p>One more time, <em>do not include the original source distfile,
-	  We will take a look, get back to you if necessary, and put
+	  the <tt>work/</tt> directory, or the package you built with
+	  `<tt>make package</tt>'!</em>
+
+	<p>See
+	  <ref id="contrib:general" name="Bug Reports and General Commentary">
+	  for more information.
+
+	<p>We will look at your port, get back to you if necessary, and put
 	  it in the tree.  Your name will also appear in the list of
 	  `Additional FreeBSD contributors' on the FreeBSD Handbook
 	  and other files.  Isn't that great?!? <tt>:)</tt>
@@ -371,7 +382,7 @@ ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
 	    it will save the file in <tt>&dollar;{DISTDIR}</tt> for
 	    future use and proceed.
 
-	  <item>The extract target is run.  It looks for your ports'
+	  <item>The extract target is run.  It looks for your port's
 	    distribution file in <tt>&dollar;{DISTDIR}</tt> (typically
 	    a gzip'd tarball) and unpacks it into a temporary
 	    subdirectory specified by <tt>&dollar;{WRKDIR}</tt>
@@ -589,7 +600,7 @@ foozolix-1.0.tar.gz
 work/foozolix-1.0/
 </verb></tscreen>
 
-	  All this behavior can be overridden, of course, it simply
+	  All this behavior can be overridden, of course; it simply
 	  represents the most common time-saving defaults.  For a port
 	  requiring multiple distribution files, simply set
 	  <tt>&dollar;{DISTFILES}</tt> explicitly.  If only a subset
@@ -1197,7 +1208,7 @@ diff -u -r1.15 PLIST
 	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 ports directories
-	to us (i.e., if your modified ports directory is called
+	to us (e.g., if your modified port directory is called
 	`<tt>superedit</tt>' and the original as in our tree is
 	`<tt>superedit.bak</tt>', then send us the result of `<tt>diff
 	-ruN superedit.bak superedit</tt>').  Please examine the output
@@ -1210,10 +1221,17 @@ diff -u -r1.15 PLIST
 	uuencode it; otherwise, just include it in as is in the PR.
 
     <sect2>
-      <heading>Do's and Dont's</heading>
+      <heading>Do's and Dont's
+      <label id="porting:dads"></heading>
 
       <p>Here is a list of common do's and dont's that you encounter
-	during the porting process.
+	during the porting process.  You should check your own port
+	against this list, but you can also check ports in the PR
+	database that others have submitted.  Submit any comments on
+	ports you check as described in <ref id="contrib:general"
+	name="Bug Reports and General Commentary">.  Checking ports in
+	the PR database will both make it faster for us to commit them,
+	and prove that you know what you are doing.
 
       <sect3>
 	<heading>WRKDIR</heading>
@@ -1227,13 +1245,11 @@ diff -u -r1.15 PLIST
 	  copy them to the <tt>work</tt> subdirectory.
 
       <sect3>
-	<heading>Package information</heading>
+	<heading>Portlint Clean</heading>
 
-	<p>Do include package information, i.e. <tt>COMMENT</tt>,
+	<p>Do use <tt>portlint</tt>!  The <tt>
-	  <tt>DESCR</tt>, and <tt>PLIST</tt>, in
+	  <htmlurl url="http://www.freebsd.org/cgi/ports.cgi?portlint"
-	  <tt>pkg</tt>.  Note that these files are not used only for
+	  name="portlint"></tt> program is part of the ports collection.
-	  packaging anymore, and are <em>mandatory</em> now, even if
-	  <tt>&dollar;{NO_PACKAGE}</tt> is set.
 
       <sect3>
 	<heading>Compress manpages, strip binaries</heading>
@@ -1352,7 +1368,7 @@ MAN8=      baz.8
 	  <tt>/etc/make.conf</tt>.)
 
 	<p>If you need to display a message to the installer, you may
-	  place the message in <tt>pkg/MESSAGE</tt>.  This capibility
+	  place the message in <tt>pkg/MESSAGE</tt>.  This capability
 	  is often useful to display additional installation steps to
 	  be taken after a pkg_add, or to display licensing information.
 	  (note: the MESSAGE file does not need to be added to pkg/PLIST).
@@ -1410,7 +1426,7 @@ MAN8=      baz.8
 	  configure, etc., are unnecessary and should be deleted.
 	  Also, if you had to delete a file, then you can do it in the
 	  <tt>post-extract</tt> target rather than as part of the
-	  patch.  Once you are happy with the resuling diff, please
+	  patch.  Once you are happy with the resulting diff, please
 	  split it up into one source file per patch file.
 
       <sect3>
@@ -1533,6 +1549,36 @@ msql:*:80:249:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
 	  port that allocates a new UID in this range so we can keep
 	  this list up to date.
 
+      <sect3>
+	<heading>Do things rationally</heading>
+
+	<p>The Makefile should do things simply and reasonably.  If you
+	  can make it a couple of lines shorter or more readable, then
+	  do so.  Examples include using a make `<tt>.if</tt>' construct
+	  instead of a shell `<tt>if</tt>' construct, not redefining
+	  <tt>do-extract</tt> if you can redefine <tt>&dollar;{EXTRACT*}</tt>
+	  instead, and using <tt>&dollar;GNU_CONFIGURE</tt> instead of
+	  `<tt>CONFIGURE_ARGS += --prefix=&dollar;{PREFIX}</tt>'.
+
+      <sect3>
+	<heading>Respect CFLAGS</heading>
+
+	<p>The port should respect the <tt>&dollar;{CFLAGS}</tt> variable.
+	  If it doesn't, please add `<tt>NO_PACKAGE=ignores cflags</tt>'
+	  to the Makefile.
+
+      <sect3>Miscellanea</heading>
+
+	<p>The files <tt>pkg/DESCR</tt>, <tt>pkg/COMMENT</tt>, and
+	  <tt>pkg/PLIST</tt> should each be double-checked.  If you are
+	  reviewing a port and feel they can be worded better, do so.
+
+	<p>Don't copy more copies of the GNU General Public License into
+	  our system, please.
+
+	<p>Please be careful to note any legal issues!  Don't let us
+	  illegally distribute software!
+
       <sect3>
 	<heading>If you are stuck....</heading>
 

handbook/submitters.sgml

@@ -1,4 +1,4 @@
-<!-- $Id: submitters.sgml,v 1.178 1998-04-25 16:08:58 kuriyama Exp $ -->
+<!-- $Id: submitters.sgml,v 1.179 1998-04-27 00:40:15 hoek Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <chapt><heading>Contributing to FreeBSD<label id="contrib"></heading>
@@ -304,7 +304,8 @@ it using the <tt>send-pr(1)</tt> program or its
 <url url="http://www.freebsd.org/send-pr.html" name="WEB-based equivalent">.
 Try to fill-in each field of the bug report.  Unless they exceed
 65KB, include any patches directly in the report.  Consider compressing
-them and using <tt>uuencode(1)</tt> if they exceed 20KB.
+them and using <tt>uuencode(1)</tt> if they exceed 20KB.  Upload very
+large submissions to <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">.
 
 After filing a report, you should receive confirmation along with
 a tracking number.  Keep this tracking number so that you can