The quality of documentation and tools in an area of software development has an incredible impact on us developers. They both influence how fast we can work, the quality of the software we write, and even how we feel about our work.
I've recently been working on adding some support for hinting into our TrueType font renderer. I was delighted to find a number of excellent tools for working with TrueType fonts, such as Microsoft's font tools and FontForge, but unfortunately found the TrueType documentation rather lacking.
Instructed font hinting like that used in TrueType fonts is a complicated subject. Each glyph contains a small (ish!) program written in TrueType byte code, which is run in order to manipulate the points. This manipulation was initially designed primarily for grid fitting, a process which improved the appearance of text on screen before anti-aliasing became a feasible option, but is now also used extensively in foreign language fonts to move and change the shape of components of a compound glyph.
Chinese characters before and after their glyph programs are run.
As can be expected with such a complex field, mistakes and ambiguities have crept into the documentation, and while generally very good, even the tools have some flaws.
TrueType was initially developed by Apple in response to Adobe's rather restrictively licensed Type 1 font technology, but was later licensed by Microsoft, eventually making it the de-facto standard on desktop computers. As a result, there are two primary sources of documentation – Apple and Microsoft. While they supposedly define exactly the same system, there are occasional direct contradictions in what they say! In fact, in Apple's guide the definition and example given for one of the most important byte codes is completely wrong.
This wouldn't be surprising in a new document – as I said, it's a complex topic – but these guides were written in the mid nineties! I can't be the first to have found these mistakes, but since in both cases there is no obvious way of contacting the authors, they've stayed incorrect for almost 15 years.
This, to me, highlights the need for a clear and direct line of communication between those writing specifications and those who use them – something we've been trying hard to achieve. Anything unclear? Let us know! We're here to help.