docs claim incorrectly that certain `name` table entries can be overriden

[mbutterick]

According to the docs, name table overrides can be specified within a feature file. I have found, however, that makeotf complains about attempts to override name ID 3, 4, or 5 (the font compiles but makeotf issues a warning that “name id 5 cannot be set from the feature file”).

1. Is the documentation wrong, or is this a bug in makeotf?

2. Is there another way of editing these name fields in a way that makeotf will tolerate?

PS. makeotf itself automatically generates an entry for name ID 5 that looks like "Version 2.548;hotconv 1.0.116;makeotfexe 2.5.65601".

[frankrolf]

As probably should be clarified, some but not all name IDs can be overridden. makeotf tries to follow the spec, which indicates:

Version string. Should begin with the syntax “Version .” (upper case, lower case, or mixed, with a space between “Version” and the number).

The string must contain a version number of the following form: one or more digits (0-9) of value less than 65,535, followed by a period, followed by one or more digits of value less than 65,535. Any character other than a digit will terminate the minor number. A character such as “;” is helpful to separate different pieces of version information.

(https://docs.microsoft.com/en-us/typography/opentype/spec/name)

Of course, there’s nothing keeping you from changing the nameID data in the font binary via a post-processing step.

[josh-hadley]

I think this is simply a mistake in the documentation. It currently reads:

An <id> is a number specifying the ID of the name string to be added to the name table. Note that IDs 2 and 6 (Family, Subfamily, Unique, Full, Version, and FontName) are reserved by the implementation and cannot be overridden; doing so will elicit a warning message and the record will be ignored.

A close reading of the parenthetical list following "IDs 2 and 6" against the OpenType Spec makes me think that part should read "IDs 1 through 6". Possibly also change "FontName" to "PostScript Name" to be consistent with the OT Spec terminology.

If that is indeed the case, we should perhaps also update the table following ("Putting this all together..."), since it suggests nameid 1. And maybe highlight the note that some names cannot be overridden since that is (apparently) easy to overlook.

[mbutterick]

Is it better to have users who read the documentation closely, or not at all? 😉

[BoldMonday]

I agree that most of these fields need to follow the OT spec and that the FDK wants to ensure by default that it is happening correctly. (In essence all the naming fields can already be controlled by the entries in FontMenuNameDB.)

However, nothing in de OT spec states that ID 5 needs to contain the additional info that the FDK is currently putting there. So far we've always circumvented this issue with post-processing scripts. But the less of those things are needed the better. Just my 2c.

[josh-hadley]

After a bit of archeology here, I've made some updates and clarifications in #1459 -- please have a look and feel free to comment. I can make additional clarifications to the documentation if this does not sufficiently address the concerns raised here. The main point I wanted to get across is that the overriding behavior is an implementation detail specific to makeotf/makeotfexe. The syntax itself does not prohibit overriding of any nameIDs, so an implementation could certainly choose to handle nameIDs in feature files as they wish (with the understanding that such implementations would not be compatible with the behavior of makeotf/makeotfexe).

[mbutterick]

I appreciate the clarification in the docs. Still, it seems inconsistent to label this an “implementation detail” and move on. The makeotf program is held out as the reference implementation of the OpenType Feature File specification:

Caution: Portions of the syntax unimplemented by Adobe are subject to change.

Note: All “Implementation Notes” and “Currently not implemented” comments in the rest of the specification below refer to the Adobe implementation of the feature file grammar in the makeotf program, unless otherwise indicated.

Therefore, if overrides for name IDs 1–6 are not supported by makeotf, it seems they should be flagged as “Currently not implemented”.

[mbutterick]

IOW, by saying “Portions of the syntax unimplemented by Adobe are subject to change”, Adobe is saying that features not implemented in makeotf are not truly part of the OT Feature File specification (because that which is “subject to change” is by definition not specified).

The change in #1459 contravenes this principle by claiming “this isn’t implemented in makeotf, but it is nevertheless fully specified.”

[josh-hadley]

overrides for name IDs 1–6 are not supported by makeotf

It's actually overrides for just IDs 2 and 6 that are not supported (IDs 1, 3, 4, and 5 can be overridden in those implementations with the use of a flag option, as I detailed in the "Implementation Note" at the end of the section about nameIDs).

I'll see what I can do to re-word #1459 a bit more based on your comments to better fit the spirit of the spec. After I do that, @mbutterick would you mind making further follow-up comments and suggestions on the PR itself (not here)?