Date: Fri, 15 Jul 2005 02:10:27 +0200 From: Pav Lucistnik <pav@FreeBSD.org> To: freebsd-doc@FreeBSD.org Subject: Porter's Handbook patch about SUB_* Message-ID: <1121386227.21850.2.camel@hood.oook.cz>
index | next in thread | raw e-mail
[-- Attachment #1 --]
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@oook.cz>
<pav@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
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (FreeBSD)
iD8DBQBC1v7zntdYP8FOsoIRAonFAJ0Yx++g6Ky07WPccU4TpS3YeJ3vYgCeKqBX
NlkTRejTBn2wbYYO6tDjB2s=
=zhed
-----END PGP SIGNATURE-----
home |
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1121386227.21850.2.camel>