[MPEG-OTSPEC] exponentiation (was RE: "font directory" / "offset table" / "table directory"

[Simon Cozens]

I often find that when it's hard to see how to attack a technical 
question, it's wise to check if we're attacking the right question.

The stated question here is what kind of unambiguous syntax would be 
used for pseudocode to be jammed into the description of the searchRange 
field. But why are we jamming pseudocode into the searchRange 
description? All the other field descriptions in the spec are 
plain-English summaries of what the information is for or how it is 
expected to be interpreted, and if additional commentary is needed to 
explain it further, then this is done further down with another 
paragraph and/or explanation. If you do the same in this case, then you 
have the space required to explain the intention behind the code more 
clearly.

So, something like this:

segCountX2: The number of segments multiplied by two.
searchRange: The maximum number of nodes in a binary search tree.
entrySelector: The maximum depth of a binary search tree.
rangeShift: ???

The searchRange is defined as being twice the largest power of two less 
than or equal to the number of segments. The entrySelector is the base 2 
logarithm of searchRange/2. The rangeShift is segCountX2 minus the 
searchRange. Here is an example of filling in the header information for 
a table with 39 segments according to the formal definition:

<table>
   <tr><th>segCountX2</th><td>78</td></tr>
   <tr><th>searchRange</th><td>64</td><td>(2 * largest power of 2 
<=39)</td></tr>
   <tr><th>entrySelector</th><td>5</td><td>log2 (32)</td></tr>
   <tr><th>rangeShift</th><td>14</td><td>2 x 39 - 64</td></tr>
</table>

I suspect the real problem is that we don't actually know what these 
fields are really for, so can't write the plain-English summaries of them.

On 31/08/2020 01:42, Peter Constable wrote:
> Separate topic:
> 
> In the description of cmap format 4, "**" is used as an exponentiation operator in the description of the searchRange field, but it appears some younger readers don't recognize that notation from older programming languages. So, I different notation should be used, preferably one that would be readily understood by readers who might or might not be familiar different language. (This will apply also to description of a similar field in the table directory (aka offset table).)
> 
> One possibility is to use pow(). E.g.,
> 
> 2 * pow(2, floor(log2(segCount)))
> 
> 
> Another is to use "^". E.g.,
> 
> 2 * (2 ^ floor(log2(segCount)))
> 
> (I'd keep the extra parens to avoid any uncertainty regarding operator precedence.)
> 
> 
> There may be other possibilities.
> 
> Recommendations?
> 
> 
> Peter
> 
> -----Original Message-----
> From: mpeg-otspec <mpeg-otspec-bounces at lists.aau.at> On Behalf Of Peter Constable
> Sent: Sunday, August 30, 2020 5:32 PM
> To: Laurence Penney <lorp at lorp.org>; MPEG OT Spec list (mpeg-otspec at lists.aau.at) <mpeg-otspec at lists.aau.at>
> Subject: Re: [MPEG-OTSPEC] "font directory" / "offset table" / "table directory"
> 
> I had considered "^", but that is bitwise XOR in C, Python and other languages du jour. I'm open to input, though.
> 
> (This is yet another topic.)
> 
> -----Original Message-----
> From: mpeg-otspec <mpeg-otspec-bounces at lists.aau.at> On Behalf Of Laurence Penney
> Sent: Sunday, August 30, 2020 1:39 PM
> To: MPEG OT Spec list (mpeg-otspec at lists.aau.at) <mpeg-otspec at lists.aau.at>
> Subject: Re: [MPEG-OTSPEC] "font directory" / "offset table" / "table directory"
> 
>> On 30 Aug 2020, at 20:43, Peter Constable <pgcon6 at msn.com> wrote:
>>
>> Separating the fingerprint from the rest of the structure would end up being messy in describing the organization of TTCs … it feels cleaner to say the offsets are to the table directory of each font resource, and that the font resource beings with sfntVersion.
> 
> Yes, that makes sense.
> 
>>> To avoid confusion it may be helpful to provide pseudocode for calculating them.
>>
>> There are similar fields in cmap format 4, and they are described with formulae. E.g., "2 × (2**floor(log2(segCount)))". Now, one of the issues opened on that chapter is that someone wasn't familiar with the Fortran "**" operator and so misunderstood the intent. It seems like something less language specific is needed. Taking that in mind, something similar could be done here. E.g., "pow(floor(log2(numTables)), 2) × 16". Or include both prose description and formula.
> 
> Good point, "**" is not clear to whippersnappers.
> 
> BTW the two definitions can be made identical apart from the factors 16 (for table directory) and 2 (for cmap). Please also consider an asterisk (*) over the typographic multiply sign, unless the whole thing uses math typography, and also consider the ascii circumflex (^) over pow().
> 
> - Laurence
> 
> _______________________________________________
> mpeg-otspec mailing list
> mpeg-otspec at lists.aau.at
> https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.aau.at%2Fmailman%2Flistinfo%2Fmpeg-otspec&data=02%7C01%7C%7C4c939a46961c49538a0f08d84d455a00%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637344307546266141&sdata=fWWEMUQzR4gBw7GVOawRuC2pAcsffK%2BPwlyWb3Ooig0%3D&reserved=0
> _______________________________________________
> mpeg-otspec mailing list
> mpeg-otspec at lists.aau.at
> https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.aau.at%2Fmailman%2Flistinfo%2Fmpeg-otspec&data=02%7C01%7C%7C4c939a46961c49538a0f08d84d455a00%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637344307546266141&sdata=fWWEMUQzR4gBw7GVOawRuC2pAcsffK%2BPwlyWb3Ooig0%3D&reserved=0
> _______________________________________________
> mpeg-otspec mailing list
> mpeg-otspec at lists.aau.at
> https://lists.aau.at/mailman/listinfo/mpeg-otspec
>