docs/62808: Update porter's handbook about RESTRICTED et al...

[Chuck Swiger]

>Number:         62808
>Category:       docs
>Synopsis:       Update porter's handbook about RESTRICTED et al...
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Feb 13 16:50:07 PST 2004
>Closed-Date:
>Last-Modified:
>Originator:     Chuck Swiger
>Release:        FreeBSD 4.9-STABLE i386
>Organization:
PKIx
>Environment:
System: FreeBSD ns1.pkix.net 4.9-STABLE FreeBSD 4.9-STABLE #9: Tue Dec 2 16:05:30 EST 2003 root at ns1.pkix.net:/usr/obj/usr/src/sys/NORMAL i386

>Description:

Kris Kennaway (wearing his <portmgr> hat?) clarified how RESTRICTED
versus NO_CDROM should be used in port Makefiles, and refered to
bsd.ports.mk.  Based on his comments and that file, I've updated that
section of the Porter's Handbook to correspond more closely.

>How-To-Repeat:

N/A.

>Fix:

--- book.sgml_orig	Fri Feb 13 18:15:59 2004
+++ book.sgml	Fri Feb 13 19:22:18 2004
@@ -3416,7 +3416,7 @@
     <sect1 id="porting-restrictions">
       <title>Ports with distribution restrictions</title>
 
-      <para>Licenses vary, and some of them place restrictions on how the
+      <para>Software licenses vary, and some ports have restrictions on how the
 	application can be packaged, whether it can be sold for profit, and so
 	on.</para>
 
@@ -3428,26 +3428,28 @@
 	  please contact the &a.ports;.</para>
       </important>
 
-      <para>In situations like this, the following variables can be set.  In
-	addition, <filename>ports/LEGAL</filename> should also be
-	updated.</para>
+      <para>If a port contains license restrictions, the port
+	  committer should add an entry to <filename>ports/LEGAL</filename>
+	  describing exactly what the license restriction entails.
+	  In addition, the following variables should be set in the
+	  port's <filename>Makefile</filename>:
+      </para>
 
       <sect2>
-	<title><makevar>NO_PACKAGE</makevar></title>
-
-	<para>This variable indicates that we may not generate a binary
-	  package of the application.  However, the port's
-	  <makevar>DISTFILES</makevar> files may be freely distributed.</para>
+	<title><makevar>RESTRICTED</makevar></title>
 
-	<para><makevar>NO_PACKAGE</makevar> should also be used if the binary
-	  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, set <makevar>NO_PACKAGE</makevar>.</para>
+	<para>Set this variable if the application's license forbids us
+	  from mirroring the application's <makevar>DISTFILES</makevar> or
+	  distributing pre-built packages of the port via FTP or CD-ROM.
+	</para>
 
-	<para><makevar>NO_PACKAGE</makevar> should be set to a string
-	  describing the reason why the package should not be
-	  generated.</para>
+	<para><makevar>RESTRICTED</makevar> should be set to a string
+	  describing the reason why the port cannot be redistributed.
+	  Typically, this indicates that the port contains proprietary
+	  software and that the user will need to manually download the
+	  <makevar>DISTFILES</makevar> for themselves, possibly after
+	  registering for the software or agreeing to accept the terms of
+	  an EULA.</para>
       </sect2>
 
       <sect2>
@@ -3455,29 +3457,36 @@
 
 	<para>This variable indicates that although we are allowed to generate
 	  binary packages, we are not allowed to put those packages, or the
-	  port's <makevar>DISTFILES</makevar>, onto a CDROM (or DVD-ROM)
-	  for resale.  The
-	  <makevar>DISTFILES</makevar> will still be available via FTP
-	  (or HTTP if you set it up that way.)</para>
+	  port's <makevar>DISTFILES</makevar>, onto a CD-ROM (or DVD-ROM)
+	  for resale.  However, the prebuilt binary packages and the port's
+	  <makevar>DISTFILES</makevar> will still be available via FTP.</para>
 
-	<para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
-	  can be set simultaneously.</para>
+	<para><makevar>NO_CDROM</makevar> should be set to a string
+	  describing the reason why the port cannot be redistributed
+	  on CD-ROM.  For instance, this should be used if the port's license
+	  is for "non-commercial" use only.</para>
       </sect2>
 
       <sect2>
-	<title><makevar>RESTRICTED</makevar></title>
+	<title><makevar>NO_PACKAGE</makevar></title>
 
-	<para>Set this variable if the application's license also forbids us
-	  from mirroring the application's <makevar>DISTFILES</makevar> via
-	  FTP (or HTTP if you set it up that way.)</para>
+	<para>This variable indicates that we may not generate a binary
+	  package of the application.  However, the port's
+	  <makevar>DISTFILES</makevar> files may be freely distributed.</para>
 
-	<para>Also set this if the application's license has general
-	  restrictions on who may use it, e.g. the application is for
-	  non-commercial use only.</para>
+	<para><makevar>NO_PACKAGE</makevar> should also be used if the binary
+	  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, set <makevar>NO_PACKAGE</makevar>.</para>
 
-	<para>Note that the port committer should add an entry to
-	  <filename>/usr/ports/LEGAL</filename> describing exactly
-	  what the restriction entails.</para>
+	<para><makevar>NO_PACKAGE</makevar> should be set to a string
+	  describing the reason why the package should not be
+	  generated.</para>
+
+	  <note>
+	    <para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
+	    can be set simultaneously.</para></note>
       </sect2>
 
       <sect2>
@@ -3486,6 +3495,15 @@
 	<para>If only some of the distribution files are restricted then set
 	  this variable to list them.  It defaults to <literal>${DISTFILES}
 	    ${PATCHFILES}</literal>.</para>
+      </sect2>
+
+      <sect2>
+      <title>Related variables</title>
+
+      <para>In addition to the variables above, a port may also be marked as
+        <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or
+	<makevar>IGNORE</makevar>.  Please refer to the following section
+	for additional details:	<xref linkend="dads-broken">.</para>
       </sect2>
     </sect1>
 
>Release-Note:
>Audit-Trail:
>Unformatted: