Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 20 Jan 2004 16:47:28 -0600 (CST)
From:      Mark Linimon <linimon@lonesome.com>
To:        FreeBSD-gnats-submit@FreeBSD.org
Subject:   docs/61653: [patch] cleanup after recent changes to Porter's Handbook
Message-ID:  <200401202247.i0KMlSuU076489@lonesome.lonesome.com>
Resent-Message-ID: <200401202250.i0KMoGwq075402@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>Number:         61653
>Category:       docs
>Synopsis:       [patch] cleanup after recent changes to Porter's Handbook
>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 Jan 20 14:50:16 PST 2004
>Closed-Date:
>Last-Modified:
>Originator:     Mark Linimon
>Release:        FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #0: Fri Sep 5 01:19:33 CDT 2003 linimon@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA_DEBUG i386
	(n/a)
>Description:
	The recent commit of my changes to the Porter's Handbook left
	some rough edges; this patch fixes them.

	First, some text was proposed but not accepted; there was
	some dangling text left behind that kind-of went with the
	rejected text.  Next, some content that was added to replace
	existing content, or move it around, didn't have the original
	text deleted afterwards.  Third, there are some places where
	a concept is introduced, then elaborated on, then the reason
	is given for having the concept.  This patch switches those
	latter two around.  Lastly, in a few places the language
	wound up being awkward.

	There is no new content in this patch; it's just a cleanup
	that IMHO makes the document "flow" a little bit better.
>How-To-Repeat:
	(n/a)
>Fix:

--- book.sgml.dist	Tue Jan 20 16:33:11 2004
+++ book.sgml	Tue Jan 20 16:33:16 2004
@@ -64,7 +64,7 @@
     <chapter id="own-port">
       <title>Making a port yourself</title>
 
-      <para>So, you are still interested in making your own port or
+      <para>So, you are interested in making your own port or
 	upgrading an existing one?  Great!</para>
 
       <para>What follows are some guidelines for creating a new port for
@@ -348,8 +348,19 @@
 	  Also add a short description of the program you ported
 	  to the <quote>Description</quote> field of the PR and
 	  the shar or uuencoded tarfile to the
-	  <quote>Fix</quote> field.  The latter one helps the committers
-	  a lot, who use scripts for the ports-work.</para>
+	  <quote>Fix</quote> field.</para>
+
+	<note>
+	  <para>You can make our work a lot easier, if you use a good
+	    description in the synopsis of the problem report.
+	    We prefer something like
+	    <quote>New port: &lt;category&gt;/&lt;portname&gt;
+	    &lt;short description of the port&gt;</quote> for new ports and
+	    <quote>Update port: &lt;category&gt;/&lt;portname&gt;
+	    &lt;short description of the update&gt;</quote> for port updates.
+	    If you stick to this scheme, the chance that someone takes a
+	    look at your PR soon is much bigger.</para>
+	</note>
 
 	<para>One more time, <emphasis>do not include the original source
 	    distfile, the <filename>work</filename> directory, or the package
@@ -375,18 +386,6 @@
 	  <ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
 	  and other files. Isn't that great?!? <!-- smiley
 	  -->:-)</para>
-
-	<note>
-	  <para>You can make our work a lot easier, if you use a good
-	    description in the synopsis of the problem report.
-	    We prefer something like
-	    <quote>New port: &lt;short description of the port&gt;</quote> for
-	    new ports and
-	    <quote>Update port: &lt;category&gt;/&lt;port&gt; &lt;short description
-	    of the update&gt;</quote> for port updates.
-	    If you stick to this scheme, the chance that one takes a look at
-	    your PR soon is much bigger.</para>
-	</note>
       </sect1>
     </chapter>
 
@@ -757,8 +756,13 @@
 	    every increase of <makevar>PORTVERSION</makevar> (i.e.
 	    every time a new official vendor release is made), and
 	    appended to the package name if non-zero.
