Updated some wording for 3.x.

Added MASTER_STIE_LOCAL and updated it's location.
Added -N to diff options to ensure the diff includes new files.
Mentioned that USENET news ports should use ${PREFIX}/news.
Refromatted some of the comments w/in the sample Makefile so they wouldn't
	wrap in the latin1 format.
General updating and minor word changes.

1 files changed, 51 insertions, 37 deletions

diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml
index 6833286..de29944 100644
--- a/share/doc/handbook/porting.sgml
+++ b/share/doc/handbook/porting.sgml
@@ -1,10 +1,12 @@
-<!-- $Id: porting.sgml,v 1.69 1997/03/10 11:55:17 asami Exp $ -->
+<!-- $Id: porting.sgml,v 1.70 1997/05/18 03:35:01 asami Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
 
 <p><em>Contributed by &a.jkh;, &a.gpalmer; and
       &a.asami;.<newline>28 August 1996.</em>
+<p><em>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
+      &a.obrien;.<newline>28 August 1996.</em>
 
 <p>The porting of freely available software, while perhaps not as
 gratifying as developing your own from scratch, is still a vital part
@@ -18,10 +20,11 @@ of the sources being ported, but merely those differences required for
 running under FreeBSD. 
 
 <p>What follows are some guidelines for creating a new port for
-FreeBSD 2.x.  The bulk of the work is done by
+FreeBSD 3.x.  The bulk of the work is done by
 <tt>/usr/share/mk/bsd.port.mk</tt>, which all port Makefiles include.
 Please refer to that file for more details on the inner workings of
-the ports collection.
+the ports collection.  Even if you don't hack Makefiles daily, it is
+well commented, and you will still gain much knowledge from it.
 
     <sect2>
       <heading>Before Starting the Port<label id="porting:starting"></heading>
@@ -30,8 +33,8 @@ the ports collection.
 	(<tt>&dollar;{..}</tt>) are mentioned in this document. Most
 	(if not all) are documented at the start of
 	<tt>bsd.port.mk</tt>.  This file uses a non-standard tab
-	setting. <tt>Emacs</tt> should recognize the setting on
-	loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to
+	setting. <tt>Emacs</tt> and <tt>Vim</tt> should recognize the setting
+	on loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to
 	using the correct value by typing `<tt>:set tabstop=4</tt>'
 	once the file has been loaded.
 
@@ -41,9 +44,9 @@ the ports collection.
 	for conditional compilation, make sure you make the changes as
 	general as possible so that we can back-port code to FreeBSD
 	1.x systems and cross-port to other BSD systems such as 4.4BSD
-	from CSRG, BSD/386, 386BSD and NetBSD.
+	from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.
 
-      <p>The preferred way to tell 4.3BSD/Reno and newer versions of
+      <p>The preferred way to tell 4.3BSD/Reno (1990) and newer versions of
 	the BSD code apart is by using the `<tt>BSD</tt>' macro
 	defined in <tt>&lt;sys/param.h&gt;</tt>.  Hopefully that file
 	is already included; if not, add the code:
@@ -58,7 +61,8 @@ the ports collection.
         system that defines these to symbols has sys/param.h.  If you find
         a system that doesn't, we would like to know.  Please send mail to
         <htmlurl url='mailto:ports@FreeBSD.org' name='ports@FreeBSD.org'>.
-	  <p>Or you can use the GNU Autoconf style of doing this:
+
+      <p>Another way is to use the GNU Autoconf style of doing this:
 
 <tscreen><verb>
 #ifdef HAVE_SYS_PARAM_H
@@ -105,15 +109,16 @@ the ports collection.
 	  Berkeleyisms, not FreeBSD changes.
 
 	<item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is defined to be
-	  <tt>2</tt>.  In earlier versions, it is <tt>1</tt>.
+	  <tt>2</tt>.  In earlier versions, it is <tt>1</tt>.  Later
+	  versions will bump it to match their major version number.
 
 	<item>If you need to tell the difference between a FreeBSD 1.x
