Recommendation: Twee 3 Specification: Adding IFID Rule

[videlais]

To clarify for future developers implementing the specification, it is recommended to add the following.

"An IFID is a sequence of between 8 and 63 characters, each of which shall be a digit, a capital letter or a hyphen (see Treaty of Babel)."

This would be added to the StoryData section.

[tmedwards]

Notionally agreed, however, per my reply in the Twine 2 HTML Elements issue, I'd suggest something along the lines of:

COMPILERS: An IFID (Interactive Fiction IDentifier) is a sequence of between 8 and 63 characters, each of which must be a digit (0–9), capital letter (A–Z), or hyphen (-) that is generated using one of the standard universally unique-ID-number algorithms and uniquely identifies your project—see The Treaty of Babel. For reference, Twine 2 uses v4 (random) UUIDs and it is recommend that Twee 3 compilers follow suit.

EDIT: Updated for consistency with the rest of the document language and for specificity.

[videlais]

This was part of a much large conversation from almost two days ago in the Slack channel. The recommended language was already put into another specification. If we decide to go with this new language, it will need to change in both places. This is still possible, of course, but it would need to be discussed about aligning all documents.

[tmedwards]

If you're talking about The Treaty of Babel, then there are issues with simply copying the sentence you cherry picked:

1. You did not quote the entire IFID specification, rather cherry picking a single sentence—one that does not cover the entire specification. If we're treating TToB as sacrosanct, then the bits about IFIDs being "universally unique" and using "the standard unique-ID-number algorithms" are kind of important, and the majority of my additions.
2. Specific to the Twee 3 Specification, the description of IFIDs in TToB are woefully under specified, so using their exact language as-is is a non-starter for that document—e.g., simply saying "a capital letter" is nonsensical as it doesn't take the character set into account, which is critically important in knowing what "a capital letter" encompasses; case in point, Æ is "a capital letter", but I guarantee you that wasn't within the set intended by the drafters of TToB.

Beyond that. If by "both places" you mean within the Twee 3 Specification and the Twine 2 HTML Output, then while I agree that the language should be similar—and I can certainly copy some of my edits here to my suggestion in the other issue—it does not need to be exactly the same, word-for-word.

OTOH, if you meant within our documents and the TToB, then fixing the deficiencies within the TToB is a whole different kettle of suck that we shouldn't be worried about here and now.

[videlais]

See my comment on the Twine 2 HTML Elements issue. I agree with the change for greater specificity, but think we should also include "capital letters" or "uppercase" somewhere within the text to match what Twine 2 actually does with the v4 UUIDs it generates.

[tmedwards]

As I noted in issue #4 , the uppercase requirement is already spelled out, but it doesn't hurt to reiterate the point. Thus, how about the following:

COMPILERS: An IFID (Interactive Fiction IDentifier) is a sequence of between 8 and 63 characters, each of which must be a digit (0–9), capital letter (A–Z), or hyphen (-) that is generated using one of the standard universally unique-ID-number algorithms and uniquely identifies compiled projects—see The Treaty of Babel. For reference, Twine 2 uses v4 (random) UUIDs, using only capital letters, and it is recommend that Twee 3 compilers follow suit.

Or, with firmer language—mirrored in the other issue:

COMPILERS: An IFID (Interactive Fiction IDentifier) is a sequence of between 8 and 63 characters, each of which must be a digit (0–9), capital letter (A–Z), or hyphen (-) that is generated using one of the standard universally unique-ID-number algorithms and uniquely identifies compiled projects—see The Treaty of Babel. Twine 2 uses v4 (random) UUIDs, using only capital letters, and Twee 3 compilers must follow suit to ensure maximum compatibility.

And, streamlined—also mirrored in the other issue and explained there:

COMPILERS: An IFID (Interactive Fiction IDentifier) uniquely identifies compiled projects—see The Treaty of Babel. Twine 2 uses v4 (random) UUIDs, using only capital letters, and Twee 3 compilers must follow suit to ensure maximum compatibility.

EDIT: Derp. Fixed a pronoun bobble in the language.

[videlais]

I vote for the streamlined version.

[tmedwards]

Resolved.