-	    <makevar>PORTREVISION</makevar> is increased each time a
-	    change is made to the FreeBSD port which significantly
+	    Changes to <makevar>PORTREVISION</makevar> are
+	    used by automated tools (e.g.  &man.pkg.version.1;)
+	    to highlight the fact that a new package is
+	    available.</para>
+
+	  <para><makevar>PORTREVISION</makevar> should be increased
+	    each time a change is made to the port which significantly
 	    affects the content or structure of the derived
 	    package.</para>
 
@@ -769,7 +773,7 @@
 	    <listitem>
 	      <para>Addition of patches to correct security
 		vulnerabilities, bugs, or to add new functionality to
-		the FreeBSD port.</para>
+		the port.</para>
 	    </listitem>
 
 	    <listitem>
@@ -832,7 +836,7 @@
 		the changes do not introduce any functional change on
 		any other platforms on which the port did previously
 		build). Since <makevar>PORTREVISION</makevar> reflects
-		the content of the package, if no package was
+		the content of the package, if the package was not
 		previously buildable then there is no need to increase
 		<makevar>PORTREVISION</makevar> to mark a
 		change.</para>
@@ -846,10 +850,7 @@
 	    actually work at all), and weigh that against that fact
 	    that it will cause everyone who regularly updates their
 	    ports tree to be compelled to update. If yes, the
-	    <makevar>PORTREVISION</makevar> should be bumped so that
-	    automated tools (e.g.  &man.pkg.version.1;)
-	    will highlight the fact that a new package is
-	    available.</para>
+	    <makevar>PORTREVISION</makevar> should be bumped.</para>
 	</sect3>
 
 	<sect3>
@@ -1577,7 +1578,7 @@
 		  safely delete <literal>misc</literal> and just put the port
 		  in that other subdirectory!  If at all possible, try to
 		  find a better category for your port than
-		  <literal>misc</literal> ports tend to get overlooked
+		  <literal>misc</literal>, as ports tend to get overlooked
 		  in here.</entry>
 	      </row>
 
@@ -1814,8 +1815,7 @@
 		  If your port <emphasis>is</emphasis> an X
 		  application, define <makevar>USE_XLIB</makevar> (implied by
 		  <makevar>USE_IMAKE</makevar>) and put it in the appropriate
-		  categories.  Also, many of them go into other
-		  <filename>x11-*</filename> categories (see below).</entry>
+		  category.</entry>
 	      </row>
 
 	      <row>
@@ -1938,7 +1938,7 @@
 	<para><makevar>DISTNAME</makevar> is the name of the port as
 	  called by the authors of the software.
 	  <makevar>DISTNAME</makevar> defaults to
-	  <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it if necessary.
+	  <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it only if necessary.
 	  <makevar>DISTNAME</makevar> is only used in two places.
 	  First, the distribution file list
 	  (<makevar>DISTFILES</makevar>) defaults to
@@ -1950,7 +1950,7 @@
 	<note>
 	  <para><makevar>PKGNAMEPREFIX</makevar> and
 	    <makevar>PKGNAMESUFFIX</makevar> do not affect
-	    <makevar>DISTNAME</makevar>.  Also note that when
+	    <makevar>DISTNAME</makevar>.  Also note that if
 	    <makevar>WRKSRC</makevar> is equal to
 	    <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
 	    while the original source archive is named something other than
@@ -1997,7 +1997,7 @@
 
 	<para>These variables are defined in
 	  <filename>/usr/ports/Mk/bsd.sites.mk</filename>.  There are
-	  new archives added all the time, so make sure to check the
+	  new entries added all the time, so make sure to check the
 	  latest version of this file before submitting a port.</para>
 
 	<para>The user can also set the <makevar>MASTER_SITE_*</makevar>
@@ -2793,7 +2793,9 @@
 	<para>Set your mail-address here.  Please.  <!-- smiley
 	  --><emphasis>:-)</emphasis></para>
 
