Point a new user to documentation explaining how to upgrade an existing

port before telling them how to create a new port.

Belatedly document MLINKS.

Seems billf committed to this under my feet, so I guess we're even, now.  :)

3 files changed, 64 insertions, 24 deletions

diff --git a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
index d8899c558b..941210d158 100644
--- a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,7 +1,7 @@
 <!--
      The FreeBSD Documentation Project
 
-     $Id: chapter.sgml,v 1.19 1999-06-20 21:19:04 billf Exp $
+     $Id: chapter.sgml,v 1.20 1999-06-28 03:37:25 hoek Exp $
 -->
 
 <chapter id="cutting-edge">
@@ -1207,7 +1207,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
       </sect3>
       
       <sect3 id="cvsup-config">
-	<title>Configuration</title>
+	<title>CVSup Configuration</title>
 	
 	<para><application>CVSup</application>'s operation is controlled by a
 	  configuration file called the <filename>supfile</filename>.
diff --git a/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
index ba23c97d20..3ecd1fe247 100644
--- a/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
@@ -1,7 +1,7 @@
 <!--
      The FreeBSD Documentation Project
 
-     $Id: chapter.sgml,v 1.32 1999-06-28 02:37:29 billf Exp $
+     $Id: chapter.sgml,v 1.33 1999-06-28 03:37:21 hoek Exp $
 -->
 
 <chapter id="ports">
@@ -946,15 +946,19 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
     <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; &a.obrien;
 	and &a.hoek;.  28 August 1996.</emphasis></para>
 
-    <para>So, now you are interested in making your own port? Great!</para>
+    <para>So, now 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
-      FreeBSD.  The bulk of the work is done by
+      FreeBSD.  If you want to upgrade an existing port, you should read this
+      and then read <xref linkend="port-upgrading">.</para>
+
+    <para>When this document is not sufficiently detailed, you should refer to
       <filename>/usr/ports/Mk/bsd.port.mk</filename>, which all port Makefiles
-      include.  Please refer to that file for more details on the inner
-      workings of the ports collection.  Even if you do not hack Makefiles
+      include.
+                                         Even if you do not hack Makefiles
       daily, it is well commented, and you will still gain much knowledge from
-      it.</para>
+      it.  Additionally, you may send specific questions to &a.ports;.</para>
 	  
     <note>
       <para>Only a fraction of the overridable variables
@@ -963,12 +967,12 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
 	<filename>bsd.port.mk</filename>.  This file users a non-standard tab
 	setting.  <application>Emacs</application> and
 	<application>Vim</application> should recognise the setting on loading
-	the file.  <command>vi</command> or <command>ex</command> can be set
+	the file.  Both <command>vi</command> and <command>ex</command> can be set
 	to use the correct value by typing <command>:set tabstop=4</command>
 	once the file has been loaded.</para>
     </note>
     
-    <sect2>
+    <sect2 id="quick-porting">
       <title>Quick Porting</title>
       
       <para>This section tells you how to do a quick port.  In many cases, it
@@ -2258,6 +2262,14 @@ MASTERDIR=      ${.CURDIR}/../xdvi300
 	depending on the setting of <makevar>NOMANCOMPRESS</makevar> in
 	<filename>/etc/make.conf</filename>.</para>
 	  
+      <para>If your port tries to install multiple names for manpages using
+	symlinks or hardlinks, you must use the <makevar>MLINKS</makevar>
+	variable to identify these.  The link installed by your port will
+	be destroyed and recreated by <filename>bsd.port.mk</filename>
+	to make sure it points to the correct file.  Any manpages
+	listed in MLINKS must not be listed in the
+	<filename>PLIST</filename>.</para>
+	
       <para>To specify whether the manpages are compressed upon installation,
 	use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
 	take three values, <literal>yes</literal>, <literal>no</literal> and
@@ -2294,6 +2306,7 @@ MASTERDIR=      ${.CURDIR}/../xdvi300
 MAN1=          foo.1
 MAN3=          bar.3
 MAN4=          baz.4
+MLINKS=        foo.1 alt-name.8
 MANLANG=       "" ja
 MAN3PREFIX=    ${PREFIX}/share/foobar
 MANCOMPRESSED= yes</programlisting>
@@ -2307,6 +2320,12 @@ ${PREFIX}/share/foobar/man/man3/bar.3.gz
 ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
 ${PREFIX}/man/man4/baz.4.gz
 ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
+
+      <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename>
+	may or may-not be installed by your port.  Regardless, a
+	symlink will be made to join the foo(1) manpage and
+	alt-name(8) manpage.</para>
+	
     </sect2>
 
     <sect2 id="porting-motif">
@@ -2894,14 +2913,15 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
       </note>
     </sect2>
     
-    <sect2>
+    <sect2 id="port-upgrading">
       <title>Upgrading</title>
       
       <para>When you notice that a port is out of date compared to the latest
 	version from the original authors, first make sure you have the latest
 	port.  You can find them in the
 	<filename>ports/ports-current</filename> directory of the ftp mirror
-	sites.</para>
+	sites.  You may also use CVSup to keep your whole ports collection
+	up-to-date, as described in <xref linkend="cvsup-config">.</para>
 	    
       <para>The next step is to send a mail to the maintainer, if one is
 	listed in the port's <filename>Makefile</filename>.  That person may
