Macros and browser compatibility indicators

MDN
#1

With browser-compat-data, we now have a single source of truth for experimental status. I think in the (possibly quite near) future the {{SeeCompatTable}} macro will be retired, and pages will use the compat data to decide whether to show some kind of “warning! experimental!” notice.

I don’t think we’ve considered the case of {{experimental_inline}} yet. Actually this is a worse case than {{SeeCompatTable}}, because the macro doesn’t live in the docs page for the item.

So if I update, say, Element.clientTop, then I might remember to change the macro on that page, but I have no idea where on the site {{experimental_inline}} calls might reference it. So it’s not surprising it gets so out of date.

Would we lose more than we gain by removing {{experimental_inline}} entirely? If the user visits the actual page for the item, they will see it is experimental anyway.

“Experimental” banners in API docs
#2

What we might instead do is create a single macro that takes on the responsibility of adding all relevant icons for a term, looked up in the BCD store. That way, we could do something like:

clientTop {{status_icons(“api.element.clientTop”)}}

The macro would then insert the HTML for any relevant icons, including experimental status if applicable.

Once that macro has been written, we can remove all the other status badge icons in favor of this one new one. Pending such removal, I wonder if we can find a way to cause the first invocation of any of those to instead run the status_icons macro, and then further invocations to do nothing within the same block.

Regardless, I feel pretty strongly that the goal should be a single macro that handles all badging for items in lists, so we can stop having to manually update these things.

Eric Shepherd
Senior Technical Writer

MDN Web Docs: https://developer.mozilla.org/

Blog: http://www.bitstampede.com/

Twitter: http://twitter.com/sheppy

#3

And now that I’m thinking about it further, we could go a step farther and include the status icon generation in our new-generation link building macros. We’ve been talking about replacing cssxref, domxref, HTMLElement, and so forth with new more intelligent macros with more flexibility and better usability.

Those macros could automatically handle injecting status icons after the text of the link when the circumstances warrant (presumably based on a parameter, although bonus points if we can figure out how to do it automatically based on context somehow).

For instance, domxref could be replaced with a new macro APIXRef:

{{APIXRef("[InterfaceName][.methodOrPropertyName[()]]", alternateText, anchor, flags)}}

This is similar to the proposal I make in bug 1314662, except for the added flags parameter. This would be a set of Boolean flags defined as enums and available by ORing the enum values together. Among these would be things like forcing the use of <code>, overriding the automated logic and whether or not to automatically append the status icons.

Sheppy

Sheppy

#4

Actually, doing the icons automatically based on context would be easy by having site CSS for it. Have a class for each badge type (non-standard, obsolete, etc, as appropriate) so that a macro call like {{APIXRef("Foo.bar")}} would result in HTML like this:

<code class="apixref api-property api-readonly api-nonstandard">
    <a href="/en-US/docs/Web/API/Foo.bar">Foo.bar</a>
</code>

The CSS would normally not do anything special with this. but if the parent element is <dt> or <td>, the classes api-readonly and api-nonstandard would kick in to add the appropriate icons after the text.

We can also look at ways to automatically or optionally decide not to include the redundant interface name if the current page is part of that interface, without requiring the writer to explicitly write out the substitution as {{APIXRef("Foo.bar", "bar")}}, which is silly given that when the current page is part of the Foo documentation, usually the Foo. is implied.

Sheppy