Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support giving spec URL as {{Specifications(...)}} argument #5329

Closed
wants to merge 1 commit into from
Closed

Support giving spec URL as {{Specifications(...)}} argument #5329

wants to merge 1 commit into from

Conversation

sideshowbarker
Copy link
Member

Related: mdn/content#13273 (comment) • This changes allows authors to give the Specifications macro a spec URL as an argument; like this:

{{Specifications("https://w3c.github.io/webappsec-secure-contexts/")}}

cc @wbamberg

Related: mdn/content#13273 (comment)

This change allows authors to give the Specifications macro a spec URL
as an argument; like this:

{{Specifications("https://w3c.github.io/webappsec-secure-contexts/")}}
@schalkneethling schalkneethling added the 🧑‍🤝‍🧑 community contributions by our wonderful community label Feb 28, 2022
@caugner caugner added the macros tracking issues related to kumascript macros label Mar 11, 2022
Copy link
Contributor

@caugner caugner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I'm not quite sure what the changes in document-extractor.js do, so I added some remarks.

Comment on lines +346 to +347
let browsers;
let data;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where are browsers and data used, apart from their assignment?

@@ -342,8 +342,17 @@ function _addSingleSpecialSection($) {
const [proseSections] = _addSectionProse($);
return proseSections;
}
const query = dataQuery.replace(/^bcd:/, "");
const { browsers, data } = packageBCD(query);
let query = dataQuery.replace(/^bcd:/, "");
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this variable is only read once in the else branch.

Could you move it there and make it const?

let browsers;
let data;

if (dataQuery && dataQuery.trim().match("^http[s]?://")) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a short comment before this block explaining what it does / we need this?

@schalkneethling schalkneethling removed their request for review April 5, 2022 10:19
@schalkneethling
Copy link

@sideshowbarker Please see @caugner’s comments when you have a moment. Thank you.

@sideshowbarker
Copy link
Member Author

sideshowbarker commented Apr 13, 2022

I’m closing this PR in favor of consideration for #5971 and #5972, which essentially would allow us to move completely away from ever using the {{Specifications}} macro — and also completely away from ever using the {{Compat}} macro either.

The context is that #5347 (reply in thread) has persuaded me that it would be a good idea for us to move wholly over to just using the browser-compat and spec-urls macros, and never using the {{Specifications}} and {{Compat}} macros.

The specific parts of #5347 (reply in thread) I found persuasive were:

Macros with arguments

...
…my preferences are toward:

  1. Providing fewer ways to author things. Either the key is the only way it's done, or there ought be more unified way of richly citing/embedding non-MDN content.
  2. Not committing to Kumascript-isms in Markdown.

In general, I'd really like to get away from macros as a way of embedding stuff in Markdown and it didn't feel like it was in scope for this discussion. That said, I'd like us to explore alternatives to Kumascript macro syntax, particularly the bits that are most unlike Markdown (in this case, arguments).

So #5971 and #5972 are also in line with our general de-macro-ization plans — in that they’d take us a big step closer to completely eliminating the {{Specifications}} and {{Compat}} macros altogether.

@sideshowbarker sideshowbarker deleted the sideshowbarker/Specifications-macro-argument-with-spec-urls branch April 13, 2022 12:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🧑‍🤝‍🧑 community contributions by our wonderful community macros tracking issues related to kumascript macros
Projects
Development

Successfully merging this pull request may close these issues.

3 participants