Docs and discussion for MDN macros

MDN
#1

Thank you greatly for the example search hacks. Such are vital to finding and tackling hidden bits scattered throughout MDN.

And the bit above about fixing older info being hit or miss is only confirmed by finding that you had very recently fixed a glitch regarding window.scrollY but then not the same for window.scrollX :wink:

After seeing the below discussion, and with regard to another ‘want’ regarding macros, is there anywhere a summary of macros and their uses? I end up crawling over Wikipedia’s template documents trying to figure out what was the intended correct usages. I can manage there. Is there similar here?

Is there a central discussion place for macros? I can see the need for macros for “not for IE/Edge” or “not for IE <9” and, if I can’t find them already existing, where do I go?

And thank you jswisher - putting search hacks in front of us common hacks is great!

“Experimental” banners in API docs
#2

is there anywhere a summary of macros and their uses?

There is this: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros but it’s incomplete and probably a little out of date.

Because of the history of how macros have been developed and maintained, we have too many macros, that have a lot of redundancy, inconsistency and nonexistent test coverage.

We would like to reduce the number of macros to a manageable number of properly tested, documented, and structured macros, and the first step towards that is to figure out which macros are no longer needed and remove them, updating pages where necessary to avoid breakage. We’re currently at 468 macros, and would love to get to under 200. But it’s going to be a long process.

Is there a central discussion place for macros?

Macros live on GitHub: https://github.com/mdn/kumascript and that would be the place for filing issues and PRs. I’m not sure you need a macro for “not for IE/Edge” though - we should use https://github.com/mdn/browser-compat-data for all browser compat, then we can present it in a consistent way.

1 Like
#3

Yeah. It’s very easy to let this happen—especially when apache is updated coincidentally when working on some other page that refers to it.

In addition to the list on the “Commonly used macros” page, you can peruse the sources for the macros. Almost all of them start with a comment block documenting the macro.

I bet we could have a script extract those comment blocks and build a macro reference doc… Hm.