search

tobie / specref

An open-source, community-maintained database of Web standards & related references.
http://www.specref.org/
Apache License 2.0
163 stars 142 forks source link

Handling editions of W3C recommendations #463

Open palemieux opened 6 years ago

palemieux commented 6 years ago

As it stands, it looks like like entries like TTML1 refers to the most recent version of TTML1, which is fine since references to specific versions, e.g. ttml1-20041101 are also available.

It looks like there is however an issue with the TTML1 entry as it is current generated:

Glenn Adams; Pierre-Anthony Lemieux. Timed Text Markup Language 1 (TTML1) (Third Edition). 24 April 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/ttml1/ ED: https://w3c.github.io/ttml1/index.html

The URL points to the Latest Version link https://www.w3.org/TR/ttml1/ and not the This Version link https://www.w3.org/TR/2018/CR-ttml1-20180424/.

This is an issue across editions. As an example, IMSC 1.0.1 refers to TTML1. When IMSC 1.0.1 was published, only TTML1 2ED has been published, and so the reference reads:

Timed Text Markup Language 1 (TTML1) (Second Edition). Glenn Adams. W3C. 24 September 2013. W3C Recommendation. URL: https://www.w3.org/TR/ttml1/

The URL https://www.w3.org/TR/ttml1/ however now points to TTML1 3ED. This is pretty confusing to readers, and may yield issues if IMSC 1.0.1 had in fact relied specifically on TTML1 2ED.

Would it make sense for the URL of entries such as TTML1 to point to the This Version link?

tobie commented 6 years ago

Would it make sense for the URL of entries such as TTML1 to point to the This Version link?

Well, we'd need something consistent. So this couldn't be specific to certain entries, or to even to specs which have multiple editions (as there's little consistency as to how those are represented). At the same time, the behavior you describe is desired for a number of use cases, so we cannot replace it altogether.

There's a number of things that could be done here. But each one is substantial and would possibly require coordinating with the different tools that rely on Specref.

Unless someone is willing to invest the resources needed to build and support this, I think your best bet is to go for dated numbers, or possibly just created aliases for the versions you care about.

palemieux commented 6 years ago

@tobie How are the references to W3C recommendations generated?

At the same time, the behavior you describe is desired for a number of use cases, so we cannot replace it altogether.

Which use cases? It seems undesirable to have the name of the specification in the reference not matched the specification to which the URL points to.

tobie commented 6 years ago

The use case is specs that don't change name across version and/or edition.

palemieux commented 6 years ago

Ok. So if there was a means of extracting the title without the edition number, then that name could be used, and so, for example, the TTML1 reference would be generated as:

Glenn Adams; Pierre-Anthony Lemieux. Timed Text Markup Language 1 (TTML1). 24 April 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/ttml1/ ED: https://w3c.github.io/ttml1/index.html

Did I get this right?

tobie commented 6 years ago

Edition numbers and version numbers are really complicated to handle because everyone does them differently and has a different understanding of what they mean. I have no idea how to fix that without some serious re-engineering of how Specref considers, stores, and handles data.

From Specref's perspective a title is a title. Unless the spec changes shortname as is changes version/edition, we'll have these URL issues.

palemieux commented 6 years ago

Understood. I plan to follow-up with W3 staff for their opinion.

tobie commented 6 years ago

We had a number of conversations with @plehegar and @deniak on the topic. And it ties in to some of the work they've been doing.

palemieux commented 6 years ago

Thanks for the pointers. Totally thinking out loud, it might be good if the W3 specifications had metadata that contains a canonical title, independently of edition number and pub date -- just like the spec status is not embedded in the title.

tobie commented 6 years ago

I don't disagree. Some editors and WGs do, however.

palemieux commented 6 years ago

That makes us two at this point, which is bigger than 1 :)

plehegar commented 6 years ago

Note that respec handles subtitles., eg https://w3c.github.io/pointerevents/

Now, compare the data from https://www.specref.org/?q=pointerevents2

and the actual WD at https://www.w3.org/TR/pointerevents2/ (the subtitle got dropped in specref)

This is because we don't expose through our API those subtitles. So, if you actually want to drop edition and version numbers, the solution is to put them as a subtitle (in html, this means use an h2 instead of h1).

marcoscaceres commented 6 years ago

Watching with interest... does the W3C API derive the "title" from <title> or from the head's <h2>. If it's getting it from <title>, then we can maybe concatenate the spec's title and subtitle, into title (subtitle). But, PubRules would need to allow <tile> and <h2> to differ.

plehegar commented 6 years ago

(I think you mean head's h1, not head's h2. I misspoke earlier when I said "instead of h1". You always need the h1 but you can use an additional h2 for the subtitle)

Not sure about the API but the title of a spec is extracted from the h1 in pubrules using https://github.com/w3c/specberus/blob/master/lib/rules/metadata/title.js

If I understand correctly, the actual "official" metadata that gets into our API is extracted by a separate mysterious metadata script/job. @deniak would know more here.

In any case, as you pointed out, pubrules enforces title === h1 in https://github.com/w3c/specberus/blob/master/lib/rules/headers/h1-title.js

