twee-3: clashing passage headers and webkit pseudo-element selectors

[cyrusfirheir]

As of now, spaces between components of the passage header are optional, as noted here:

NOTE: Each component after the start token may be preceded by one or more spaces for readability.

This brings up the following case:

:: Story Stylesheet [stylesheet]
body {
  color: red;
}
::-webkit-some-pseudo-element {
  /* this section is no longer read as a part of the stylesheet... This is new passage now. */
}

The above twee code fails to compile unless the ::-webkit-some-pseudo-element is prefixed by some other character (e.g. whitespace).

While this can be worked around by allowing an exception for the prefix ::-webkit-, making a space between the start token :: and the passage name mandatory would make things clearer and easier for writing tools.

Twee decompilers already do this, adding spaces between each of components, so, rather than having the spaces for readability, mandating them would potentially result in less ambiguous code.

[videlais]

I have left a note for the Twine Committee to consider this, but I propose changing "Each component after the start token may be preceded by one or more spaces for readability" to "Each component after the start token should be preceded by one or more spaces for readability," changing "may" to "should."

[greyelf]

Changing the word from may to should doesn't really make that sentence any less passive, and isn't likely to solve the issue described in the OP.

Personally I believe encouraging people to always use one or more white spaces between the components of the header makes more sense.

[ChapelR]

I agree with Greyelf, why not go full must?

[videlais]

How would “encouraging” work exactly? If the only exposure to Twee people have is the spec, and we think this is important, some wording In it has to change. I’m okay with re-wording things, but the spec uses “may”, “should”, and “must” to signal compliance. I agree with you that something should happen, but think it should happen within the spec itself to signal how spaces should appear between components.

…

On Aug 4, 2020, at 2:31 AM, Greyelf ***@***.***> wrote:  Changing the word from may to should doesn't really make that sentence any less passive, and isn't likely to solve the issue described in the OP. Personally I believe encouraging people to always use one or more white spaces between the components of the header makes more sense. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[klembot]

I’d like to state probably the obvious, that if this becomes mandatory it’s a breaking change to the spec. That doesn’t mean it shouldn’t be done, but there is an impact to the decision.

What about the opposite, that if :: is found at the start of a new line inside passage text, it is recommended that decompilers prepend it with a space, and that the user is warned?

[tmedwards]

My response to this is the same as it was the last time this came up—I forget if that was during the discussions of the spec or as a Tweego discussion, but it has come up before.

---

There are two basic paths to resolution here:

1. Change the specification to require space between the passage header marker (::) and the start of the passage name.
2. Advise users to make their style rules conformant.

1. Change the specification…

Pros: Users, probably, won't have to make their style rules conform to the spec.

Cons: Likely to break, literally, decades of Twee code. Remember, aside from the new parts of the specification—i.e., story and passage metadata—the spec largely enshrined existing Twee behavior and usage. There are a lot of Twee files out there that would not be valid with the proposed specification change—e.g., ::Muh Passage. Note, I'm not guessing about this, I know this for a fact.

2. Advise users to make their style rules conformant.

Pros: Won't break any existing Twee code.

Cons: Users need to make their style rules conform to the existing specification†.

† Frankly, not really a con, this is simply meeting the existing specification. As to how. Selectors always start with an implicit global selector (*), which may be explicitly specified instead. For example:

*::-webkit-some-pseudo-element { /* Works as normal. */ }

---

Final thoughts

This is something users who want to use text that looks like a passage header within their passages already have to deal with, because that's the specification. This isn't anything different. Conformance to the spec for a, frankly, minor part of the vast majority of projects should not be considered an issue worth breaking existing projects over.

[cyrusfirheir]

Supporting existing code does ask for handling edge cases, and I'm already doing that. I suppose this is more of a suggestion for v4 (or the next breaking version, if that ever happens.)

[mcdemarco]

While this can be worked around by allowing an exception for the prefix ::-webkit-, making a space between the start token :: and the passage name mandatory would make things clearer and easier for writing tools.

Twee decompilers already do this, adding spaces between each of components, so, rather than having the spaces for readability, mandating them would potentially result in less ambiguous code.

Note that ::-webkit- is not the only vendor prefix that might appear in this context, and vendor prefixes are not the only occurrence of this problem, so making exceptions is not a very promising or future-proof solution. Back in the day, pseudo-elements were prefixed with a single colon just like pseudo-classes, but many new ones seem to require double colons now. (See MDN.) On the bright side, these things are unlikely to appear in old Twine stories because they weren't in use yet.

I think the case of raw pseudo-element selectors not prefixed by the asterisk is corner enough to go on permitting the current twee syntax for the moment. Maybe some mandatory versioning information could go into Twee 4 (alongside the mandatory ifid) to support a breaking change in passage name spacing requirements.

[tmedwards]

Coming back to this, my position hasn't changed since my last comment here, which can be summed up as "don't break things".

That said, I did not suggest a solution, other than following the existing specification. Thus, a proposal:

1. As suggested by @videlais , change "may" to "should". Yes, it's still not a requirement, but at least we offer guidance rather than simply punting—i.e., go from "do whatever you want" to "we really recommend that you do".
2. Add a compiler requirement that when generating passage headers themselves, compilers must use the recommended format with a space—i.e., :: …. All compilers probably already do, but having it defined in the spec. is a good idea.
3. Add a compiler recommendation something along the lines of "compilers (may|should) emit a warning if common passage header-like patterns are detected", maybe including a recommendation for the user as part of the warning. That puts the ball in the compilers' court, rather than the spec. It's also not a significant ask as there are a limited number of vendor prefixes and pseudo-elements—even if more are added, that's simply a minor compiler update.

[videlais]

I've introduced a PR with some language proposals for addressing this issue modeled after what @tmedwards suggested but including wording noting the differences between older and current versions of Twee as @klembot noted last year.