fix(packages): Adjust dropcap logic for letters with a depth

packages/dropcaps/init.lua

@@ -9,6 +9,18 @@ function package:_init ()
   self:loadPackage("raiselower")
 end
 
+local function getToleranceDepth ()
+  -- In non-strict mode, we allow using more lines to fit the dropcap.
+  -- However we cannot just check if the extra depth of the dropcap is above 0.
+  --  - our depth adjustment is but a best attempt.
+  --  - Some characters may have a small depth of their own, such as the "O" in Gentium Plus.
+  -- We must just ensure they stay within reasonable bounds with respect to the baseline,
+  -- so as not to flow over the next lines.
+  -- With well-formed text font, a good compromise is around 0.3bs (LaTeX does this too for defining its \strut).
+  -- This could be computed more precisely (e.g. computing the ratio between ascender and descender font metrics).
+  return SILE.measurement("0.3bs"):tonumber()
+end
+
 local shapeHbox = function (options, content)
   -- Clear irrelevant values before passing to font
   options.lines, options.join, options.raise, options.shift, options.color, options.scale = nil, nil, nil, nil, nil, nil
@@ -31,32 +43,68 @@ function package:registerCommands ()
     local shift = SU.cast("measurement", options.shift or 0)
     local size = SU.cast("measurement or nil", options.size or nil)
     local scale = SU.cast("number", options.scale or 1.0)
+    local strict = SU.boolean(options.strict, true)
+    local depthadjust = SU.boolean(options.depthadjust, false)
     local color = options.color
     options.size = nil -- we need to measure the "would have been" size before using this
 
     if color then self:loadPackage("color") end
 
+    -- Some initial capital fonts have all their glyphs hanging below the baseline (e.g. EB Garamond Initials)
+    -- We cannot manage all pathological cases.
+    -- Quite empirically, we can shape an "X", which shouldn't usually have a depth normally.
+    -- If it has, then likely all glyphs do also and we need to compensate for that everywhere.
+    local depthAdjustment = depthadjust and shapeHbox(options, { "X" }).depth:tonumber() or 0
+    SU.debug("dropcaps", "Depth adjustment", depthAdjustment)
+
     -- We want the drop cap to span over N lines, that is N - 1 baselineskip + the height of the first line.
     -- Note this only works for the default linespace mechanism.
     -- We determine the height of the first line by measuring the size the initial content *would have* been.
-    -- This gives the font some control over its relative size, sometimes desired sometimes undesired.
     local tmpHbox = shapeHbox(options, content)
     local extraHeight = SILE.measurement((lines - 1).."bs"):tonumber()
-    local targetHeight = tmpHbox.height:tonumber() * scale + extraHeight
+    local curHeight = tmpHbox.height:tonumber() + depthAdjustment
+    if strict then
+      -- Take into account the compensated depth of the initial
+      curHeight = curHeight + tmpHbox.depth:tonumber() - depthAdjustment
+    end
+    local targetHeight = curHeight * scale + extraHeight
     SU.debug("dropcaps", "Target height", targetHeight)
 
     -- Now we need to figure out how to scale the dropcap font to get an initial of targetHeight.
     -- From that we can also figure out the width it will be at that height.
     local curSize = SILE.measurement(SILE.settings:get("font.size")):tonumber()
-    local curHeight, curWidth = tmpHbox.height:tonumber(), tmpHbox.width:tonumber()
+    local curWidth = tmpHbox.width:tonumber()
     options.size = size and size:tonumber() or (targetHeight / curHeight * curSize)
     local targetWidth = curWidth / curSize * options.size
     SU.debug("dropcaps", "Target font size", options.size)
     SU.debug("dropcaps", "Target width", targetWidth)
 
-    -- Typeset the dropcap with its final shape, but don't output it yet
+    -- Typeset the dropcap with its final shape, but don't output it yet.
     local hbox = shapeHbox(options, content)
 
+    -- Compensation for regular extra depth.
+    local compensationHeight = depthAdjustment * options.size / curSize
+
+    if not strict then
+      -- Some fonts have descenders on letters such as Q, J, etc.
+      -- In that case we may need extra lines to the dropcap.
+      local hasExtraDepth = hbox.depth:tonumber() > compensationHeight
+      local d = hasExtraDepth and hbox.depth:tonumber() - compensationHeight or 0
+      local extraDepth = d - raise:tonumber()
+      local toleranceDepth = getToleranceDepth()
+      if extraDepth > toleranceDepth then
+        SU.debug("dropcaps", "Extra depth", extraDepth, "> tolerance", toleranceDepth)
+        local extraLines = math.ceil((extraDepth - toleranceDepth) / SILE.measurement("1bs"):tonumber())
+        lines = lines + extraLines
+        SU.debug("dropcaps", "Extra lines needed to fit", extraLines)
+      else
+        SU.debug("dropcaps", "Extra depth", extraDepth, "< tolerance", toleranceDepth)
+      end
+      raise = raise + (hasExtraDepth and compensationHeight or 0)
+    else
+      raise = raise + hbox.depth:tonumber()
+    end
+
     -- Setup up the necessary indents for the final paragraph content
     local joinOffset = join and standoff:tonumber() or 0
     SILE.settings:set("current.hangAfter", -lines)
@@ -65,7 +113,7 @@ function package:registerCommands ()
 
     -- The paragraph is indented so as to leave enough space for the drop cap.
     -- We "trick" the typesetter with a zero-dimension box wrapping our original box.
-    SILE.call("rebox", { height = 0, width = -joinOffset }, function ()
+    SILE.call("rebox", { height = 0, depth = 0, width = -joinOffset }, function ()
       SILE.call("glue", { width = shift - targetWidth - joinOffset })
       SILE.call("lower", { height = extraHeight - raise }, function ()
         SILE.call(color and "color" or "noop", { color = color }, function ()
@@ -92,6 +140,17 @@ To tweak the position of the dropcap, measurements may be passed to the \autodoc
 Other options passed to \autodoc:command{\dropcap} will be passed through to \autodoc:command{\font} when drawing the initial letter(s).
 This may be useful for passing OpenType options or other font preferences.
 
+Some fonts have capitals — such as, typically, Q and J — hanging below the baseline.
+By default, the dropcap fits the specified number of line and the characters are typeset in a smaller size to fit these descenders.
+With the \autodoc:parameter{strict} option set to \code{false}, the characters are scaled with respect to their height only, and extra hanged lines are added to the dropcap to accommodate the descenders.
+
+Some fonts, such as EB Garamond Initials, have \em{all} capitals hanging below the baseline.
+For the latter, you should let the \autodoc:parameter{strict} option to its default (\code{true}).
+
+The \autodoc:parameter{depthadjust=true} option empirically adjusts the dropcap depth based of that of the X character.
+Combined with \autodoc:parameter{strict=false}, it will work for EB Garamond Initials too.
+While it is not possible to handle all pathological cases, these two options may help in some cases.
+
 \begin{autodoc:note}
 One caveat is that the size of the initials is calculated using the default linespacing mechanism.
 If you are using an alternative method from the \autodoc:package{linespacing} package, you might see strange results.