Using macros (cssxref, SVGAttr, etc) vs regular links

[leon-win]

Recently I've been uniformizing the use of length, percentage and length-percentage references (mdn/content#31874). I applied the corresponding macro ({{cssxref}}) everywhere.

When making similar changes to translated-content (mdn/translated-content#18012), concerns about the use of such macros became known: if they were deprecated, then it would be necessary to do the opposite -- replace the use of macros with regular links.

So there are questions:

1. Is there a roadmap to deprecate certain macros?
2. What is better to use -- macros or regular links?

[Josh-Cena]

Most maintainers, from my impression, are either indifferent or prefer regular links. I'm in the minority to prefer macros. In any case I don't think there is any official deprecation of these macros, at least in the main content. Localization teams are of course free to impose additional stylistic restrictions where they see fit, as long as it doesn't directly contradict with the main content's.

[leon-win]

@Josh-Cena thank you for reply!

[leon-win]

And is it known what was the purpose of creating such macros?

It turns out that they only reduce the consistency of document source codes.

[wbamberg]

See also https://github.com/orgs/mdn/discussions/624 and https://github.com/orgs/mdn/discussions/350 .

Actually I think Josh makes good points in https://github.com/orgs/mdn/discussions/350, and we could imagine an xref system that worked well, but that would take infrastructure work.

[Josh-Cena]

And is it known what was the purpose of creating such macros?

In the days when MDN was authored with HTML, it was very tricky to write markup and get them done right, so a lot of macros were created. These xref macros were simple but they still replace the <a><code></code></a> boilerplate. Most of the benefits I listed in the linked discussion apple from then till now, including (a) they abstract away the site structure details (b) they allow us to deduplicate some texts (c) they allow us to build certain "wrappers" instead of making it "just" an <a> tag. For example, the glossary xref doesn't add code formatting but jsxref does—I think that's a very good semantic distinction.

It turns out that they only reduce the consistency of document source codes.

Having multiple ways to do the same thing is fine, IMO, it all depends on what expresses the idea the most clearly. If I can write an xref with only one parameter, I use an xref; if I need three or four parameters, I consider a Markdown link instead. It's the same idea as many other syntactic sugars in programming: margin-top/margin, while/for...

[leon-win]

@Josh-Cena, @wbamberg, thank you for the detailed answers and links to previous discussions. Now I have read all the information and realized that this is not such a simple topic as I thought before)
In general, I also like the idea of macros, but now I understand that they are not ideal.

To summarize, I will write explicit answers to the questions:

1. There is no plan to deprecate macros.
2. The choice between using links or macros is not regulated. One good criterion is the number of parameters when using a macro: if several parameters are required, then it is probably better to use a link.