Document missing RTCPeerConnection»createOffer params

[sideshowbarker]

Fixes #12164

Also fixes some broken macros and links.

[github-actions]

Preview URLs

• https://pr12165.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/RTCPeerConnection/createOffer

Flaws

None! 🎉

External URLs

URL: /en-US/docs/Web/API/RTCPeerConnection/createOffer
Title: RTCPeerConnection.createOffer()
on GitHub

No new external URLs

(this comment was updated 2022-01-28 01:35:14.891033)

[wbamberg]

Thanks for the PR @sideshowbarker !

I don't think we should add these two options, since as far I can tell they're not in the spec any more. Also I don't think we should add that inline HTML: this hasn't been our practice before, and if we adopt it generally we will end up with a messy mix of HTML and Markdown.

The link fixes are fine though :).

[sideshowbarker]

I don't think we should add these two options, since as far I can tell they're not in the spec any more.

They’re in the spec at https://w3c.github.io/webrtc-pc/#attributes-2 and they are implemented in browsers — though the section they’re in is “Legacy configuration extensions”, which I suppose should mean that we mark them as deprecated (since the spec says, “Developers are encouraged to use the RTCRtpTransceiver API instead”.

Also I don't think we should add that inline HTML: this hasn't been our practice before, and if we adopt it generally we will end up with a messy mix of HTML and Markdown.

That’s pretty disappointing to hear. I would think that having the utility to direct developer readers to the specific point-of-use places in the docs where they can find the information they need would take precedence over our concerns as maintainers about any internal markup details that don’t end up getting exposed to readers in the rendered content.

Do you have another suggestion about what the cross-references should link to in this case?

[sideshowbarker]

Do you have another suggestion about what the cross-references should link to in this case?

Ah, I now see your comment, “It would be fine for the other page to link to #values”. I don’t agree that would be fine. That just makes things easier for us as maintainers at the cost of making things more difficult for our readers.

[wbamberg]

This was discussed in the Markdown conversion: https://github.com/mdn/content/discussions/6322. and honestly I thought we had consensus for it. My concern really is that if we have a policy where people can add <span> elements whenever they want to link to something, we'll end up with a mishmash of Markdown and HTML, and it'll almost be worse than just HTML.

If we want to make elements of syntax sections linkable perhaps we could auto-generate ID attributes for dt elements, as we already do for headings.

That just makes things easier for us as maintainers at the cost of making things more difficult for our readers.

Yes. There are trade offs we made moving to Markdown and this was one of them.

[sideshowbarker]

If we want to make elements of syntax sections linkable perhaps we could auto-generate ID attributes for dt elements, as we already do for headings.

Agreed. Is there a reason we’re not already doing that? Is there an open Yari issue for it? If not, should I raise one?

[wbamberg]

If we want to make elements of syntax sections linkable perhaps we could auto-generate ID attributes for dt elements, as we already do for headings.

Agreed. Is there a reason we’re not already doing that? Is there an open Yari issue for it? If not, should I raise one?

I haven't raised one and I doubt anyone else has. I'd be happy for you to. I can't think of a reason not to do it.

[sideshowbarker]

If we want to make elements of syntax sections linkable perhaps we could auto-generate ID attributes for dt elements, as we already do for headings.

Agreed. Is there a reason we’re not already doing that? Is there an open Yari issue for it? If not, should I raise one?

I haven't raised one and I doubt anyone else has. I'd be happy for you to. I can't think of a reason not to do it.

Opened mdn/yari#5190 with a patch.

[sideshowbarker]

@wbamberg About the options, did you see my reply at #12165 (comment) ?

[wbamberg]

@wbamberg About the options, did you see my reply at #12165 (comment) ?

Sorry, yes. I think it would be OK to mark them as deprecated.

[wbamberg]

👍 thanks!