speced / respec

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

Correct way to reference ED versions for new definitions #3134

Open igneel64 opened 4 years ago

igneel64 commented 4 years ago

Is your feature request related to a problem? Please describe. The issue that we are facing, is finding the correct way to reference definitions from the ED version of a document before it is published.

The new references to different specs will point out to the already published document which is not the ED making them invalid.

An example: <a data-cite='PERFORMANCE-TIMELINE-2#dfn-performance-entry-buffer'>performance entry buffer</a> will point correctly at https://www.w3.org/TR/performance-timeline-2/#dfn-performance-entry-buffer

In the case now that we need to add a new reference to something that is in the ED version of the Perfromance Timeline spec (w3c.github.io/performance-timeline), how should we go about it without having a broken link pointing to something that does not exist.

Is the only alternative to use something like a full href: <a href="https://w3c.github.io/performance-timeline/#dfn-performance-timeline-task-source">performance timeline task source</a> ?

If this has already been discussed, it would be nice to point me to the proposed way. /cc @yoavweiss

sidvishnoi commented 4 years ago

An alternative here might be to make use of localBiblio:

var respecConfig = {
  localBiblio: {
    "PERFORMANCE-TIMELINE-ED": {
      status: "ED",
      href: "https://w3c.github.io/performance-timeline/", 
    },
  }
};

and then use it as:

<a data-cite="PERFORMANCE-TIMELINE-ED#dfn-performance-timeline-task-source">performance timeline task source</a>

I'm not sure if this is recommended over passing the full href, though it seems shorter and less brittle. cc: @marcoscaceres

marcoscaceres commented 4 years ago

The right way to do this is just to publish performance-timeline to /TR/. There shouldn't be any reason to reference the ED draft because the cost of publishing to /TR/ in the 2020 W3C Process is virtually zero (i.e., editor's drafts can basically go away). CC'ing @plehegar as he can probably provide the best guidance here.

marcoscaceres commented 4 years ago

(BTW, @sidvishnoi has some awesome GitHub actions for auto-publishing to TR... it only takes a few minutes to set up).

sidvishnoi commented 4 years ago

https://github.com/sidvishnoi/spec-prod/

dontcallmedom commented 4 years ago

Note that there will be hopefully soon an improved mechanism for collecting definitions from specs (cf https://github.com/tabatkins/bikeshed/issues/1761) at which point definitions from ReSpec editors drafts will also get imported, not just the ones from TR documents.

marcoscaceres commented 4 years ago

Sounds cool. Reminds me, we should try to organize some time during TPAC to chat about what we want the future of W3C publications to look like more broadly over next few years. We've got some tremendously powerful systems now, so it would be good to look to the future and make some kind of roadmap for spec capabilities.

dontcallmedom commented 4 years ago

@tidoust and I have been thinking to organize a TPAC breakout around that topic, with a focus on editors outreach; but I think a spec-infrastructure-builder catch up meeting would also be be great (maybe outside of the TPAC breakout week then?)

marcoscaceres commented 4 years ago

I'm happy to chat before, during, or after :) We just need to figure out the timezone situation.