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

[Mathieu Arnold]

Author: mat
Date: Tue Jun 14 14:17:44 2016
New Revision: 48925
URL: https://svnweb.freebsd.org/changeset/doc/48925

Log:
  Document the fact that group names should be restricted to a certain
  character class.
  
  PR:		210251
  Sponsored by:	Absolight

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 Jun 14 14:02:59 2016	(r48924)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Jun 14 14:17:44 2016	(r48925)
@@ -2106,6 +2106,14 @@ USE_GITHUB=	yes</programlisting>
 	  <varname>CONFIGURE_ARGS</varname>, or whatever is needed
 	  so that the software builds correctly.</para>
 
+	<note>
+	  <para>As this is only syntastic sugar above
+	    <varname>DISTFILES</varname> and
+	    <varname>MASTER_SITES</varname>, the tag names must adhere
+	    to the restrictions on group names outlined in <xref
+	      linkend="porting-master-sites-n"/></para>
+	</note>
+
 	<example xml:id="makefile-master_sites-github-multi">
 	  <title>Use of <varname>USE_GITHUB</varname> with Multiple
 	    Distribution Files</title>
@@ -2335,9 +2343,9 @@ EXTRACT_ONLY=	source.tar.gz</programlist
 	inside <varname>DISTFILES</varname> and
 	<varname>PATCHFILES</varname> which allows files and
 	patches to be postfixed with <literal>:n</literal>
-	identifiers.  Here, <literal>n</literal> can be both
-	<literal>[0-9]</literal> and denote a group designation.  For
-	example:</para>
+	identifiers.  Here, <literal>n</literal> can be any word
+	containing <literal>[0-9a-zA-Z_]</literal> and denote a group
+	designation.  For example:</para>
 
       <programlisting>DISTFILES=	alpha:0 beta:1</programlisting>
 
@@ -2370,6 +2378,14 @@ EXTRACT_ONLY=	source.tar.gz</programlist
 	&os; implementation of this idea.  We improved a bit on
 	OpenBSD's concept.</para>
 
+      <important>
+	<para>The group names cannot have dashes in them
+	  (<literal>-</literal>), in fact, they cannot have any
+	  characters out of the <literal>[a-zA-Z0-9_]</literal> range.
+	  This is because, while &man.make.1; is ok with variable
+	  names containing dashes, &man.sh.1; is not.</para>
+      </important>
+
       <sect3 xml:id="porting-master-sites-n-simplified">
 	<title>Simplified Information</title>