docs/64384: [patch] add Workarounds section to Porter's Handbook

[Mark Linimon]

>Number:         64384
>Category:       docs
>Synopsis:       [patch] add Workarounds section 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:   Wed Mar 17 10:50:25 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 #3: Thu Jan 22 20:41:05 CST 2004 root at lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
	Recently I got bit by committing a port that broke 'make
	index' -- but only on older versions of FreeBSD that had the
	buggy make.  I knew I had seen something about this, but had
	saved no email about it.  So, let's just define a place towards
	the end of the Porter's Handbook to hold gotchas like this.
>How-To-Repeat:
	Collect some "arrows in the back".
>Fix:
	Tested via make.

	Note to docs gurus: I don't know if there is a preferred
	style to refer to a particular FreeBSD release, so I have
	them listed in plain text.

Index: book.sgml
===================================================================
RCS file: /mnt/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.385
diff -u -r1.385 book.sgml
--- book.sgml	17 Mar 2004 07:14:41 -0000	1.385
+++ book.sgml	17 Mar 2004 18:30:38 -0000
@@ -6639,6 +6639,30 @@
 	  entirely.</para>
       </sect1>
 
+      <sect1 id="dads-workarounds">
+	<title>Necessary workarounds</title>
+
+	<para>Sometimes it is necessary to work around bugs in
+	  software included with older versions of FreeBSD.</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>Some versions of &man.make.1; were broken
+	      on at least 4.8 and 5.0 with respect to handling
+	      comparisons based on <makevar>OSVERSION</makevar>.
+	      This would often lead to failures during
+	      <command>make describe</command> (and thus, the overall
+	      ports <command>make index</command>).  The workaround is
+	      to enclose the conditional comparison in spaces, e.g.:
+	      <programlisting>if ( OSVERSION > 500023 )</programlisting>
+	      Be aware that test-installing a port on 4.9 or 5.2
+	      will <emphasis>not</emphasis> detect this problem.</para>
+	  </listitem>
+
+	</itemizedlist>
+
+      </sect1>
+
       <sect1 id="dads-misc">
 	<title>Miscellanea</title>
 
>Release-Note:
>Audit-Trail:
>Unformatted: