Case sensitive macro names?

[hamishwillee]

Yari is case insensitive with respect to macro names - so in the docs we have {{glossary("Xxxxx")}} , {{Glossary("Xxxxx")}}, and {{Deprecated_Header}} and {{deprecated_header}}, and so on.

Josh has started looking at consistency for the naming in JavaScript section: mdn/content#29008 and mdn/content#29006. The selected format is the most common used, which probably matches https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros.

Consistency makes me happy, but since the macros are MDN-wide I think it is worth making sure we are all happy with both making this change, and the actual agreed format.

My preference is:

• We do only allow one case-sensitive format
• That format is all lower case (snake case). That is the easiest format to remember as an author, and it makes no difference to users.
• We plan to disallow other formats and make them a flaw.

[Josh-Cena]

I prefer lowercase for xref macros (jsxref, domxref, cssxref) and snake case (optional_inline, deprecated_header), but I prefer the "real case" for all CamelCase macros, like HTMLElement, HTTPHeader, PreviousNext, SeeCompatTable, etc. because those are much easier to read :( Furthermore, @OnkarRuikar would need to change the BCD sync script if we agree to use deprecated_header instead of Deprecated_Header.

FYI, here's the macro count on main (for the JS section):

And here's the set of macro casings I settled on tentatively:

[hamishwillee]

FWIW Its a real pity we didn't settle on sake case or camel case when this was started. The mix is what makes it hard. The best option would be to rename anything that needs to be to be snake case. But that would be disruptive. If we're going to to do this I'd still prefer one rule - so: htmlelement, httpheader, previousnext, seecompattable.

Doing it at all is disruptive - once you decide that it is worth doing you choose the right way and suck up any pain :-).

[Josh-Cena]

I would prefer doing it like how we actually case things in a programming language: you use either snake_case or CamelCase, and it's fine if there's a mishmash of both (for legacy reasons), but you don't do seecompattable. Again, I would be overjoyed if we agree to change seecompattable to see_compat_table.

[Josh-Cena]

I would be very happy if (a) all macros can use snake_case (b) they are all valid JS identifiers, but that sounds far too disruptive.

[OnkarRuikar]

I would love to see CamelCase because it's more compact than snake_case and it stands out, e.g.

