tc39
emu-clause diff attribute
As discussed with @bterlson. I would like to change emu-clause to allow adiff attribute. If the attribute is present, the section will be numbered with the number of the section with the same ID in the referenced document. It will also add a link to the matching section in the referenced document following the header. If the section does not exist in the referenced document, it should be an error.
How would you number a document with an emu-clause followed by a emu-clause diff pointing to ES6 clause 16 and another emu-clause? 1, 16, 2, or 1, 16, 3?
Hmm, that brings up some other more complex issues. Maybe section numbering doesn't make sense at all for documents that diff another. I'll talk to you more about it in person during the meeting.
To me, the name 'diff' didn't suggest the requested semantics. Perhaps 'modifies' would be better. Or 'original'.
I was thinking the incantation would go like this:
<emu-clause diff id=sec-some-262-clause>
but this doesn't seem good because you probably want a distinct id for your diff clause, so I guess I agree that
<emu-clause modifies=sec-some-262-clause id=sec-modified-262-clause>
might be better.
Why would to want a distinct ID? The whole point was to show that this clause is intended to replace the referenced one. Meaning references throughout the rest of the document should point to it instead.
Update after in-person discussion with @bterlson:
<emu-clause modifies id="sec-id-from-spec">to update a section- section number derived from referenced spec section
- arrow (⮵ or 🡵 or something) following header linking to original section
- references from within the proposal to the referenced section point to this modified section
<emu-clause insert-after="sec-id-from-spec" id="proposed-sec-id">to insert this section as a sibling to the referenced section- derive section number from referenced spec section
insert-beforeto do the same but the other direction- presence of both (or either and
modifies) is an error
<emu-clause delete="sec-id-from-spec"></emu-clause>explicitly removes a section- keeps track of section numbering
- causes references within the proposal to the referenced section to be broken references
An <emu-clause> in the presence of any of these should be considered an error. If these exist, this must be a proposal.
Now that I think about it, ins-before, ins-after, and del would probably be better attribute names since they match up with <ins> and <del> elements as well as the ins and del classes for <li> elements.
Also, I think each of these features should also apply to annexes. /cc @ljharb
The whole point was to show that this clause is intended to replace the referenced one.
Ah! In that case, maybe the attribute should be 'replaces' rather than 'modifies'.
(I suggested 'modifies' when I thought that the clause would merely list modifications to the original, not replace it entirely.)
An
<emu-clause>in the presence of any of these should be considered an error. If these exist, this must be a proposal.
What does that mean exactly? How does ecmarkup know something is a proposal versus a spec PR versus the spec?
@ljharb I think the idea is that if there is at least one emu-clause modifying another clause, then the spec is considered a diff spec and must only diff existing clauses using these mechanisms we're talking about. An emu-clause without such annotation is likely to be an oversight. I'm not super invested in this error personally but we'll see what I implement :)
A number of my proposals add new sections and diff existing ones; is that not something that could be supported?
aha, that makes sense :-) just trying to understand.
I think the part that confused me is the implication that a proposal would ever need to have a bare <emu-clause>, since everything would always involve an addition, change, or deletion.
A proposal may have non-normative text describing the proposal itself that may not need to be included in the specification itself.
Many proposals include their own <emu-intro>, though that's somewhat different from an <emu-clause>