[patch] PH tells crap about GMAKE (Was: Re: svn commit: r340018 - head/textproc/scew)

[Warren Block]

On Fri, 17 Jan 2014, Alexey Dokuchaev wrote:

> On Fri, Jan 17, 2014 at 10:50:21AM +0100, Pietro Cerutti wrote:
>> On 2014-Jan-17, 09:35, Alexey Dokuchaev wrote:
>>> If possible, particular make(1) implementation should not be referenced in
>>> port's Makefile.  If you need to call "correct" make(1), use ${MAKE_CMD},
>>> which would be correctly set to "gmake" in this case of yours (per USES=
>>> gmake).
>>
>> That makes sense. What about updating [section] 6.4.2 of the porter's
>> handbook?
>
> Indeed, this section needs some love.  Even more, I think it tells something
> that is not true: "GMAKE [variables contains] The full path for gmake if it
> is not in the PATH."
>
> GMAKE is defined in Mk/bsd.commands.mk, and equals to simply "gmake".  It
> is one of the rare cases when absolute (or relative to ${LOCALBASE}) path
> is not used.  I did not observe any indication of some PATH inspection to
> conditionally set GMAKE variable under /usr/ports/Mk.
>
> I also think that Table 6.1 which consists of two rows and columns is, hm,
> ridicule, I guess. :)  IMHO it should be removed.
>
> Please consider attached patch.  It is not a polished gem, and most likely
> would need a review and wordsmithing from doc@ guys.
>
> While here I've also standardized the spelling of "okay", and fixed couple
> of grammar nits.  These changes are not related to GMAKE ones, and probably
> should be committed separately, but I'm not splitting the diff for personal
> convenience, sorry. :)

Attached is a quick editing pass.  I have not tested it for building 
yet, and edited the diff directly, so it has some a new blank line.
-------------- next part --------------
Index: book.xml
===================================================================
--- book.xml	(revision 43554)
+++ book.xml	(working copy)
@@ -201,7 +201,7 @@
 	    <filename>README</filename> or manpage</emphasis>; too
 	    often they are not a concise description of the port or
 	    are in an awkward format (e.g., manpages have justified
-	    spacing, as it looks particularly bad with monospaced
+	    spacing, which looks particularly bad with monospaced
 	    fonts).</para>
 	</note>
 
@@ -515,7 +515,7 @@
   <chapter xml:id="slow">
     <title>Slow Porting</title>
 
-    <para>Ok, so it was not that simple, and the port required some
+    <para>Okay, so it was not that simple, and the port required some
       modifications to get it to work.  In this section, we will
       explain, step by step, how to modify it to get it to work with
       the ports paradigm.</para>
@@ -4128,7 +4128,7 @@
 
 	<para>Available <varname>USE_</varname> and
 	  <varname>WANT_</varname> variables are defined in the files
-	  in <filename>/usr/ports/Mk</filename>.</para>
+	  in <filename class="directory">/usr/ports/Mk/</filename>.</para>
       </sect2>
     </sect1>
 
@@ -5644,40 +5644,32 @@
       </sect2>
 
       <sect2 xml:id="using-make">
-	<title><command>make</command>, <command>gmake</command>, and
-	  <command>imake</command></title>
+	<title><command>make</command>, <command>gmake</command>,
+	  <command>fmake</command>, and <command>imake</command></title>
 
+	<para>Several <literal>make</literal> implementations exist and
+	  are in use.  Quite often, a specific implementation is required,
+	  like GNU make, or legacy &os; make.</para>
+
 	<para>If your port uses <application>GNU make</application>,
-	  set <literal>USES= gmake</literal>.</para>
+	  add <literal>gmake</literal> to <literal>USES</literal>.  If
+	  the legacy &os; <command>make</command> is needed, add <literal>fmake</literal>
+	  there.</para>
 
-	<table frame="none">
-	  <title>Variables for Ports Related to
-	    <application>gmake</application></title>
+	<para>To reference a specific <command>make</command> command
+	  that depends on <literal>USES</literal> value in a port's
+	  <filename>Makefile</filename>, use
+	  <varname>MAKE_CMD</varname>.  In rare cases where
+	  several different <literal>make</literal> implementations are listed
+	  in <literal>USES</literal>, the variables
+	  <varname>GMAKE</varname> (for GNU version) or
+	  <varname>FMAKE</varname> (for legacy &os; version) are available.
+	  
+	  Most
+	  ports should only use <varname>MAKE_CMD</varname> within
+	  their <filename>Makefile</filename>s (that is, to call the <command>make</command>
+	  implementation expected by the ported software).</para>
 
-	  <tgroup cols="2">
-	    <thead>
-	      <row>
-		<entry>Variable</entry>
-		<entry>Means</entry>
-	      </row>
-	    </thead>
-
-	    <tbody>
-	      <row>
-		<entry><varname>USES= gmake</varname></entry>
-		<entry>The port requires <command>gmake</command> to
-		  build.</entry>
-	      </row>
-
-	      <row>
-		<entry><varname>GMAKE</varname></entry>
-		<entry>The full path for <command>gmake</command> if
-		  it is not in the <envar>PATH</envar>.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</table>
-
 	<para>If your port is an X application that creates
 	  <filename>Makefile</filename> files from
 	  <filename>Imakefile</filename> files using