@@ -2926,7 +2946,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 
       <note>
         <para>Once again, please use &man.diff.1; and not &man.shar.1; to send
-	  updates to existing ports.</para>
+	  updates to existing ports!</para>
       </note>
     </sect2>
     
diff --git a/en_US.ISO_8859-1/books/porters-handbook/book.sgml b/en_US.ISO_8859-1/books/porters-handbook/book.sgml
index ef4b2f1b72..733e58ada7 100644
--- a/en_US.ISO_8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO_8859-1/books/porters-handbook/book.sgml
@@ -1,7 +1,7 @@
 <!--
      The FreeBSD Documentation Project
 
-     $Id: book.sgml,v 1.32 1999-06-28 02:37:29 billf Exp $
+     $Id: book.sgml,v 1.33 1999-06-28 03:37:21 hoek Exp $
 -->
 
 <chapter id="ports">
@@ -946,15 +946,19 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
     <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; &a.obrien;
 	and &a.hoek;.  28 August 1996.</emphasis></para>
 
-    <para>So, now you are interested in making your own port? Great!</para>
+    <para>So, now 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
-      FreeBSD.  The bulk of the work is done by
+      FreeBSD.  If you want to upgrade an existing port, you should read this
+      and then read <xref linkend="port-upgrading">.</para>
+
+    <para>When this document is not sufficiently detailed, you should refer to
       <filename>/usr/ports/Mk/bsd.port.mk</filename>, which all port Makefiles
-      include.  Please refer to that file for more details on the inner
-      workings of the ports collection.  Even if you do not hack Makefiles
+      include.
+                                         Even if you do not hack Makefiles
       daily, it is well commented, and you will still gain much knowledge from
-      it.</para>
+      it.  Additionally, you may send specific questions to &a.ports;.</para>
 	  
     <note>
       <para>Only a fraction of the overridable variables
@@ -963,12 +967,12 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
 	<filename>bsd.port.mk</filename>.  This file users a non-standard tab
 	setting.  <application>Emacs</application> and
 	<application>Vim</application> should recognise the setting on loading
-	the file.  <command>vi</command> or <command>ex</command> can be set
+	the file.  Both <command>vi</command> and <command>ex</command> can be set
 	to use the correct value by typing <command>:set tabstop=4</command>
 	once the file has been loaded.</para>
     </note>
     
-    <sect2>
+    <sect2 id="quick-porting">
       <title>Quick Porting</title>
       
       <para>This section tells you how to do a quick port.  In many cases, it
@@ -2258,6 +2262,14 @@ MASTERDIR=      ${.CURDIR}/../xdvi300
 	depending on the setting of <makevar>NOMANCOMPRESS</makevar> in
 	<filename>/etc/make.conf</filename>.</para>
 	  
+      <para>If your port tries to install multiple names for manpages using
+	symlinks or hardlinks, you must use the <makevar>MLINKS</makevar>
+	variable to identify these.  The link installed by your port will
+	be destroyed and recreated by <filename>bsd.port.mk</filename>
+	to make sure it points to the correct file.  Any manpages
+	listed in MLINKS must not be listed in the
+	<filename>PLIST</filename>.</para>
+	
       <para>To specify whether the manpages are compressed upon installation,
 	use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
 	take three values, <literal>yes</literal>, <literal>no</literal> and
@@ -2294,6 +2306,7 @@ MASTERDIR=      ${.CURDIR}/../xdvi300
 MAN1=          foo.1
 MAN3=          bar.3
 MAN4=          baz.4
+MLINKS=        foo.1 alt-name.8
 MANLANG=       "" ja
 MAN3PREFIX=    ${PREFIX}/share/foobar
 MANCOMPRESSED= yes</programlisting>
@@ -2307,6 +2320,12 @@ ${PREFIX}/share/foobar/man/man3/bar.3.gz
 ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
 ${PREFIX}/man/man4/baz.4.gz
 ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
+
+      <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename>
+	may or may-not be installed by your port.  Regardless, a
+	symlink will be made to join the foo(1) manpage and
+	alt-name(8) manpage.</para>
+	
     </sect2>
 
     <sect2 id="porting-motif">
@@ -2894,14 +2913,15 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
       </note>
     </sect2>
     
-    <sect2>
+    <sect2 id="port-upgrading">
       <title>Upgrading</title>
       
       <para>When you notice that a port is out of date compared to the latest
 	version from the original authors, first make sure you have the latest
 	port.  You can find them in the
 	<filename>ports/ports-current</filename> directory of the ftp mirror
-	sites.</para>
+	sites.  You may also use CVSup to keep your whole ports collection
+	up-to-date, as described in <xref linkend="cvsup-config">.</para>
 	    
       <para>The next step is to send a mail to the maintainer, if one is
 	listed in the port's <filename>Makefile</filename>.  That person may
@@ -2926,7 +2946,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 
       <note>
         <para>Once again, please use &man.diff.1; and not &man.shar.1; to send
-	  updates to existing ports.</para>
+	  updates to existing ports!</para>
       </note>
     </sect2>