[pkgsrc/trunk]: pkgsrc/doc/guide/files Update the pkgsrc guide to reflect the...

[jlam <jlam%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/fda5733b0189
branches:  trunk
changeset: 505046:fda5733b0189
user:      jlam <jlam%pkgsrc.org@localhost>
date:      Thu Dec 29 14:59:03 2005 +0000

description:
Update the pkgsrc guide to reflect the following changes to the pkginstall
framework:

   * USE_PKGINSTALL is no longer needed.

   * X11 font directories should be listed in FONTS_DIRS.<type>

   * fonts.mk is no longer needed as the functionality has been completely
     reimplemented within the pkginstall framework.

   * PKG_UPDATE_FONTS_DB may be set to "yes" or "no" to indicate whether
     the fonts databases should be updated or not.  This defaults to "yes".

diffstat:

 doc/guide/files/fixes.xml      |  12 +++-----
 doc/guide/files/pkginstall.xml |  54 +++++++++++++++++++++++++++++++++++-------
 2 files changed, 50 insertions(+), 16 deletions(-)

diffs (110 lines):

diff -r 6bfa3f5555de -r fda5733b0189 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Thu Dec 29 14:57:15 2005 +0000
+++ b/doc/guide/files/fixes.xml Thu Dec 29 14:59:03 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.43 2005/12/14 23:55:17 minskim Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.44 2005/12/29 14:59:03 jlam Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Making your package work</title>
@@ -1357,14 +1357,12 @@
       <para>If a package installs font files, you will need to rebuild
         the fonts database in the directory where they get installed at
         installation and deinstallation time.  This can be automatically
-        done by using <filename>mk/fonts.mk</filename>, which you need to
-        include in your <filename>Makefile</filename>.</para>
+        done by using the pkginstall framework.</para>
     
-      <para>When the file is included, you can list the directories where
-        fonts are installed in the
-        <varname>FONTS_<replaceable>type</replaceable>_DIRS</varname>
+      <para>You can list the directories where fonts are installed in the
+        <varname>FONTS_DIRS.<replaceable>type</replaceable></varname>
         variables, where <replaceable>type</replaceable> can be one of
-        <quote>TTF</quote>, <quote>TYPE1</quote> or <quote>X11</quote>.
+        <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>.
         Also make sure that the database file
         <filename>fonts.dir</filename> is not listed in the PLIST.</para>
     
diff -r 6bfa3f5555de -r fda5733b0189 doc/guide/files/pkginstall.xml
--- a/doc/guide/files/pkginstall.xml    Thu Dec 29 14:57:15 2005 +0000
+++ b/doc/guide/files/pkginstall.xml    Thu Dec 29 14:59:03 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkginstall.xml,v 1.7 2005/10/23 11:25:58 rillig Exp $ -->
+<!-- $NetBSD: pkginstall.xml,v 1.8 2005/12/29 14:59:03 jlam Exp $ -->
 
 <chapter id="pkginstall"> <?dbhtml filename="pkginstall.html"?>
 <title>The pkginstall framework</title>
@@ -30,15 +30,13 @@
     <para>Registration of system shells.</para>
   </listitem>
 
+  <listitem>
+    <para>Automatic updating of fonts databases.</para>
+  </listitem>
+
 </itemizedlist>
 
-<para>The following sections inspect each of the above points in detail.
-Note that in order to use any of the described functionalities, you must
-add the following to your package's <filename>Makefile</filename>:</para>
-
-<programlisting>
-    USE_PKGINSTALL= YES
-</programlisting>
+<para>The following sections inspect each of the above points in detail.</para>
 
 <para>You may be thinking that many of the things described here could be
 easily done with simple code in the package's post-installation target
@@ -475,7 +473,6 @@
 following example, taken from <filename role="pkg">shells/zsh</filename>:</para>
 
 <programlisting>
-    USE_PKGINSTALL= YES
     PKG_SHELL=      ${PREFIX}/bin/zsh
 </programlisting>
 
@@ -494,4 +491,43 @@
 
 </sect1>
 
+<!-- ================================================================== -->
+
+<sect1 id="fonts">
+<title>Fonts</title>
+
+<para>Packages that install X11 fonts should update the database files
+that index the fonts within each fonts directory.  This can easily be
+accomplished within the pkginstall framework.</para>
+
+<para>When a package installs X11 fonts, it must list the directories in
+which fonts are installed in the
+<varname>FONTS_DIRS.<replaceable>type</replaceable></varname> variables,
+where <replaceable>type</replaceable> can be one of <quote>ttf</quote>,
+<quote>type1</quote> or <quote>x11</quote>.  This will add hooks to the
+installation scripts to run the appropriate commands to update the fonts
+database files within each of those directories.  For convenience, if the
+directory path is relative, it is taken to be relative to the package's
+installation prefix.  Consider the following example, taken from <filename
+role="pkg">fonts/dbz-ttf</filename>:</para>
+
+<programlisting>
+    FONTS_DIRS.ttf= ${PREFIX}/lib/X11/fonts/TTF
+</programlisting>
+
+<!-- ================================================================== -->
+
+<sect2 id="fonts-disable">
+<title>Disabling automatic update of the fonts databases</title>
+
+<!-- XXX This doesn't really belong here -->
+
+<para>The automatic update of fonts databases can be disabled by
+the administrator by setting the <filename>PKG_UPDATE_FONTS_DB</filename>
+environment variable to <literal>NO</literal>.</para>
+
+</sect2>
+
+</sect1>
+
 </chapter>