From f98db52327c12fa20a9c67b7b641423c8baf7d45 Mon Sep 17 00:00:00 2001
From: Ken Moffat <ken@linuxfromscratch.org>
Date: Sat, 25 Nov 2023 02:20:45 +0000
Subject: [PATCH] tuningfonts: Update details about hinting.

A lot of the information which shows up in google, particularly from
Arch users, is for using the Infinality True Type interpreter. Let
people read the history from FreeType.

Also confirm, from a posting this month, that medium hinting is broken.
---
 x/installing/tuning-fontconfig.xml | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/x/installing/tuning-fontconfig.xml b/x/installing/tuning-fontconfig.xml
index e2ddbd0905..530119d42f 100644
--- a/x/installing/tuning-fontconfig.xml
+++ b/x/installing/tuning-fontconfig.xml
@@ -420,7 +420,7 @@ cat > ~/.config/fontconfig/fonts.conf &lt;&lt; "EOF"
     hintfull: is supposed to give a crisp font that aligns well to the
     character-cell grid but at the cost of its proper shape.
 
-    hintmedium: poorly documented, maybe a synonym for hintfull.
+    hintmedium: is reported to be broken.
     hintslight is the default: - supposed to be more fuzzy but retains shape.
 
     hintnone: seems to turn hinting off.
@@ -442,9 +442,25 @@ cat > ~/.config/fontconfig/fonts.conf &lt;&lt; "EOF"
 EOF</userinput></screen>
 
     <para>
-      You will now need to edit the file in your preferred editor.
+      You will now need to edit the file in your preferred editor. Many of the
+      different settings give very subtle differences and the results may differ
+      for some of the fonts you use.
     </para>
 
+    <note>
+      <para>
+        Hinting, if enabled, is done in <application>FreeType</application>.
+        Since FreeType-2.7 the default TrueType interpreter is v40. The
+        original v35 hinter could be enabled by an environment variable, but
+        is only really appropriate to original Microsoft TTF fonts (Arial, etc).
+        The v38 hinter (Infinality) is not built by default and all the options
+        to tune it have been removed. For full details see <xref
+        linkend="subpixel-hinting"/> (Spoiler: there is NO sub-pixel hinting,
+        the code simply ignores <emphasis>all</emphasis> horizontal hinting
+        instructions.
+      </para>
+    </note>
+
     <para>
       For more examples see the blfs-support thread which started at <ulink
       url="https://lists.linuxfromscratch.org/sympa/arc/blfs-support/2016-09/msg00128.html">2016-09/00128</ulink>,
@@ -844,6 +860,16 @@ EOF</userinput></screen>
       non-MS Japanese fonts when an ugly MS font is already installed.
     </para>
 
+    <bridgehead renderas="sect3" id="subpixel-hinting"
+    xreflabel="subpixel-hinting">subpixel-hinting</bridgehead>
+
+    <para>The documentation of the FreeType v40 interpreter at <ulink
+      url="https://freetype.org/freetype2/docs/hinting/subpixel-hinting.html">freetype
+      docs</ulink>
+      explains how the current hinter works, and why the previous (slow) Infinality
+      interpreter was replaced.
+    </para>
+
     <bridgehead renderas="sect3" id="arch-fontconfig"
     xreflabel="Fontconfig in the Arch wiki">Fontconfig in the Arch wiki</bridgehead>