search

speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.12k stars 201 forks source link

Make algorithm name optional #1693

Open foolip opened 4 years ago

foolip commented 4 years ago

As discussed in https://github.com/tabatkins/bikeshed/issues/1603, <div algorithm> can be used to provide scope for variables and enable the highlighting feature when clicking them.

However, if one uses <div algorithm> twice, one gets the error "Multiple declarations of the '' algorithm."

Bikeshed wants the name of the algorithm, but that's usually repeating something from right below. Other times, the algorithm doesn't have a name, it's just steps you should run when something else happens.

Can the algorithm name be made optional?

mkruisselbrink commented 4 years ago

It sort of already is optional. If the <div algorithm> contains exactly one dfn, that will be used to identify the algorithm. Only when you have zero or more than one dfn in an algorithm do you need to specify a name (and in practice I rarely run into this).

tabatkins commented 4 years ago

Algorithms need names so I can report errors properly, etc. As Marign says, tho, most of the time Bikeshed can infer the algo name by itself.

If you have a <div algorithm> around some steps without a <dfn> in them... what are you trying to define? What's the algorithm that is important enough to define the markup-scope of, but not important enough to get a linkable definition?

foolip commented 4 years ago

Aha, I hadn't noticed that the name is inferred in some cases. The case I ran into is https://w3c.github.io/webdriver-bidi/ defining both a https://w3c.github.io/webdriver/#dfn-additional-capability-deserialization-algorithm and a https://w3c.github.io/webdriver/#dfn-matched-capability-serialization-algorithm, but neither of them named.

Knowing that it works like this, I could give those a name.

foolip commented 4 years ago

@domenic I see you reacted. Have you tried sprinkling in <div algorithm> in any specs and run into any similar issues, where it would be awkward to name the algorithm?

foolip commented 4 years ago

linkable definition

@tabatkins it looks to me like no ID is generated for the algorithm block, if that's what you meant. Is it Shepherd that annotates the definition as an algorithm by using this construct?

domenic commented 4 years ago

I see you reacted.

In general I think supplying Bikeshed information that purely helps error reporting should be optional.

Have you tried sprinkling in <div algorithm> in any specs and run into any similar issues, where it would be awkward to name the algorithm?

Yes. This mainly occurs in monkeypatches, e.g. https://wicg.github.io/origin-policy/#monkeypatch-fetch or any of the other algorithms in https://wicg.github.io/origin-policy/#monkeypatches. It looks like I decided to not use <div algorithm> there (despite using it for other parts of the spec). https://wicg.github.io/origin-policy/#monkeypatch-fp is especially interesting since it replaces the algorithm wholesale, so (unlike some of the others in those section) it's completely standalone. But it would be inappropriate to <dfn> it.

tabatkins commented 4 years ago

it looks to me like no ID is generated for the algorithm block, if that's what you meant. Is it Shepherd that annotates the definition as an algorithm by using this construct?

No, I was referring to the dfn.

This mainly occurs in monkeypatches

In both of those cases it still seems reasonable to give an algorithm name. A dfn is just useful for inferring one; <div algorithm="my cool algo"> still works any time, tho, and without any ID or autolinking implications. (So far, at least.)

In general I think supplying Bikeshed information that purely helps error reporting should be optional.

My intention is that it will be useful for more than just error reporting eventually.

Tangentially,

wicg.github.io/origin-policy/#monkeypatch-fp is especially interesting since it replaces the algorithm wholesale, so (unlike some of the others in those section) it's completely standalone. But it would be inappropriate to dfn it.

I don't understand why it wouldn't be appropriate to dfn this? If you're replacing the algo, presumably you want autolinks to go straight to it, no?

domenic commented 4 years ago

In both of those cases it still seems reasonable to give an algorithm name.

It's just busywork though, done purely to keep Bikeshed happy. So I opted not to.

I don't understand why it wouldn't be appropriate to dfn this? If you're replacing the algo, presumably you want autolinks to go straight to it, no?

I don't want specs to have to differentiate between the canonical algorithm and my monkeypatched one. Nobody should generally be linking to the monkeypatched one. (Except perhaps inside my monkeypatching spec, but in that case I just use section links to refer to "monkeypatches to the Feature Policy spec" in general.)