-	<para>The format used should be <literal>user@hostname.domain</literal>.
+	<para>Note that only a single address without comment part is
+	  allowed as a <makevar>MAINTAINER</makevar> value.
+	  The format used should be <literal>user@hostname.domain</literal>.
 	  Please do not include any descriptive text such as your real
 	  name in this entry&mdash;that merely confuses
 	  <filename>bsd.port.mk</filename>.  Instead, put that information
@@ -2803,9 +2805,6 @@
 	  refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
 	    Makefiles</ulink> section.</para>
 
-	<para>Note that only a single address without comment part is
-	  allowed as a <makevar>MAINTAINER</makevar> value.</para>
-
 	<para>If the maintainer of a port does not respond to an update
 	  request from a user after two weeks (excluding major public
 	  holidays), then that is considered a maintainer timeout, and the
@@ -3440,7 +3443,7 @@
 	  package is not generally useful, and the application should always
 	  be compiled from the source code.  For example, if the application
 	  has configuration information that is site specific hard coded in to
-	  it at compile time.</para>
+	  it at compile time, set <makevar>NO_PACKAGE</makevar>.</para>
 
 	<para><makevar>NO_PACKAGE</makevar> should be set to a string
 	  describing the reason why the package should not be
@@ -4547,7 +4549,7 @@
 	  occurrences of <filename>/usr/local</filename> (or
 	  <filename>/usr/X11R6</filename> for X ports that do not use imake)
 	  in the various <filename>scripts/Makefile</filename>s in the port to read
-	  <makevar>PREFIX</makevar>, as this variable is automatically passed
+	  <makevar>${PREFIX}</makevar>, as this variable is automatically passed
 	  down to every stage of the build and install processes.</para>
 
 	<para>Make sure your application is not installing things in
@@ -4557,7 +4559,7 @@
 	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>
 
 	<para>If anything is installed outside of <makevar>PREFIX</makevar>,
-	making the package creation process will complain that it
+	the package creation process will complain that it
 	cannot find the files.</para>
 
 	<!-- XXX This paragraph is confusing and poorly indented. -->
@@ -4634,23 +4636,23 @@
 
       <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
+	please make the upgrade and save the result of the
 	recursive <command>diff</command> output
 	of the new and old
-	ports directories to us (e.g., if your modified port directory is
+	ports directories.  (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
+	as <filename>superedit.bak</filename>, then save the result of
 	<command>diff -ruN superedit.bak superedit</command>).  Either
 	unified or context diff is fine, but port committers generally
 	prefer unified diffs.  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>
+	deleted.  Before sendingus the diff, please examine the
+	output to make sure all the changes make sense.</para>
 
-      <para>Please examine
-	the output to make sure all the changes make sense.  The best way to
+      <para> 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,
+	<literal>ports</literal>).  If you are going to be the maintainer for the port,
 	be sure to put <literal>[maintainer update]</literal> at the beginning
 	of your synopsis line and/or set the <quote>Class</quote> of your PR
 	to <literal>maintainer-update</literal>.  Please mention any added or
@@ -4676,8 +4678,8 @@
       </important>
 
       <note>
-	<para>Once again, please use &man.diff.1; and not &man.shar.1; to send
-	  updates to existing ports!</para>
+	<para>Once again, please use &man.diff.1;, and not &man.shar.1;, to send
+	updates to existing ports!</para>
       </note>
     </chapter>
 
@@ -6397,8 +6399,8 @@
 	      number of vulnerable FreeBSD hosts (we like being known
 	      for being secure), however sometimes there is a
 	      noticeable time gap between disclosure of a
-	      vulnerability and an updated software release of a piece
-	      of vulnerable software.  Do not mark a port
+	      vulnerability and an updated release of the
+	      vulnerable software.  Do not mark a port
 	      <makevar>FORBIDDEN</makevar> for any reason other than
 	      security.</para>
 	  </listitem>
>Release-Note:
>Audit-Trail:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200401202247.i0KMlSuU076489>