svn commit: r397340 - head/Mk/Uses

[Hiroki Sato]

Author: hrs
Date: Sat Sep 19 22:56:19 2015
New Revision: 397340
URL: https://svnweb.freebsd.org/changeset/ports/397340

Log:
  Add description about background why arguments other than
  :fcfontsdir are required.

Modified:
  head/Mk/Uses/fonts.mk

Modified: head/Mk/Uses/fonts.mk
==============================================================================
--- head/Mk/Uses/fonts.mk	Sat Sep 19 22:04:27 2015	(r397339)
+++ head/Mk/Uses/fonts.mk	Sat Sep 19 22:56:19 2015	(r397340)
@@ -10,6 +10,35 @@
 #  fcfontsdir	Add @fcfontsdir ${FONTSDIR} to PLIST_FILES
 #  none		No special handling of ${FONTSDIR} in PLIST_FILES
 
+# Ports should use USES=fonts with an argument only when necessary.
+# By default, @fcfontsdir ${FONTSDIR} is added and it updates font
+# information cache file of fontconfig library, and XLFD entries
+# in fonts.dir and fonts.scale file, which are directly used by
+# X server and xfs font server.
+#
+# Xorg supports TrueType and OpenType via either of the two font
+# subsystems.  @fcfontsdir is designed to update configuration files for
+# both of them to register a font file.  Specifically, fc-cache and
+# mkfontdir utilities are used, respectively.
+#
+# Ports to install fonts with which mkfontdir or fc-cache do not work well
+# should use :fc and/or :fontsdir argument.  fc-cache and mkfontdir
+# get information such as fontname, encoding, etc. from a font file.
+# However, mkfontdir does not understand information in some scalable
+# fonts.  Typical examples are TrueType Collection format and
+# CJK (Chinese, Japanese, and Korean) TrueType font.  The former is
+# a format which contains multiple fonts in a single file.
+# While Xorg supports it, mkfontdir does not generate correct
+# fonts.dir entries from a TTC font.  CJK fonts often require
+# modifiers in a XFLD entry to enable special feature which mkfontdir
+# does not support, either.
+#
+# Note that ports which do not want mkfontdir need to use
+# a separate FONTSDIR, not shared ones such as misc or TTF.
+# This is because other ports using @fcfontsdir or @fontsdir
+# update fonts.dir in these font directories upon installation
+# and deinstallation.  mkfontdir will overwrite manually-added entries.
+
 .if !defined(_INCLUDE_USES_FONTS_MK)
 _INCLUDE_USES_FONTS_MK=	yes