Porter's Handbook patch about SUB_*

[Pav Lucistnik]

Hi,

I rewrote a section of Porter's Handbook about SUB_FILES and SUB_LIST
variables, which was quite confusingly written. Patch attached, seeking
markup wisdom and approval to commit. English was already checked and
fixed by <subdue> on IRC. It's build tested.

Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.576
diff -a -u -r1.576 book.sgml
--- book.sgml	15 Jul 2005 00:07:13 -0000	1.576
+++ book.sgml	15 Jul 2005 00:08:08 -0000
@@ -5512,57 +5512,55 @@
 	<title>Making use of <makevar>SUB_FILES</makevar> and
 	  <makevar>SUB_LIST</makevar></title>
 
-	<para>In some cases, it may be necessary to modify port files,
-	  i.e.: files not included in the original distribution, to set
-	  values; the <makevar>SUB_FILES</makevar> and
-	  <makevar>SUB_LIST</makevar> variables are available.</para>
+	<para>The <makevar>SUB_FILES</makevar> and <makevar>SUB_LIST</makevar>
+	  variables are useful for dynamic values in port files, such as the
+	  installation <makevar>PREFIX</makevar> in
+	  <filename>pkg-message</filename>.</para>
 
 	<para>The <makevar>SUB_FILES</makevar> variable specifies a list
 	  of files to be automatically modified.  Each
 	  <replaceable>file</replaceable> in the
 	  <makevar>SUB_FILES</makevar> list must have a corresponding
-	  <filename><replaceable>file</replaceable>.in</filename> listed
-	  in <makevar>FILESDIR</makevar>.  If you add some files, such as
-	  <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>
+	  <filename><replaceable>file</replaceable>.in</filename> present
+	  in <makevar>FILESDIR</makevar>.  A modified version will
+	  be created in <makevar>WRKDIR</makevar>.  Files defined as a
+	  value of <makevar>USE_RC_SUBR</makevar> and
+	  <makevar>USE_RCORDER</makevar> are automatically added to
+	  <makevar>SUB_FILES</makevar>.  For files
+	  <filename>pkg-message</filename>,
+	  <filename>pkg-install</filename>, <filename>pkg-deinstall</filename>
+	  and <filename>pkg-reg</filename>, the corresponding Makefile variable
+	  is automatically set to point to the processed version.</para>
 
 	<para>The <makevar>SUB_LIST</makevar> variable 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=VALUE</literal> pairs.  For each pair
 	  <literal>%%VAR%%</literal> will get replaced
 	  with <literal>VALUE</literal> in each file listed in
-	  <makevar>SUB_FILES</makevar>.  Some usual pairs are
-	  automatically added to <makevar>SUB_LIST</makevar>,
-	  so you are not required to worry about them :
-	  <literal>PREFIX=${PREFIX}DOCSDIR=${DOCSDIR}</literal>,
-	  etc. (see <filename>bsd.port.mk</filename> for the entire
-	  list).</para>
-	  
-	<para> The substitution process is almost the same as the
-	  <makevar>PLIST_SUB</makevar> variable.  Any line beginning with
-	  <literal>@comment</literal> after variable substitution will be
-	  deleted from resulting files.</para>
-	  
-	<para>The following example should be enough for a port to
-	  display a custom <filename>pkg-message</filename>,
-	  using <literal>%%PREFIX%%</literal>,
-	  and to install an rcNG startup script using
-	  <literal>%%RC_SUBR%%</literal>.</para>
-	  
-	<programlisting>SUB_FILES= pkg-message myport.sh
-SUB_LIST= RC_SUBR=${RC_SUBR}
+	  <makevar>SUB_FILES</makevar>.  Several common pairs are
+	  automatically defined: <makevar>PREFIX</makevar>,
+	  <makevar>LOCALBASE</makevar>, <makevar>X11BASE</makevar>,
+	  <makevar>DATADIR</makevar>, <makevar>DOCSDIR</makevar>,
+	  <makevar>EXAMPLESDIR</makevar>.  Any line beginning with
+	  <literal>@comment</literal> will be deleted from resulting files
+	  after a variable substitution.</para>
+
+	<para>The following example will replace <literal>%%ARCH%%</literal>
+	  with the system architecture
+	  in a <filename>pkg-message</filename>:</para>
 
-USE_RC_SUBR=  yes</programlisting>
+	<programlisting>SUB_FILES=     pkg-message
+SUB_LIST=      ARCH=${ARCH}</programlisting>
 
 	<para>Note that for this example, the
-	  <filename>pkg-message.in</filename> and
-	  <filename>myport.sh.in</filename> files must exist in
+	  <filename>pkg-message.in</filename> file must exist in
 	  <makevar>FILESDIR</makevar>.</para>
+
+	<para>Example of a good <filename>pkg-message.in</filename>:</para>
+
+	<programlisting>Now it's time to configure this package.
+Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory
+as .putsy.conf and edit it.</programlisting>
+
       </sect1>
     </chapter>
 


-- 
Pav Lucistnik <pav at oook.cz>
              <pav at FreeBSD.org>

Bento's Law: If It Can Break, It Will Break
Bento's Corollary: If It Can Break, Kris Can Send Mail About It
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 187 bytes
Desc: This is a digitally signed message part
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20050715/491e792d/attachment.sig>