{{embed_live_sample("example_showing_some_thing", "100%", "300px"}}
vs
{{EmbedLiveSample("example_showing_some_thing", "100%", "300px"}}

I did try to make macro calls consistent before, tried changing to camel case. But changing massive amount of files just to change case was not welcomed.
We have grown accustomed to using different cases for each macro, e.g. jsxref, HTTPHeader, and deprecated_header. So changing to fixed case will cause some discomfort. In the beginning we could allow people to use whatever case they want and update the macro calls at the end of the day in our nightly automated linting. Eventually when people get used to the case then we can start enforcing the case in Husky and PR workflows.

We plan to disallow other formats and make them a flaw.

Using our custom linter will be more effective than the Yari flaws mechanism.

---

As we are on the topic of prettying the macro calls, we need to iron out following issues as well:

• {{ CSSref }} vs {{CSSref}}: Someone was/is adding spaces around the macro names to make them more readable. But this creates conflict with the automation scripts because the usage is not fixed.
• {{CSSref()}} vs {{CSSref}}: We can get rid of () in cases where there are no arguments.
• {{Macro("arg")}} vs {{Macro('arg')}}: Can we choose to have only double quotes?
• Use of px or % in live sample macro calls and other inconsistencies:

{{EmbedLiveSample('audio', '100%', '70px')}}
{{EmbedLiveSample('audio', '100%', '70')}}

{{EmbedLiveSample('audio', 250, 250)}}
{{EmbedLiveSample('audio', '250', '250')}}

{{EmbedLiveSample('audio', '', '70px')}}
{{EmbedLiveSample('audio', '100%', '70px')}}

{{EmbedLiveSample('audio_example')}}
{{EmbedLiveSample('audio example')}}

[Josh-Cena]

@OnkarRuikar These are all issues fixable by my checker, which does a full parsing of the macro content and runs Prettier over the expression. I plan to roll out these changes one by one.

[bsmth]

Thanks for kicking off the discussion, it's frustrating to grep through for matches as we have so many different formats. No preference on the casing, but it would be great to stick to one format per macro. The same sentiment on the list Onkar has pointed out; it would be great to be inflexible on these cases.

No preference:
I'm happy with what others decide for these:

• lower / mixed / CamelCase
• singe v double quotes
• % v px

Preference:
I think the following makes sense:

• disallow brackets when no arguments
• whitespace (+1 to get rid of it when not needed)
  • we have multiline macro calls, this would be good to make single-line

[yin1999]

Just to draw attention: we also have different formats for the width and height parameters of the livesample macro (quoted/unquoted numbers).

• {{EmbedLiveSample("some_id", 120, 150)}}
• {{EmbedLiveSample("some_id", "120", "150")}}

[wbamberg]

For naming, I prefer snake case to camel case, but I don't really care as long as we don't have more than one naming convention. I don't want to have to remember which convention to use for which macro, that's just ridiculous. If we're going to do that we might as well leave things in the current mess and save a lot of grief.

The best option would be to rename anything that needs to be to be snake case.

Yeah, I agree, this is best, and next best, if we don't want to rename, would be just to adopt snake case.

But that would be disruptive.

For renaming: the disruptiveness I think is mostly in two parts:

1. making and reviewing additional diffs, to change the places that renamed macros are called
2. getting people used to using new names

For the first of these, I think the additional disruption on top of just snake-casing is not that great, just because most of our invocations use at least one uppercase letter. I made a spreadsheet: https://docs.google.com/spreadsheets/d/1oXrwRhLRM745z0QOAm53ezaPcI55SId9gsFV4ffA7gQ/edit?usp=sharing that lists all the different macro invocations in all our docs, and tries to assess for each one:

• whether it would need to be changed to implement snake case
• whether it would need to be changed to implement renaming only (meaning, if we didn't need to change it anyway for snake-casing)

You can see most of the diffs - 71370 - are incurred in snake-casing, and only an additional 3105 in renaming.

(This also shows that just snake-casing is a BIG change, and hard for humans to review reliably. IMO we should use machines to test the change instead of relying on human review.)

One open question there is whether we rename xrefs (e.g. domxref to dom_xref) - @Josh-Cena above proposed we make an exception for xrefs. For these numbers I excluded xrefs, but that would add a lot more churn.

The second part of disruptiveness - getting people used to using new names - is harder to quantify, but I think it would be OK. We will get used to the names quickly enough.

But renaming also tends to open another worm-can. Why are some of our xrefs called thingxref and some aren't? Why are some of our sidebars called thingsidebar but some aren't? Why are some of our banner/header macros called thingheader and some aren't?

[hamishwillee]

Re ^^^ whether we consider this in 1 phase or 2 really depends on whether we can get changes to the macros approved. If this is in doubt 2 phases make sense. If not we should just agree the final point and work towards it.

My assumption is that given this is a name change we can create new macros for the changed name versions, make content changes, then remove the old versions. Anyone can submit a copied macro with a new name so that's doable. You have rights to merge right @wbamberg ? If that approach is doable I'll stop talking phase 1.

[wbamberg]

You have rights to merge right @wbamberg ?

Yes.

I'm in favour of doing it all in one go I think, for 2 reasons:

• it will be painful and scary, and one round of that is better than 2. It's like when you go to the dentist and they do all your root canals at once.
• doing things in 2 phases always makes me wonder, what if we don't get to phase 2? And then in this case we will be stuck with case-sensitivity, but half in camel case and half in snake case, which for writers is in some ways worse than case-insensitivity.

However! Although I'm happy to help support this I won't be able to put time into planning it out, I just have too much else going on at the moment. I think y'all are making good choices about it though 👍 .

[hamishwillee]

@wbamberg Thanks. I deleted my phase 1 column

• HW column is what I think we might end up with IF we can test changes by building and binary compare.
• HW invert column puts the category as a prefix
• Now we are thinking churn is not an issue then does anyone very strongly have an opinion for/against CamelCase? I don't care as long as we are consistent.
• I added "_link" as an identifier for previous, next, glossary and so on
• proposing _info as category for anything that pulls in data - such as css syntax, inheritance, compat, etc.
• I moved embed_ to be a suffix for consistency
• propose we prefix internal_ to tag things we don't really expect people to use directly

Or to put it another way given that we are now saying we might suck up the churn then our previous decisions need to be revisited:

• CamelCase vs snake case: JsXref vs js_xref (I prefer snake - less compact but all lower case removes decisions)
• Prefix vs suffix for type - i.e. xref_js/XrefJs, vs js_xref
• All use type identifier, or only some - html_element or html_element_xref
• What types do we prefer - OK with link, embed, info, internal, xref, inline, header, sidebar?

[yin1999]

The "Total need call-site changing for snake case" field has not included the macro calls in translated-content. I think this would be a huge task.

[hamishwillee]

@yin1999 if we do it then largely an automated process both in terms of conversion and testing. So perhaps not as scary as you think

[OnkarRuikar]

Regarding other macro related suff.

1. I prefer double quotes over single quotes:

-- {{Macro('arg')}}
++ {{Macro("arg")}}

2. Explicit double quotes:

-- {{EmbedLiveSample("audio", 250, 250)}}
++ {{EmbedLiveSample("audio", "250", "250")}}

3. No brackets for zero arguments:

-- {{CSSref()}}
++ {{CSSref}}

4. No space between macro call and curly braces:

-- {{ APIRef }} {{ Non-standard_header }} {{ deprecated_header }}
++ {{APIRef}} {{Non-standard_header}} {{deprecated_header}}

5. Explicit use of units:

-- {{EmbedLiveSample("audio", "100", "70")}}
++ {{EmbedLiveSample("audio", "100%", "70px")}}

No preference for following cases:
6. Empty params:

-- {{EmbedLiveSample('audio', '', '70px')}}
++ {{EmbedLiveSample('audio', '100%', '70px')}}

7. Sentence or single word:

-- {{EmbedLiveSample("Audio example")}}
++ {{EmbedLiveSample("audio_example")}}

[hamishwillee]

• Agree 1-4 inclusive.
• 5, 6: I prefer units but happy to have on hold it it requires a change to Yari? Yes, empty params need to be marked.
• 7: I prefer sentence for the "7" because then I just copy in the heading text.

[OnkarRuikar]

happy to have on hold it it requires a change to Yari?

Yari sets the width and height arguments as it is on iframe. Treat it as <iframe height="${arg}"> So no change on Yari side is needed.

[OnkarRuikar]

PS Does anyone want to test Will's theory that we can do a binary compare of before/after changes for generated content to validate macro changes?

If no one else I guess I can - is it just yari build to create a local tree?

Using command line we can use following shell script:

# 1. get fresh `mdn/content` code

# 2. assuming you've the latest yari code and done `yarn install`
cd /projects/mdn/yari
yarn build --locale en-us
mv client/build /temp_dir/build

# 3. do the macro renaming in `mdn/content`

# 4. build content again
yarn build --locale en-us

# 5. list the files that are different
diff -qr /temp_dir/build/ client/build > different_files.log

On Windows I think this should run without any issues in GIT BASH.
For step 5 you can use GUI diff tool Meld for dir comparison.

[hamishwillee]

I'm too lazy. Result is that the approach will work or not?

[OnkarRuikar]

I'm too lazy. Result is that the approach will work or not?

It is working for me in Linux setup. If you want give me the changed content and I'll run the test.

[hamishwillee]

Cool. We'll have to agree the final set and then create some macros etc before we can get that far. Someone will also have to write a conversion script.

[OnkarRuikar]

Cool. We'll have to agree the final set

Do we need a meeting for this?

Someone will also have to write a conversion script.

Simple regex search replace in any IDE should do it.

[hamishwillee]

@OnkarRuikar I was thinking maybe a bit more than basic regexp for the bits you identified here https://github.com/orgs/mdn/discussions/448#discussioncomment-6963747

I think the next step is that I will create a column "Agreed changes" and see if anyone disagrees with any of them :-)

But probably not until Monday

[hamishwillee]

So in the sheet there were are few contentions around the xref and suffixes

• jsxref (JC) or js_xref (WB)
• glossary (JC) or glossary_xref.
• html_element (JC), html_element_xref (HW)

1. A suffix (or prefix) is supposed to differentiate the type. You might not think html_element_xref is needed, but a newbie could think that html_element means a sidebar for html elements, or a list of html element.
   So IMO we either have suffixes and use them consistently or not at all.
2. Could we have no xref suffix? So js, css, api, etc. Maybe, if we consistently have an extension for every other type _sidebar, _list and so on. I personally think it is better to have it and be consistent.
3. I prefer js_xref to jsxref for consistency reasons - same pattern for all suffixes.

[Josh-Cena]

html_xref doesn't make sense because you are only linking to elements, not attributes. I'm all for htmlxref if we end up having the same macro that replaces both html_element and html_attr.

glossry_xref also doesn't make sense because xref means "link to reference", but glossary is not a reference.

The idea is this: if we are linking to a "reference section" as a whole, and the section contains many parallel sets of topics, then we add the xref suffix. For example:

• The entire web API reference is one flat list of the API interfaces. Therefore api("fetch") by itself is good. One complication is that there are also guide pages mixed among these, so we either change the content structure or prevent them from being linkable to keep the "purity" of the api macro.
• The JS reference contains disjoint sets of documents for globals, statements, and expressions. Therefore, the name js by itself tells you nothing about the semantics of the page being linked to (what is js("class")?) In this case, we add the suffix xref to be explicit that it's a link to the entire reference. We may also use js_global("Array") and js_statement("while"), but I'm sure people won't want that.
• The CSS reference also contains disjoint sets of documents for pseudoclasses, functions, selectors, etc. Therefore it's the same situation and we add xref.
• The glossary is (a) not a reference (b) contains a flat list of term definitions, therefore glossary("identifier") is good enough.
• The HTML reference contains documents for elements and attributes. It happens that there are also two macros—html_element and html_attr—bravo!

I hope that makes sense?

[Josh-Cena]

I don't feel too strongly about jsxref vs js_xref, as I also commented in the doc. My main arguments are:

• Significantly less churn (xrefs are by far the most popular macros and are ever growing in number)
• Easier authoring experience (takes much less time to type a letter compared to an underscore)

But I can relate: I used to think it means jsx_ref, because JSX is an actual thing. However, that doesn't really affect how I use the macro; just a bit of misunderstanding.

[hamishwillee]

I'm not so concerned about the churn if we are able to get this checked using an approach like @OnkarRuikar tried here https://github.com/orgs/mdn/discussions/448#discussioncomment-7009651.

[hamishwillee]

PS I tried that approach and it seems to work. @Josh-Cena I had some more questions above https://github.com/orgs/mdn/discussions/448#discussioncomment-7097778 - basically we're all still happy with suffixes rather than prefixes? I think we're happy with js_xref vs jsxref too.

[Josh-Cena]

I don't feel strongly about using prefix or suffix, although I don't see a strong motivation to change the existing ones either. api_sidebar does read more naturally than sidebar_api to me. However I feel like compat => compat_info doesn't add much meaning. Usually the suffix "info" is not needed; it's only added for css_info because css doesn't make sense. If we decided to use prefix, then xref_js would be good, but in the status quo I want to keep jsxref,