[MPEG-OTSPEC] "font directory" / "offset table" / "table directory"

[Laurence Penney]

Thanks for this, Peter.

My simple way of thinking of an sfnt file is in three parts:

1. 4-byte fingerprint (0x00010000, "OTTO", "true")
2. table directory (numTables, binary search parameters, and table records)
3. tables

This is a little bit different from both Apple’s and Microsoft’s descriptions. I vote for the term “table directory” to refer to Apple’s “font directory”, with the exception of the first 4 bytes. (Those 4 bytes, Apple’s “scaler type”, Microsoft’s “sfntVersion”, seem independent of “table directory”. In my code I call it the “fingerprint”. It reminds me of many other file formats that start with a particular byte sequence to help identification.)

So your question becomes how to specify (2).

I suggest using the term “table directory header” for the 4 items occupying 8 bytes:

uint16	numTables
uint16	searchRange
uint16	entrySelector
uint16	rangeShift

I recommend noting in the spec that the latter 3 fields are not arbitrary, and are to help binary search.

Then use the term “table record” for the 16-byte table entries.

This header + records structure for “table directory” is very similar to other parts of the spec.

I take note of Simon Cozens’s suggestion to deprecate the binary search parameters. I regard them as a kind of checksum, not onerous to calculate, so I don’t see a problem with them staying in. To avoid confusion it may be helpful to provide pseudocode for calculating them. P.S. Do/did any implementations use them? I can’t imagine they’ve saved more than a second of processor time worldwide since 1990 :)

- Laurence

> On 29 Aug 2020, at 23:43, Peter Constable <pgcon6 at msn.com> wrote:
> 
> I was trying to clean up some terminology and format descriptions in the OT spec and discovered there was a greater terminology problem than I realized. (This applies equally to OFF.) I’d like to get input on how people are used to using these terms / names of structures and the best remedy for clear and consistent usage in the spec.
>  
> This is about those structures that are found at the start of a (non-collection) font file: an offset (sub)table / array of table records. Q: What terms are people used to using for these?
>  
>  
> Here’s the skivvy wrt Apple’s TrueType Reference Manual, and OT/OFF:
>  
> Apple’s TrueType Reference Manual has terminology that’s similar to but slightly different to that currently in OT/OFF, and it has its own inconsistency.
>  
> 	• The TT font begins with a “font directory”, which is a two-part entity comprised of the “offset subtable” that is followed directly by the “table directory”.
>  
> 	• “Offset subtable” refers to the five fields from sfntVersion to rangeShift.
>  
> 	• “Table directory” is used inconsistently:
>  
> 		• There’s a good usage, meaning an array of records (each record comprised of tag, checksum, offset, length fields).
> 		• The bad usage: the same term is also used as the name for that record.
>  
> The OT spec / OFF refer to that four-member record as “Table Record”, though it inconsistently uses “Table Record entries” or “Table Record” to mean the array.
>  
> The record part is easy to fix in OT/OFF and in Apple’s spec: That record should be called “TableRecord”, and that term should only be used for that structure (not the array).
>  
> But OT / OFF also have another inconsistency in that “Table Directory” is used with different meanings:
>  
> 	• The table record array only (consistent with Apple’s good use of “table directory”)
>  
> 	• The Offset Table, or the combination of offset table + table records array (= Apple’s “font directory”)
>  
> This inconsistency dates back at least to Microsoft’s TrueType 1.66 spec.
>  
> A simple fix would be to use “Offset Table” to mean the same thing that Apple calls the “font directory”, incorporating a tableRecords[] member into that structure, then revise current instances of “Table Directory” changing to “Offset Table” or “tableRecords array” as appropriate.
>  
> But as these are such a basic part of every font file, it occurs to me that many implementers may have terminology engrained in their minds—or their code—that differs, and that this could be confusing / hard to adjust to.
>  
> An alternative would be a clean-up of Apple’s terminology:
>  
> 	• “Font Directory” is comprised of the “Offset Table” followed directly by the “Table Directory”.
> 	• “Offset Table” is comprised of five members, sfntVersion to rangeShift.
> 	• “Table Directory” is comprised of an array of “TableRecord”. (This could be described as a struct consisting of tableRecords[].)
> 	• “TableRecord” is a structure comprised of tag, checksum, offset and length fields.
>  
> Yet another alternative would be to use “Font Directory” as a formal struct name that includes tableRecords[] as a member, so “offset table” would not be used in the formal description.
>  
> Personally, I don’t care for either of these alternatives owing to the use of “font directory”: IMO, that would be better used in describing a collection-level structure, not a font-resource-level structure. (I.e., a collection file begins with a font directory that provides offsets to “offset tables” (or whatever) for one or more font resources.)
>  
>  
>  
> Peter
> _______________________________________________
> mpeg-otspec mailing list
> mpeg-otspec at lists.aau.at
> https://lists.aau.at/mailman/listinfo/mpeg-otspec