search

speced / respec

A tool for creating technical documents and web standards
https://respec.org/
Other
709 stars 376 forks source link

More flexible title id generation #4712

Open egekorkan opened 1 month ago

egekorkan commented 1 month ago

Description of problem

URL to affected spec or repo:

https://w3c.github.io/wot-thing-description/ontology/td

What happened (e.g., it crashed)?: ReSpec always inserts the id title for the document title. However, if there is already a section id with value title in the document, it causes issues with linking to that section.

Expected behavior (e.g., it shouldn't crash): In such cases, respec should display a warning. It can also try to iterate and add title2 etc. Even better would be a configuration option to set a custom title id.

Optional, steps to reproduce:

  1. Go to https://w3c.github.io/wot-thing-description/ontology/td#title
  2. Expect to land at section 4.3.12 but the window moves to the top of the page, i.e. to the document title

Note: I am not sure why the title needs an id. Maybe removing that addition of the id can make sense?

marcoscaceres commented 1 month ago

I think the W3C pub rules checker needs id=“title” iirc.

marcoscaceres commented 1 month ago

And yeah, that’s weird if it’s not detecting the collision. Is that second title explicitly set to id=title?

marcoscaceres commented 1 month ago

Yeah, the document is explicitly setting the id:

<section id="title"><h4>title</h4>

Respec won't override author's id. You will need to set it to something else (otherwise w3c pub rules will also break)

egekorkan commented 1 month ago

I think the W3C pub rules checker needs id=“title” iirc.

Ok I did not know that. Do we know why they need it? As a first solution we have removed it from our publications.

Is that second title explicitly set to id=title?

Yes since it is a vocabulary term of our information model and it is linked by external documents as well so we cannot change it.

egekorkan commented 1 month ago

Funny enough, pubrules checker does not complain with missing id=title https://validator.w3.org/nu/?doc=https%3A%2F%2Fw3c.github.io%2Fwot-thing-description%2Fpublication%2Fver11%2F7-resources%2Fontology%2FstaticFiles%2Ftd

marcoscaceres commented 1 month ago

To be sure, that’s the html validator (not the w3c pub rules). However, let me check about the id.

egekorkan commented 1 month ago

No id related errors at https://www.w3.org/pubrules/?url=https%3A%2F%2Fw3c.github.io%2Fwot-thing-description%2Fpublication%2Fver11%2F7-rec%2FOverview&profile=REC&validation=simple-validation&informativeOnly=false&echidnaReady=false&patentPolicy=pp2020

Also if it is needed for pubrules check, why not add it only when generating a static file?

marcoscaceres commented 1 month ago

Ok, thanks for also checking. Seems I had misremembered.