Help ReSpec conversions

[tabatkins]

There are a few ReSpec-isms that aren't obvious to catch when converting to Bikeshed. In particular:

• ReSpec does some weird thing with <dl class=idl title="..."> that then generates an IDL block. Should look for these and WARN about them, recommending a switch to <pre class=idl>.
• ReSpec doesn't have Bikeshed's dfn metadata hierarchy; in particular, it's easy to miss links that should be IDL but are accidentally marked up as plain dfn autolinks.

[marcoscaceres]

There are a few ReSpec-isms that aren't obvious to catch when converting to Bikeshed. In particular:

ReSpec does some weird thing with

that then generates an IDL block. Should look for these and WARN about them, recommending a switch to

.

I have a PR that warns the user that old school

IDL definitions are deprecated.

ReSpec doesn't have Bikeshed's dfn metadata hierarchy; in particular, it's easy to miss links that should be IDL but are accidentally marked up as plain dfn autolinks.

I wouldn't mind aligning on this. I'll check the BS docs and try to implement. Do you have tests I could reuse?

[tabatkins]

I have a PR that warns the user that old school

IDL definitions are deprecated.

Cool! I might still warn about it in Bikeshed too, tho. ^_^

I wouldn't mind aligning on this. I'll check the BS docs and try to implement. Do you have tests I could reuse?

No, but I have thorough documentation.

[foolip]

One thing that would really help with w3c/webdriver#1462 is the ability to control whether dfn- get prepended to the IDs of generic <dfn>s.

[foolip]

(Posted too quick by accident.)

I have a change that I applied locally to do this unconditionally:

diff --git a/bikeshed/unsortedJunk.py b/bikeshed/unsortedJunk.py
index 0cb01a19..f86ed7b3 100644
--- a/bikeshed/unsortedJunk.py
+++ b/bikeshed/unsortedJunk.py
@@ -677,7 +677,7 @@ def classifyDfns(doc, dfns):
                 else:
                     id = config.simplifyText(primaryDfnText)
             if dfnType == "dfn":
-                pass
+                id = config.simplifyText("dfn-{id}".format(id=id))
             elif dfnType == "interface":
                 pass
             elif dfnType == "event":

@tabatkins have you had other requests to customize ID generation? Is there another approach I could take to keep the many IDs starting with dfn- in https://w3c.github.io/webdriver/ working?

[marcoscaceres]

@foolip, anything we can do on the ReSpec side, let us know... also, we support most of the BS syntax now + all the cross referencing, so would like to know if we are missing something?

[foolip]

@marcoscaceres I'm just a lot more familiar with Bikeshed, and after we set up https://github.com/w3c/webdriver-bidi with Bikeshed I volunteered to fix w3c/webdriver#1462, mainly to make it trivial to copy content between them, and to make myself more familiar with the existing WebDriver spec in the process.

It's not the cause for switching, but I have noticed that Bikeshed spots a lot more issues with unused definitions and single-use variables, the types of issues fixed in w3c/webdriver#1515 and w3c/webdriver#1518.

[marcoscaceres]

heh, coincidently was talking about prioritizing those warnings with @sidvishnoi today :) thanks for the info @foolip! that's quite helpful.