From 56d422545f5566ac4a694676205c9e0fed4c6bb0 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Thu, 2 May 2019 14:18:22 +0000
Subject: [PATCH] Document that USE_GIT(HUB|LAB)=nodefault needs some special
 handling.

PR:		235762
Reported by:	jhb
---
 .../porters-handbook/makefiles/chapter.xml    | 45 ++++++++++++++-----
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
index 12063c9b02..f543e8a3e4 100644
--- a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -2664,12 +2664,6 @@ v0.7.3-0-gc66c71d</screen>
 	  similar to <xref
 	    linkend="porting-master-sites-n"/>.</para>
 
-	<para>When fetching multiple files from GitHub, sometimes the
-	  default distribution file is not fetched from GitHub.  To disable
-	  fetching the default distribution, set:</para>
-
-	<programlisting>USE_GITHUB=	nodefault</programlisting>
-
 	<para>Multiple values are added to
 	  <varname>GH_ACCOUNT</varname>,
 	  <varname>GH_PROJECT</varname>, and
@@ -2712,6 +2706,22 @@ v0.7.3-0-gc66c71d</screen>
 	    <xref linkend="porting-master-sites-n"/></para>
 	</note>
 
+	<para>When fetching multiple files from GitHub, sometimes the
+	  default distribution file is not fetched from GitHub.  To disable
+	  fetching the default distribution, set:</para>
+
+	<programlisting>USE_GITHUB=	nodefault</programlisting>
+
+	<important>
+	  <para>When using <literal>USE_GITHUB=nodefault</literal>,
+	    the <filename>Makefile</filename> must set
+	    <varname>DISTFILES</varname> in its
+	    <link linkend="porting-order-portname">top block</link>.
+	    The definition should be:</para>
+
+	  <programlisting>DISTFILES=    ${DISTNAME}${EXTRACT_SUFX}</programlisting>
+	</important>
+
 	<example xml:id="makefile-master_sites-github-multi">
 	  <title>Use of <varname>USE_GITHUB</varname> with Multiple
 	    Distribution Files</title>
@@ -3053,12 +3063,6 @@ GL_COMMIT=	9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</programlisting>
               linkend="porting-master-sites-n"/> and <xref
               linkend="makefile-master_sites-gitlab-multiple"/>.</para>
 
-          <para>When fetching multiple files using <application>GitLab</application>,
-            sometimes the default distribution file is not fetched from a <application>GitLab</application>
-            site.  To disable fetching the default distribution, set:</para>
-
-          <programlisting>USE_GITLAB=     nodefault</programlisting>
-
           <para>Multiple values are added to
             <varname>GL_SITE</varname>,
             <varname>GL_ACCOUNT</varname>,
@@ -3100,6 +3104,23 @@ GL_COMMIT=	9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</programlisting>
               <xref linkend="porting-master-sites-n"/></para>
           </note>
 
+	<para>When fetching multiple files using <application>GitLab</application>,
+	  sometimes the default distribution file is not fetched from a <application>GitLab</application>
+	  site.  To disable fetching the default distribution, set:</para>
+
+	<programlisting>USE_GITLAB=	nodefault</programlisting>
+
+	<important>
+	  <para>When using <literal>USE_GITLAB=nodefault</literal>,
+	    the <filename>Makefile</filename> must set
+	    <varname>DISTFILES</varname> in its
+	    <link linkend="porting-order-portname">top block</link>.
+	    The definition should be:</para>
+
+	  <programlisting>DISTFILES=    ${DISTNAME}${EXTRACT_SUFX}</programlisting>
+	</important>
+
+
         <example xml:id="makefile-master_sites-gitlab-multi">
           <title>Use of <varname>USE_GITLAB</varname> with Multiple
             Distribution Files</title>