Documentation: better explain pros and cons of the different renderers

[callegar]

Apparently, there is a very significant difference in compilation times when using the default (node) renderer and harfbuzz.
On short documents using a non negligible amount of fonts, harfbuzz can half the compilation time. Possibly in larger documents, the generally longer compilation times will make the difference less striking. As an example, on some exam papers that are just a few pages long and that employ Source Serif 4, Source Sans 3, Source Code Pro, Cinzel and XITS (Math), the compilation time drops from 5 to 6 s to approximately 2.5s using harfbuzz and looking at the production of the lualatex log on stdout it is very evident how the output pauses as the font loading happens.

This makes it tempting to configure the fonts to use the harfbuzz renderer via fontspec (e.g. with a default font feature), at least in the initial phases of a document writing (as if it was a draft feature). However, from the documentation it is not very clear what the implications of doing so would be. From what I understand:

1. Harfbuzz may be better or even indispensable to correctly render some non latin fonts;
2. Harfbuzz may break hyphenation on latin fonts;
3. Harfbuzz and node map non standard chars to charcodes differently
4. Harfbuzz is much much faster
5. Harfbuzz cannot do variable fonts

Specifically is 2. still true? Are there any other contraindications in using harfbuzz? Will switching from node to harfbuzz or viceversa change linebreaks and pagebreaks? Is there anything subtle and specific that one needs to check when switching from one renderer to another one (e.g., to avoid ending up with some incorrectly rendered PDFs without noticing)? Shouldn't point 4 be mentioned in the docs? Is point 4 expected to remain true?

IMHO these points, including 4, are worth mentioning both in the luaotfload and in the fontspec documentation (more technical and more user oriented respectively), because users might be quite interested in turnaround times particularly in certain workflows (e.g. if you use overleaf) or in certain phases of document preparation. As a matter of fact, compilation time is probably the hottest selling point of LaTeX competitors (e.g. typst).

[jbezos]

Item 2 is issue #152. The MWE shows this bug hasn’t been fixed, so with Latin/Cyrillic/Greek you should rely on the default renderer. Sadly, it may misplace some diacritics.

[zauguin]

The modes are very different implementation wise, so it's hard to list all points where they differ. So I started a wiki-page where differences and pro/cons can be collected which people consider relevant and we can consider merging that into the documentation later.

I created a first draft based on your points, feel free to add or modify.

A few notes about your points:

1. Yes, non latin fonts sometimes need harf mode. It's hard to tell exactly how much of an issue that still is, probably @jbezos knows that better than me.
2. harf leads to worse hyphenation for all fonts. That's somewhat tricky to solve in general. Some fonts are more affected than others, the worst offenders usually being script style font with lots of kerning.
3. They map charcodes very differently but both are weird in their own way. IMO the harf mode is quite a bit saner, but I'm somewhat biased.
4. You seem to have a much better feel for the performance difference than I currently do.
5. Both modes support variable fonts. The node mode supported them earlier, but the harf mode was earlier compatible with typical fonts. Now they should behave rather similar, but they are still sufficiently different that it's a good idea to try the other one if one has an issue with a specific font.

@jbezos Is there already an issue for the misplaced diacritics problem?

[jbezos]

@zauguin Sadly, I haven’t kept any examples and it’s even possible it’s already fixed (maybe with uninormalize ) . I'll try to remember what I was referring to in #152 (comment) (iirc, it was related to some Greek combinations).

[jbezos]

@zauguin See #267.

[callegar]

In addition to the previous points, I also happen to see

! Math error: parameter \Umathaxis\textstyle is not set.
\endtabular ->\endarray \m@th $
                               \egroup 
l.43   \end{tabular}}

when I set the OpenType renderer in the math font (XITS Math). Is this expected?

[callegar]

With respect to compilation speed, see also: fontspec issue 491, which may hide the speed differences, unless the renderer option is individually attached to all the loaded fonts.

[zauguin]

when I set the OpenType renderer in the math font (XITS Math). Is this expected?

Never use another mode than base in math mode. They fundamentally can't work. In math mode the math layout system positions characters which is completely independent of the shapers managed by node and harf. Since node and harf expect the shapers to run any fonts with these modes will be broken if used in math. (unicode-math takes care of this automatically by explicitly setting base mode for all fonts it loads unless explicitly overwritten)

[callegar]

So I started a wiki-page

This is extremely helpful, thanks!