feat(core): Implement hangafter/hangindent + dropcaps package

[Omikhleia]

Greetings,

This PR is an implementation for the idea I mentioned in #1218, as an alternative for implementing initial capitals (drop caps) without using float frames.

• It implements the hangafter/hangindent algorithm from TeX
• As such, it touches two "core" components, the typesetter (a small bit) and the line breaking routines (in a more tricky way, and the pseudo-code from Knuth's book isn't the simplest thing to read).

I haven't noticed anything broken in my tests (though limited), but this certainly has to be reviewed and checked with both eyes wide open. Hence the PR, if anyone wants to play with it. - not necessarily to check drop caps, but also to ensure there's no hiccup on normal documents.

As a by-product of this hangafter/hangindent, I have included:

• The proposed drocaps package per se, with an example (in the "examples" directory). It works by:
  • Computing the dimensions of the "insert" based on the target font for the initial
  • Using that to set the appropriate hangs on the top left of the paragraph
  • Invoking some box magic to fit the initial in the space left blanks by the hangs
• A test for the hangafter logic, using all 4 cases (I have no idea what the use case for the 3 other corners, but it's here), in the tests directory.

N.B. As opposed to TeX, the hangafter is not reset at the start of a new paragraph (but being implemented via settings, it's easy to set only temporarily).

[alerque]

I'm putting off reviewing and merging this until after the current release cycle because we have an issue with feature creep and can't get everything together for a good release if we don't draw some boundaries. I will not be opposed to an early follow up with whatever new features and fixes we have lined up after that, and this is very high of my personal list of wants/needs.

[alerque]

Whew. Goodbye math, safe voyages.

Hello there my old nemesis friend dropcaps.

[alerque]

This implementation has some great sides, but I'm going to combine it with one of mine before merging. The split between core shaping issues vs. dropcap package issues is a good one, and that is much better than any iteration I have cooked up. From my implementations though I have some measurement stuff that I think is a little more robust, a function to trigger the "next" paragraph to have a dropcap without needing to split out the character in markup yourself, and a few other tweaks.

I'm posting partial work on this because my brain is going fuzzy and I need to put it to bed.

[alerque]

@Omikhleia Can you have another look at this? Other than splitting up the commits a bit I left your hangAfter/hangIndent implementation alone entirely. On the other hand I basically rewrote the dropcaps package in a75009c. It functions roughly the same way, but I changed to just two cycles creating hboxes, the second one being the final shape. What is being measured changed just a bit along the way (using the requested dropcap font for placement metrics, not the paragraph) but I think it makes sense. I also re-used some APIs that exist (rebox, lower) to achieve the same affect in perhaps a more understandable way for anybody that tries to copy and modify the code.

Besides that I moved the example to the website and cleaned it up a bit for that context, and I pared down the test a bit to be closer to a unit test.

[alerque]

Force push right now took care of a Lua lint issue. The remaining test failures have to do with this being branched before some changes to the CI font caching. Even though I merged from master into this, the way the GH Actions are setup the fonts are cached for test runs on the PR. I think this will be okay, but if not I'll take care of that separately.

[alerque]

I just took yet another pass at this in f31438d. This time I moved the content of the initial itself from an argument to the command to the content itself. The rest of the paragraph can just be typeset as usual afterwards. This makes it a bit easier to integrate into other systems and contexts I think.

[alerque]

My last couple commits have added some additional features so this can be customized in more ways. Just for reference, here is where we are at (from the website example PR):

\begin[papersize=a5,class=book]{document}
\nofolios
\script[src=packages/lorem]
\script[src=packages/dropcaps]
\set[parameter=document.parskip,value=4ex]

\dropcap[lines=2]{T}his paragraph has a pretty plain initial (drop cap),
using the default document font:
\lorem[words=26].\footnote{You didn’t expect more than that here, with such a font choice, right?}

\dropcap[lines=3,shift=-2pt,raise=-2pt,size=5em,family=Acorn Initials]{T}\font[features=+smcp]{his paragraph},
provided you have the Acorn Initials font, has a much better initial. The size of glyphs in Acorn tends to run a a little big, but we have exagerated this example by specifying a size ourselves. We've also tweaked the location left and down by 2pt.

\dropcap[lines=4,family=Zallman Caps]{H}\font[features=+smcp]{ere is an even nicer initial},
provided you have the Zallman Caps font:
\lorem[words=44].

\dropcap[lines=4,join=true,family=Zallman Caps,standoff=1.5spc]{T}his paragraph shows the effect of the joining option that you can use when the initial belongs to the first word in a sentence.
The first line of text will be flush against the drop cap.
Each additional line spanned with be indented with an extra space.
In old-style typography, this was often preferred to the bare rectangular box most modern word-processing software render.
With SILE, the choice is all yours!

\language[main=tr]
\dropcap[lines=2,style=Italic,join=true]{2.} gösterebileceğimiz nokta, dropcap fonksiyonun birden fazlı karakter içerebilmesi. İşte su paragrafın başında bulunduğu gibi bazı metinde nokta da dahil olması gerekebilir. Ayrıcı \em{Italic} stil kullanıldı.

\dropcap[lines=2,join=true]{\kern[width=-0.8en]“N}\font[features=+smcp]{ever say never”}, the saying goes.
But what does it mean?
Maybe someday your dropcap \em{will} need to include leading punctuation and a hanging indent.
No worries.
\lorem[words=20].
\end{document}

[alerque]

N.B. As opposed to TeX, the hangafter is not reset at the start of a new paragraph (but being implemented via settings, it's easy to set only temporarily).

In order to work as expected in my redesigned usage (passing the initial letter content as the function content and letting the rest of the paragraph follow naturally) this will need to change to reset itself much like paragraph indent does when you change the current paragraph setting.

[Omikhleia]

@alerque Looks great, and the extra options are most welcome. The case for leading punctuation is impressively cool. I'll try to have a closer look and test as soon as I can (might be hard before the end of the week, some tough days to come ^^)

[alerque]

@Omikhleia No worries. I'm going to use this is a book project soon and I try to make sure there is a stable SILE release to match, but this week is just ISBN application and I don't expect to go to press before next week. I'll try to hold off stuffing this in a release until you get a chance to review.

By the way you might check your email from a couple days back for special invitation notices from GitHub ;-)

[alerque]

@Omikhleia and @simoncozens The function provided here is \dropcap, but the package name is currently plural, packages/dropcaps. Does that make sense or should we move it to singular packages/dropcap? There will only ever be one dropcap function provided, but it is quite likely there will be more functions related to dropcaps (such as setting up auto detection of the first letter of paragraphs following chapter functions, something I have working in CaSILE for Turkish and English but needs better language handling before adding here).

[Omikhleia]

N.B. As opposed to TeX, the hangafter is not reset at the start of a new paragraph (but being implemented via settings, it's easy to set only temporarily).

In order to work as expected in my redesigned usage (passing the initial letter content as the function content and letting the rest of the paragraph follow naturally) this will need to change to reset itself much like paragraph indent does when you change the current paragraph setting.

Sorry to notice it that late - but this change, if the dropcap is in the main document, breaks any inserts (e.g. footnote if present in the paragraph with a dropcap, folio if a pagebreak occurs in that paragraph) as they inherit the document settings since 3795a4e

[alerque]

if the dropcap is in the main document, breaks any inserts (e.g. footnote if present in the paragraph with a dropcap, folio if a pagebreak occurs in that paragraph) as they inherit the document settings since 3795a4e

Hmmm, my current production project has both situations in the wild (footnotes in first paragraph with dropcap) and pagebreak in the first paragraph. I don't see this issue there, do you mean when both those situations are true?

One each sample condition (not combined)

[Omikhleia]

Hmmm, my current production project has both situations in the wild (footnotes in first paragraph with dropcap) and pagebreak in the first paragraph. I don't see this issue there, do you mean when both those situations are true?

One or the other, not necessarily at the same time.

\begin[papersize=6in x 9in, class=book]{document}
\script[src=packages/dropcaps]
\script[src=packages/lorem]

\dropcap[lines=3, join=true]{E}ventually,
we will get it right... \lorem[words=50].\footnote{Houston, we got a problem}

One day, \lorem[words=50]\footnote{I am another footnote}

\end{document}

[alerque]

Ah hah! My production project uses CaSILE's implementation of footnotes, not SILE's. This is a function of your recent contributions to SILE's footnotes package, the typesetter of which is now inheriting settings from the document scope. That worked pretty nicely for font family and relative size treatments, but it looks like it is a bit aggressive. We need to either blacklist some settings it should typically not inherit or whitelist the ones it should.

[alerque]

For now I added a blacklist for core settings that users are pretty unlikely to expect to carry over to footnotes. This isn't an ideal implementation because it is in the footnote package and hence any new packages that come along that might have inappropriate settings won't be able to extend this easily.

I have to wonder if perhaps the defaults array might be a better source for footnote settings rather than the top level document settings. Only if people explicitly mark their settings as default would they get inherited. In any event that fix can go in another PR.

[alerque]

Hm, folios needs the same fix.