I actually like the way it is at the moment, ie you have the choice to put the version number in the title of the spec or leave as a subtitle in the h2. In other words, if you want to contain the version number, make it part of the h1.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/marcoscaceres"><img src="https://avatars.githubusercontent.com/u/870154?v=4" />marcoscaceres</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <blockquote> <p>I actually like the way it is at the moment, ie you have the choice to put the version number in the title of the spec or leave as a subtitle in the h2. In other words, if you want <title> to contain the version number, make it part of the h1.</p> </blockquote> <p>Agree. </p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/palemieux"><img src="https://avatars.githubusercontent.com/u/4871350?v=4" />palemieux</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>So... in the case of <a href="https://www.w3.org/TR/2018/CR-ttml1-20180424/">TTML1</a>, you are suggesting that <em>(Third Edition)</em> could be carried in an <code>h2</code> so that it is not picked up by spec-ref?</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/marcoscaceres"><img src="https://avatars.githubusercontent.com/u/870154?v=4" />marcoscaceres</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>Yes, I believe that is correct. </p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/tobie"><img src="https://avatars.githubusercontent.com/u/3392?v=4" />tobie</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>That wouldn't be immediate, though. W3C would need to republish the spec for this change to be effective. </p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/plehegar"><img src="https://avatars.githubusercontent.com/u/1490400?v=4" />plehegar</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>@palemieux . it is indeed correct. Since 3rd is a CR, you could make the update in the editor's draft and our system would pick that up at the next publication.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/palemieux"><img src="https://avatars.githubusercontent.com/u/4871350?v=4" />palemieux</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>Ok. Thanks, so it sounds like this issue can be closed? Would it make sense to document this thread in respec... for future generations?</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/tobie"><img src="https://avatars.githubusercontent.com/u/3392?v=4" />tobie</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>Yeah, the underlying problem is that W3C doesn't have a real defined concept of what a version or an edition is. I'm not too sure where that issue should be filed, @plehegar?</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/plehegar"><img src="https://avatars.githubusercontent.com/u/1490400?v=4" />plehegar</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>@tobie, <a href="https://github.com/w3c/guide/">https://github.com/w3c/guide/</a> would be the place. Version management is documented in <a href="https://www.w3.org/2005/05/tr-versions">https://www.w3.org/2005/05/tr-versions</a> at the moment but could be moved into the Guide repo.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/skynavga"><img src="https://avatars.githubusercontent.com/u/377455?v=4" />skynavga</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>From my perspective, the problem is that IMSC doesn't employ the correct URL. The intent of the generic URL is to be fluid, and be updated as new editions are created. By using that URL in IMSC, you get a non-fixed resource to dereference (and must live with it). On the other hand, if IMSC wants to refer to a specific edition, then it should do so, and thus have a fixed resource to dereference.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/nigelmegitt"><img src="https://avatars.githubusercontent.com/u/4988915?v=4" />nigelmegitt</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>For information, w3c/ttml1#353 is in a holding pattern pending any clear agreement on how W3 is going to handle this. It's clear already from <a href="https://github.com/tobie/specref/issues/463#issuecomment-385781680">https://github.com/tobie/specref/issues/463#issuecomment-385781680</a> that using a subtitle in <code>h2</code> is an option, but that further work would be needed, perhaps in backend tooling, to populate the title shown in specref with the unqualified (no subtitle) one for generic spec URLs and the qualified (concatenated with subtitle) one for specific spec URLs.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/tobie"><img src="https://avatars.githubusercontent.com/u/3392?v=4" />tobie</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>Deleted a bunch of comments that were referencing a comment @skynavga had changed in the meantime and that were thus adding confusion.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/tobie"><img src="https://avatars.githubusercontent.com/u/3392?v=4" />tobie</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>@nigelmegitt to clarify my position here, handling versions and editions is an automated way in Specref is a lot of work that I'm not expecting anyone to feel like doing (and then supporting), or be willing to pay for in the near future. I wouldn't expect a resolution to this issue under 18 months. Not to mention that this potentially relies on prior work at the W3C level (which might add another year to the equation).</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/nigelmegitt"><img src="https://avatars.githubusercontent.com/u/4988915?v=4" />nigelmegitt</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <p>Thanks @tobie that's useful information. I had the impression from @plehegar that possibly specref would not be changed at all and the only change would be in backend W3 systems.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/tobie"><img src="https://avatars.githubusercontent.com/u/3392?v=4" />tobie</a> commented <strong> 6 years ago</strong> </div> <div class="markdown-body"> <blockquote> <p>further work would be needed, perhaps in backend tooling, to populate the title shown in specref with the unqualified (no subtitle) one for generic spec URLs and the qualified (concatenated with subtitle) one for specific spec URLs.</p> </blockquote> <p>I'm unable to tell whether adding support for this in Specref—granted it was actually added on the W3C side and exposed in W3C's rdf file (which Specref still relies on)—is a 5 minute job, or requires a complete re-architecture of the project. There is <em>a lot</em> of technical debt in Specref.</p> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>