fontconfig: patch and document

pkgs/development/libraries/fontconfig/default.nix

@@ -1,4 +1,16 @@
-{ stdenv, fetchurl, fetchpatch, pkgconfig, freetype, expat, libxslt, fontbhttf }:
+{ stdenv, fetchurl, fetchpatch, pkgconfig, freetype, expat, libxslt, fontbhttf
+, substituteAll }:
+
+/** Font configuration scheme
+ - ./config-compat.patch makes fontconfig try the following root configs, in order:
+    $FONTCONFIG_FILE, /etc/fonts/${configVersion}/fonts.conf, /etc/fonts/fonts.conf
+    This is done not to override config of pre-2.11 versions (which just blow up)
+    and still use *global* font configuration at both NixOS or non-NixOS.
+ - NixOS creates /etc/fonts/${configVersion}/fonts.conf link to $out/etc/fonts/fonts.conf,
+    and other modifications should go to /etc/fonts/${configVersion}/conf.d
+ - See ./make-fonts-conf.xsl for config details.
+
+*/
 
 let
   configVersion = "2.11"; # bump whenever fontconfig breaks compatibility with older configurations
@@ -19,17 +31,24 @@ stdenv.mkDerivation rec {
       }
     ;
 
-  patches = [(fetchpatch {
-    url = "http://cgit.freedesktop.org/fontconfig/patch/?id=f44157c809d280e2a0ce87fb078fc4b278d24a67";
-    sha256 = "19s5irclg4irj2yxd7xw9yikbazs9263px8qbv4r21asw06nfalv";
-  })];
+  patches = [
+    (fetchpatch {
+      url = "http://cgit.freedesktop.org/fontconfig/patch/?id=f44157c809d280e2a0ce87fb078fc4b278d24a67";
+      sha256 = "19s5irclg4irj2yxd7xw9yikbazs9263px8qbv4r21asw06nfalv";
+    })
+    (substituteAll {
+      src = ./config-compat.patch;
+      inherit configVersion;
+    })
+  ];
 
   propagatedBuildInputs = [ freetype ];
-  buildInputs = [ pkgconfig libxslt expat ];
+  buildInputs = [ pkgconfig expat ];
 
   configureFlags = [
-    "--with-cache-dir=/var/cache/fontconfig"
+    "--with-cache-dir=/var/cache/fontconfig" # otherwise the fallback is in $out/
     "--disable-docs"
+    # just ~1MB; this is what you get when loading config fails for some reason
     "--with-default-fonts=${fontbhttf}"
   ];
 
@@ -49,11 +68,10 @@ stdenv.mkDerivation rec {
   # Don't try to write to /var/cache/fontconfig at install time.
   installFlags = "fc_cachedir=$(TMPDIR)/dummy RUN_FC_CACHE_TEST=false";
 
-  # Add a default font for non-nixos systems. fontbhttf is only about 1mb.
   postInstall = ''
     cd "$out/etc/fonts" && tar xvf ${infinality_patch}
     rm conf.d/{50-user,51-local}.conf
-    xsltproc --stringparam fontDirectories "${fontbhttf}" \
+    "${libxslt}/bin/xsltproc" --stringparam fontDirectories "${fontbhttf}" \
       --stringparam fontconfig "$out" \
       --stringparam fontconfigConfigVersion "${configVersion}" \
       --path $out/share/xml/fontconfig \