Sprints: Remove "event" macro

[Elchi3]

This is a work item for #685.

We need to refactor, delete, or decide what to do with the "event" xref macro.
See https://github.com/mdn/kumascript/blob/master/macros/event.ejs
This macros is used on over 2000 pages in all locales and we will need to either update or remove it, as it links to events in the Web/Events tree which we plan to get rid of as part of the event pages overhauling project.

[wbamberg]

domeventxref

Nice work! Merged.

event
This macros is used on over 2000 pages in all locales

This one is a problem. We can't just update the macro because it assumes that the events are flat, so you can just pass, say "event-name" and this will identify a single page. If the events are distributed under their interfaces, as we propose, then you would also need to pass the interface into the macro, which of course the pages that include the macro don't :/. So much for xref macros making maintenance easier!

If we are going to go and edit 2400 pages (or 900 en-US) then we should just kill the macro and replace it with links to the new page. But this is a lot of very tedious work (much more work than killing the WebExtBrowserCompat). I hate the fact that every tiny incremental improvement means people have to spend days editing thousands of obsolete pages. Perhaps we should block this work on (1) fixing the PUT API, (2) having tooling for making focused updates to pages, and (3) having a plan for dealing with outdated locales.

Another related question: if we had redirects from the old pages to the new ones, then things would continue to work. But I guess we can't do that since an event like close is going to be split into multiple pages.

I'll be back later to comment on the other macros.

[Elchi3]

Thanks for your thoughts. My 2019 sentence is: "I hate the wiki, too!" :)

I also agree that xref macros aren't helping at all. Not for maintenance, nor for consistency. I think the plan for the event macro would be to replace it with plain links.

if we had redirects from the old pages to the new ones, then things would continue to work. But I guess we can't do that since an event like close is going to be split into multiple pages.

Yes, this will not work in all cases, but there are also quite some cases where I think a redirect would work fine. I think we can live with those that will be split into multiple pages. There are ~260 event pages, I don't have a number of those we will split into multiple pages, but we could look into it to see how big of a problem it really is.

I'll be back later to comment on the other macros.

In fact I think that there is enough work for each of these macros that I should split this in several issues. Let's have this one about the event macro then.
See https://github.com/mdn/sprints/issues/906 and https://github.com/mdn/sprints/issues/907 for the new issues.

[chrisdavidmills]

This all makes sense so far, from my understanding.

I too, would love to see an end to xref macros. I don't know if we could just do an operation using the PUT API to remove them all and replace them with their simple link equivalents, as part of the future maintenance work, then get rid of the macros?

[wbamberg]

I don't know if we could just do an operation using the PUT API to remove them all and replace them with their simple link equivalents, as part of the future maintenance work, then get rid of the macros?

For the previous work with PUT, I took the fully-rendered version of the pages and replaced the existing content with that. That's simpler and less risky than selectively replacing parts of the content with the expanded version. Also, that was on archived pages, not actively maintained ones.

I'd be happy to automate changes like this if we could generate a single diff of the prospective changes, review it and apply it cleanly and transparently, and I guess that's the kind of thing that having the content hosted on GitHub gives us. Maybe if we can get cleaner diffs out of the PUT API that would be good enough? Might be worth looking into.

[wbamberg]

I don't have a number of those we will split into multiple pages, but we could look into it to see how big of a problem it really is.

I think this would be worth doing. If it wasn't for the page splitting, then the event.ejs xref wouldn't actually block this work. We could keep the event.ejs macro and the calls to it, and the automatic redirects would continue to keep things working. We could then remove event.ejs when we have a better way to de-macroify pages, and/or after we have deleted a lot of unmaintained pages to make the problem smaller.

But to avoid breaking things when we split pages, we really ought to update event.ejs calls where the target is a page that we are splitting (e.g. {{event("close")}}) and even just going through them all to check that is tedious work.

I wonder if we could get all these pages (https://developer.mozilla.org/en-US/search?locale=*&kumascript_macros=event&topic=none) in a single list? Then we could fetch them and grep for the calls we'd need to update?

[Elchi3]

Yes, I think it would be great to have a closer look into {{event}} calls for this work. For the WebSpeech sample move, I also removed all {{event}} calls and there where ones that looked like this: {{event("end_(SpeechRecognition)","end")}} which is strange and now I really want to remove it even more...

@jwhitlock can you help us and run https://gist.github.com/jwhitlock/ce1088cf9b6431ff93e74791c610d3ef to get us a list of all pages that use {{event}}?

Ideally something like this for the 2390 pages:

| URL | macro call |
|---|---|
| https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/onend | {{event("end_(SpeechRecognition)","end")}} |

(there might be multiple macro calls per page)

[jwhitlock]

I have a different gist for finding macro usage, but it uses a naive regex parser so it may not catch every user, and combines several macros together. But, I thought quick results may be better than good results. I've uploaded the results to a Google sheet. If you need better data, I can iterate on the script.

[a2sheppy]

I suggest that we have an event JSON file that provides information about all the events, including the target interface. This would be useful both for the {{event}} macro and for several other things, such as generating "related events" lists and automatically generating the blue event info boxes.

Something like:

"icecandidate": {
  "api": "WebRTC",
  "target": "RTCPeerConnection",
  "handler": "RTCPeerConnection.oniceconnection", // null if no onfoo
  "type": "RTCPeerConnectionIceEvent",
  "bubbles": false,
  "cancelable": false,
  "related": [
    "iceconnectionstatechange", "icegatheringstatechange"
  ]
}

The target interface could then be taken from the JSON and used by {{event}} to produce a correct link.