Added some guideline to write pkg/COMMENT.

Added reference to pkg_create(1) man page in the explanation of the packing
list.

Added description of ${INSTALL_*} macros.

Added an explanation to use patch files distributed in .tar.gz format.

Added statement about the copyright on the submitted files.

Slgith change in sample Makefile.

Written mostly by:	asami

handbook/porting.sgml

@@ -1,4 +1,4 @@
-<!-- $Id: porting.sgml,v 1.31 1996-10-05 18:36:19 wosch Exp $ -->
+<!-- $Id: porting.sgml,v 1.32 1996-10-29 11:55:06 max Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
@@ -157,7 +157,7 @@ The pattern is the year followed by the month.
  # Date created:	5 December 1994
  # Whom:		asami
  #
- # $Id: porting.sgml,v 1.31 1996-10-05 18:36:19 wosch Exp $
+ # $Id: porting.sgml,v 1.32 1996-10-29 11:55:06 max Exp $
  #
  
  DISTNAME=	oneko-1.1b
@@ -189,8 +189,9 @@ The pattern is the year followed by the month.
 	  <heading>COMMENT</heading>
 
 	  <p>This is the one-line description of the port.  It is
-	    recommended to not have the name of the package at the
+	    recommended to <em>not</em> have the name of the package
-	    beginning, as in:
+	    at the beginning, or the version number of the software at
+	    the end.  Here is an example:
 <tscreen><verb>
 A cat chasing a mouse all over the screen.
 </verb></tscreen>
@@ -239,6 +240,9 @@ lib/X11/oneko/cat2.xpm
 lib/X11/oneko/mouse.xpm
 </verb></tscreen>
 
+	  <p>Refer to the <tt>pkg_create(1)</tt> man page for details
+	    on the packing list.
+
       <sect3>
 	<heading>Creating the checksum file</heading>
 
@@ -435,6 +439,11 @@ ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/
 	  as possible for the end-user while using a minimum of disk
 	  space.
 
+	<p>Note: Unless explicitly stated, patch files, scripts, and
+	  other files you have created and contributed to the FreeBSD
+	  ports collection are assumed to be covered by the standard
+	  BSD copyright conditions.
+
       <sect3>
 	<heading>Patching</heading>
 
@@ -593,6 +602,23 @@ work/foozolix-1.0/
 	  decompressed automatically if the filenames end with
 	  `<tt>.gz</tt>' or `<tt>.Z</tt>'.
 
+	<p>If the patch is distributed with some other files, such as
+	  documentation, in a gzip'd tarball, you can't just use
+	  <tt>&dollar;{PATCHFILES}</tt>.  If that is the case, add the
+	  name and the location of the patch tarball to
+	  <tt>&dollar;{DISTFILES}</tt> and
+	  <tt>&dollar;{MASTER_SITES}</tt>.  Then, from the
+	  <tt>pre-patch</tt> target, apply the patch either by running
+	  the patch command from there, or copying the patch file into
+	  the <tt>&dollar;{PATCHDIR}</tt> directory and calling it
+	  <tt>patch-&lt;xx&gt;</tt>.  (Note the tarball will have been
+	  extracted alongside the regular source by then, so there is
+	  no need to explicitly extract it if it is a regular gzip'd
+	  or compress'd tarball.)  If you do the latter, take extra
+	  care not to overwrite something that already exists in that
+	  directory.  Also do not forget to add a command to remove
+	  the copied patch in the <tt>pre-clean</tt> target.
+
       <sect3>
 	<heading>MAINTAINER</heading>
 
@@ -894,6 +920,27 @@ FETCH_DEPENDS=   ncftp2:${PORTSDIR}/net/ncftp2
 	  to check whether the binary is stripped or not.  If it
 	  does not say `not stripped', it is stripped.
 
+      <sect3>
+	<heading>INSTALL_* macros</heading>
+	<p>Do use the macros provided in bsd.port.mk to ensure correct 
+	  modes and ownership of files in your own *-install targets.
+	  They are:
+
+	<itemize>
+	  <item><tt>${INSTALL_PROGRAM}</tt> is a command to install
+	    binary executables.
+	  <item><tt>${INSTALL_SCRIPT}</tt> is a command to install
+	    executable scripts.
+	  <item><tt>${INSTALL_DATA}</tt> is a command to install
+	    sharable data.
+	  <item><tt>${INSTALL_MAN}</tt> is a command to install
+	    manpages (it doesn't do compression).
+	</itemize>
+
+	<p>These are basically the <tt>install</tt> command with all
+	  the appropriate flags.  See below for an example on how to
+	  use them.
+
       <sect3>
 	<heading>Install additional documentation</heading>
 
@@ -917,7 +964,7 @@ FETCH_DEPENDS=   ncftp2:${PORTSDIR}/net/ncftp2
  post-install:
  .if !defined(NOPORTDOCS)
 	 mkdir -p ${PREFIX}/share/doc/xv
-	 cp ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+	 ${INSTALL_DATA} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
  .endif
 </verb></tscreen>
 
@@ -1098,7 +1145,7 @@ lib/libtcl.so.7.3
   person who wrote this Makefile]
  # Whom:			Satoshi Asami <asami@FreeBSD.ORG>
  #
- # $Id: porting.sgml,v 1.31 1996-10-05 18:36:19 wosch Exp $
+ # $Id: porting.sgml,v 1.32 1996-10-29 11:55:06 max Exp $
  [ ^^^^ do not worry about this, I know it says "porting.sgml"...it
   will be automatically filled in by CVS when it is committed to our
   repository]
@@ -1136,8 +1183,8 @@ lib/libtcl.so.7.3
  WRKSRC=		${WRKDIR}/xdvi-new
  [If it asks questions during configure, build, install...]
  IS_INTERACTIVE=	yes
- [If it requires "configure" in the distributed source directory to be run...]
+ [If it requires a "configure" script generated by GNU autoconf to be run...]
- HAS_CONFIGURE=	yes
+ GNU_CONFIGURE= yes
  [If it requires GNU make, not /usr/bin/make, to build...]
  USE_GMAKE=	yes
  [If it is an X application and requires "xmkmf -a" to be run...]