-	  system and a FreeBSD 2.x system, usually the right answer is
+	  system and a FreeBSD 2.x or 3.x system, usually the right answer is
 	  to use the <tt>BSD</tt> macros described above.  If there
 	  actually is a FreeBSD specific change (such as special
 	  shared library options when using `<tt>ld</tt>') then it is
 	  OK to use <tt>__FreeBSD__</tt> and `<tt>#if __FreeBSD__ &gt;
-	  1</tt>' to detect a FreeBSD 2.x system.
+	  1</tt>' to detect a FreeBSD 2.x and later system.
 
 	  If you need more granularity in detecting FreeBSD systems since
 	  2.0-RELEASE you can use the following:
@@ -236,8 +241,8 @@ 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, please do not just copy the <tt>README</tt>
-	    file here, unless, of course, it is a concise description
+	    In particular, <em>please do not just copy the <tt>README</tt>
+	    file here</em>, unless, of course, it is a concise description
 	    of the port.
 
 	  <p>It is recommended that you sign the name at the end of
@@ -260,7 +265,8 @@ asami@cs.berkeley.edu
 	    is also called the `packing list' because the package is
 	    generated by packing the files listed here.  The pathnames
 	    are relative to the installation prefix (usually
-	    <tt>/usr/local</tt> or <tt>/usr/X11R6</tt>).
+	    <tt>/usr/local</tt> or <tt>/usr/X11R6</tt>)  Also it is assumed
+	    the manpages will be compressed.
 
 	  <p>Here is a small example:
 
@@ -438,9 +444,10 @@ ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
 	  non-standard formats, we can `house' it ourselves by putting
 	  it on
 <tscreen><verb>
-ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/
+ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/
 </verb></tscreen>
-	  as the last resort.  Send mail to the &a.ports
+	  as the last resort.  Please refer to this localation as
+	  <tt>&dollar;{MASTER_SITE_LOCAL}</tt>.  Send mail to the &a.ports
 	  if you are not sure what to do.
 
 	<p>If your port requires some additional `patches' that are
@@ -927,9 +934,10 @@ FETCH_DEPENDS=   ncftp2:${PORTSDIR}/net/ncftp2
 	to us (i.e., if your modified ports 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
-	-ru superedit.bak superedit</tt>').  Please examine the output
+	-ruN superedit.bak superedit</tt>').  Please examine the output
 	to make sure all the changes make sense.  The best way to send
-	us the diff is by including it to <tt>send-pr(1)</tt>.  Please
+	us the diff is by including it to <tt>send-pr(1)</tt> (category
+	`ports').  Please
 	mention any added or deleted files in the message, as they
 	have to be explicitly specified to CVS when doing a commit.
 
@@ -945,14 +953,15 @@ FETCH_DEPENDS=   ncftp2:${PORTSDIR}/net/ncftp2
 	<p>Do not leave anything valuable lying around in the
 	  <tt>work</tt> subdirectory, `<tt>make clean</tt>' will
 	  <em>nuke</em> it completely!  If you need auxiliary files
-	  that are not scripts or patches, put them in the subdirectory
-	  <tt>files</tt> and use the <tt>post-extract</tt> target to
+	  that are not scripts or patches, put them in the
+	  <tt>&dollar;{FILESDIR}</tt> subdirectory (files/ by default)
+	  and use the <tt>post-extract</tt> target to
 	  copy them to the <tt>work</tt> subdirectory.
 
       <sect3>
 	<heading>Package information</heading>
 
-	<p>Do install package information, i.e., the three files in
+	<p>Do include package information, i.e. COMMENT, DESCR, and PLIST, in
 	  <tt>pkg</tt>.  Note that these files are not used only for
 	  packaging anymore, and are <em>mandatory</em> now, even if
 	  <tt>&dollar;{NO_PACKAGE}</tt> is set.
@@ -1007,7 +1016,7 @@ MAN8=      baz.8
 	  <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).
+	    manpages and other documentation (it doesn't compress anything).
 	</itemize>
 
 	<p>These are basically the <tt>install</tt> command with all
@@ -1064,7 +1073,7 @@ MAN8=      baz.8
  post-install:
  .if !defined(NOPORTDOCS)
 	 ${MKDIR} ${PREFIX}/share/doc/xv
-	 ${INSTALL_DATA} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+	 ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
  .endif
 </verb></tscreen>
 
@@ -1128,11 +1137,12 @@ MAN8=      baz.8
 	  to generate patches is fine, but please take a look at the
 	  resulting patches to make sure you don't have any
 	  unnecessary junk in there.  In particular, diffs between two
-	  backup files, Makefiles when the port uses imake or GNU
+	  backup files, Makefiles when the port uses Imake or GNU
 	  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.
+	  patch.  Once you are happy with the resuling diff, please
+	  split it up into one source file per patch file.
 
       <sect3>
 	<heading>PREFIX</heading>
@@ -1181,7 +1191,7 @@ MAN8=      baz.8
 	  incorrect.  Also, many ports put everything except binaries,
 	  header files and manual pages in the a subdirectory of
 	  `<tt>lib</tt>', which does not bode well with the BSD
-	  paradigm.  Many of the files should me moved to one of the
+	  paradigm.  Many of the files should be moved to one of the
 	  following: `<tt>etc</tt>' (setup/configuration files),
 	  `<tt>libexec</tt>' (executables started internally),
 	  `<tt>sbin</tt>' (executables for superusers/managers),
@@ -1189,7 +1199,9 @@ MAN8=      baz.8
 	  `<tt>share</tt>' (architecture independent files).  See man
 	  <tt>hier(7)</tt> for details, the rule governing
 	  <tt>/usr</tt> pretty much applies to <tt>/usr/local</tt>
-	  too.
+	  too.  The exception are ports dealing with USENET `news'.
+	  They may use <tt>&dollar;{PREFIX}/news</tt> as a destination
+	  for their files.
 
       <sect3>
 	<heading>ldconfig</heading>
@@ -1265,7 +1277,8 @@ lib/libtcl.so.7.3
  DISTNAME=	xdvi
  PKGNAME=	xdvi-pl18
  CATEGORIES=	print
- [do not forget the trailing slash ("/")!]
+ [do not forget the trailing slash ("/")! 
+  if you aren't using MASTER_SITE_* macros]
  MASTER_SITES=	${MASTER_SITE_XCONTRIB}
  MASTER_SITE_SUBDIR= applications
  [set this if the source is not in the standard ".tar.gz" form]
@@ -1278,24 +1291,24 @@ lib/libtcl.so.7.3
  [maintainer; *mandatory*!  This is the person (preferably with commit
   privileges) who a user can contact for questions and bug reports - this
   person should be the porter or someone who can forward questions to the
-  original porter reasonably promptly.  If you really do not want to have your
-  address here, set it to "ports@FreeBSD.ORG".]
+  original porter reasonably promptly.  If you really do not want to have
+  your address here, set it to "ports@FreeBSD.ORG".]
  MAINTAINER=	asami@FreeBSD.ORG
  
  [dependencies -- can be empty]
  RUN_DEPENDS=	gs:${PORTSDIR}/print/ghostscript
  LIB_DEPENDS=	Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
  
- [this section is for other standard bsd.port.mk variables that do not belong 
-  to any of the above]
+ [this section is for other standard bsd.port.mk variables that do not
+  belong to any of the above]
  [If it asks questions during configure, build, install...]
  IS_INTERACTIVE=	yes
  [If it extracts to a directory other than ${DISTNAME}...]
  WRKSRC=		${WRKDIR}/xdvi-new
- [If the distributed patches were not made relative to ${WRKSRC}, you may need
- to tweak this]
+ [If the distributed patches were not made relative to ${WRKSRC}, you
+  may need to tweak this]
  PATCH_DIST_STRIP=	-p1
- [If it requires a "configure" script generated by GNU autoconf to be run...]
+ [If it requires a "configure" script generated by GNU autoconf to be run]
  GNU_CONFIGURE= yes
  [If it requires GNU make, not /usr/bin/make, to build...]
  USE_GMAKE=	yes
@@ -1341,8 +1354,9 @@ lib/libtcl.so.7.3
 	<item>FreeBSD strives to support the native language of its
 	  users.  The `&lt;language&gt;' part should be a two letter
 	  abbreviation of the natural language if the port is specific
-	  to a certain language.  Examples are `jp' for Japanese and
-	  `ru' for Russian.
+	  to a certain language.  Examples are `jp' for Japanese,
+	  `ru' for Russian, `vn' for Vietnamese, `cn' for Chinese,
+	  and `kr' for Korean.
 
         <item>The `<tt>&lt;name&gt;</tt>' part should be all
 	  lowercases, except for a really large package (with lots of