html-page-title: minimise the number of notes

[WilcoFiers]

This was a suggestion from the ACT TF.

Need for Final Call: none

[Jym77]

I'm a bit uncomfortable with the whole crusade for killing notes we've had recently.
I understand that this is orders from the TF and thus we probably don't have that much saying in it… But I think we should have discussed it in a CG call before starting to aggressively remove every single note.
There is an agenda item for this (#1305) but as far as I remember, we've never actually discussed it in a call…

[jeeyyy]

a reference or a definition of what is a non-embedded page will be useful.

[Jym77]

Yeah, I'd probably use "top-level browsing context" (or something in that line) instead of "non-embedded", given that it is the technical term of what we try to do. And similarly "nested browsing context" instead of "embedded".

OTOH, so far we've avoided links inside the description of rules.
This was fairly easy when descriptions were short; but might become increasingly harder with longer description (absorbing notes).

I do not know why we were avoiding links in descriptions and whether that still need to be the case or not…

[WilcoFiers]

I think if we want to do that we should make the description a heading in the doc, instead of making it part of the frontmatter. That's a separate PR. I don't think that should hold up this PR.

[Jym77]

Looking back at that specific case: how would you feel about moving this second sentence to the background section?
(#1305 (comment))

I feel that it is "information about the background for the development of the rule" (to quote the ACT format) and thus fits there.
Putting it in the description feels like it is very important information that we want to show immediately to readers. But in that case, it feels more like some "corner case FAQ" for people having read the rule and wondering "why only non-embedded?"

[Jym77]

We might want to update that to use https://act-rules.github.io/glossary/#web-page-html instead. This would remove the need for "if it is an html element" since our definition is only about HTML.

This is most likely topic for another PR, however. But may be related to https://github.com/act-rules/act-rules.github.io/pull/1340/files#r438130594

[WilcoFiers]

Go for it.

[Jym77]

Yeah, I'd probably use "top-level browsing context" (or something in that line) instead of "non-embedded", given that it is the technical term of what we try to do. And similarly "nested browsing context" instead of "embedded".

OTOH, so far we've avoided links inside the description of rules.
This was fairly easy when descriptions were short; but might become increasingly harder with longer description (absorbing notes).

I do not know why we were avoiding links in descriptions and whether that still need to be the case or not…

Updated

[Jym77]

Looking back at that specific case: how would you feel about moving this second sentence to the background section?
(#1305 (comment))

I feel that it is "information about the background for the development of the rule" (to quote the ACT format) and thus fits there.
Putting it in the description feels like it is very important information that we want to show immediately to readers. But in that case, it feels more like some "corner case FAQ" for people having read the rule and wondering "why only non-embedded?"

Updated, please check again

[Jym77]

👍