docs/76688: Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}

[Florent Thoumie]

>Number:         76688
>Category:       docs
>Synopsis:       Update doc: books/porters-handbook - tell about SUB_{FILES,LIST}
>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 Jan 26 00:20:24 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Florent Thoumie
>Release:        FreeBSD 5.3-RELEASE i386
>Organization:
Xbsd.org
>Environment:
System: FreeBSD gate.xbsd.org 5.3-RELEASE FreeBSD 5.3-RELEASE #2: Wed Nov 24 16:35:34 CET 2004 root at gate.xbsd.org:/usr/src/sys/i386/compile/GATE i386

>Description:

Add some piece of information about SUB_FILES and SUB_LIST variables.

>How-To-Repeat:

N/A

>Fix:

--- subfiles.diff begins here ---
--- book.sgml.orig	Wed Jan 26 00:15:04 2005
+++ book.sgml	Wed Jan 26 01:07:06 2005
@@ -5377,6 +5377,56 @@
 	  installed in <filename>/var/db/pkg</filename> upon install from a
 	  port.</para>
       </sect1>
+
+      <sect1 id="using-sub-files">
+	<title>Making use of <makevar>SUB_FILES</makevar> and
+	  <makevar>SUB_LIST</makevar></title>
+
+	<para>If your port wants to modify some of your files (that means not
+	  included in the original distribution) according to some values, you
+	  can use <makevar>SUB_FILES</makevar> and <makevar>SUB_LIST</makevar>
+	  variables.</para>
+
+	<para><makevar>SUB_FILES</makevar> specifies a list of files to be
+	  automatically modified.  Each <replaceable>file</replaceable> in
+	  <makevar>SUB_FILES</makevar> must have a corresponding
+	  <filename><replaceable>file</replaceable>.in</filename> in
+	  <makevar>FILESDIR</makevar>.  If you add some special files
+	  (<filename>pkg-message</filename>, <filename>pkg-install</filename>,
+	  <filename>pkg-deinstall</filename> or <filename>pkg-reg</filename>),
+	  <makevar>PKG-<replaceable>FILE</replaceable></makevar> associated
+	  variables will be set to
+	  <filename><makevar>WRKDIR</makevar>/pkg-<replaceable>file</replaceable></filename>.</para>
+
+	<para><makevar>SUB_LIST</makevar> is a list of <literal>VAR=VALUE</literal>
+	  pairs.  The modified version of each file will be created in
+	  <makevar>WRKDIR</makevar>.  For each <literal>VAR=VALUE</literal> in
+	  <makevar>SUB_LIST</makevar>, <literal>%%VAR%%</literal> gets replaced
+	  by <literal>VALUE</literal> in each file in <makevar>SUB_FILES</makevar>.
+	  Some usual pairs are automatically added to <makevar>SUB_LIST</makevar>,
+	  so you don't have to worry about them : <literal>PREFIX=${PREFIX}
+	  DOCSDIR=${DOCSDIR}</literal>, etc. (see
+	  <filename>bsd.port.mk</filename> for the entire list).</para>
+	  
+	<para> The substition process is almost the same as with
+	  <makevar>PLIST_SUB</makevar>.  Note that any line beginning with
+	  <literal>@comment</literal> after variables substitution are deleted from
+	  resulting files.</para>
+	  
+	<para>The following example can be enough for a port wanting to display a
+	  custom <filename>pkg-message</filename> (using <literal>%%PREFIX%%</literal>)
+	  and to install a rcNG startup script (using
+	  <literal>%%RC_SUBR%%</literal>).</para>
+	  
+	<programlisting>SUB_FILES= pkg-message myport.sh
+SUB_LIST= RC_SUBR=${RC_SUBR}
+
+USE_RC_SUBR=  yes</programlisting>
+
+	<para>Note that you must have (in this case) at least
+	  <filename>pkg-message.in</filename> and <filename>myport.sh.in</filename>
+	  in <makevar>FILESDIR</makevar>.</para>
+      </sect1>
     </chapter>
 
   <chapter id="testing">
--- subfiles.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted: