svn commit: r48308 - head/en_US.ISO8859-1/books/porters-handbook/makefiles

[Mathieu Arnold]

Author: mat
Date: Tue Mar  1 20:23:18 2016
New Revision: 48308
URL: https://svnweb.freebsd.org/changeset/doc/48308

Log:
  Add a bit of documentation about the upcoming GH_TUPLE.
  
  PR:		204772
  Reviewed by:	wblock
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D5509

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Mar  1 16:41:09 2016	(r48307)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Mar  1 20:23:18 2016	(r48308)
@@ -1977,10 +1977,27 @@ MASTER_SITE_SUBDIR=	stardict/WyabdcRealP
 		snapshot.</entry>
 	      <entry><literal>${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal></entry>
 	    </row>
+
+	    <row>
+	      <entry><varname>GH_TUPLE</varname></entry>
+	      <entry><varname>GH_TUPLE</varname> allows putting all
+		the <varname>GH_ACCOUNT</varname>,
+		<varname>GH_PROJECT</varname>, and
+		<varname>GH_TAGNAME</varname> into one variable.  The
+		format is
+		<replaceable>account</replaceable><literal>:</literal><replaceable>project</replaceable><literal>:</literal><replaceable>tagname</replaceable><literal>:</literal><replaceable>group</replaceable>.
+		It is helpful when there is more than one GitHub
+		project from which to fetch.</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
+      <important>
+	<para>Do not use <varname>GH_TUPLE</varname> for the default
+	  distribution file, as it has no default.</para>
+      </important>
+
       <example xml:id="makefile-master_sites-github-ex1">
 	<title>Simple Use of <varname>USE_GITHUB</varname></title>
 
@@ -2052,7 +2069,7 @@ USE_GITHUB=	yes</programlisting>
 	  <varname>${WRKDIR}/foo-1.0.2</varname>.</para>
       </example>
 
-      <sect3>
+      <sect3 xml:id="makefile-master_sites-github-multiple">
 	<title>Fetching Multiple Files from GitHub</title>
 
 	<para>The <varname>USE_GITHUB</varname> framework also
@@ -2071,6 +2088,11 @@ USE_GITHUB=	yes</programlisting>
 	  <xref
 	    linkend="makefile-master_sites-github-description"/>.</para>
 
+	<para><varname>GH_TUPLE</varname> can also be used when there
+	  are a lot of distribution files.  It helps keep the account,
+	  project, tagname, and group information at the same
+	  place.</para>
+
 	<para>For each tag, a
 	  <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>
 	  helper variable is created, containing the directory into
@@ -2133,6 +2155,33 @@ post-extract:
 	    <varname>${WRKSRC_contrib}</varname> and contains
 	    <literal>${WRKDIR}/foo-contrib-fa579bc</literal>.</para>
 	</example>
+
+	<example xml:id="makefile-master_sites-github-multi2">
+	  <title>Use of <varname>USE_GITHUB</varname> with Multiple
+	    Distribution Files Using
+	    <varname>GH_TUPLE</varname></title>
+
+	  <para>This is functionally equivalent to <xref
+	      linkend="makefile-master_sites-github-multi"/>, but
+	    using <varname>GH_TUPLE</varname>:</para>
+
+	  <programlisting>PORTNAME=	foo
+PORTVERSION=	1.0.2
+
+USE_GITHUB=	yes
+GH_TUPLE=	bar:foo-icons:1.0:icons \
+		bar:foo-contrib:fa579bc:contrib
+
+CONFIGURE_ARGS=	--with-contrib=${WRKSRC_contrib}
+
+post-extract:
+      @${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+
+	  <para>Grouping was used in the previous example with
+	    <literal>bar:icons,contrib</literal>.  Some redundant
+	    information is present with <varname>GH_TUPLE</varname>
+	    because grouping is not possible.</para>
+	</example>
       </sect3>
     </sect2>