search

speced / respec

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

data-cite=SPECNAME unexpectedly throws #2432

Open saschanaz opened 5 years ago

saschanaz commented 5 years ago

Important info

Description of problem

What happened (e.g., it crashed)?:

<a data-cite="FEATURE-POLICY">Feature Policy</a> is resolved as https://www.w3.org/TR/feature-policy-1/ as expected but still marked as an error: Couldn't match "feature policy" to anything in the document or to any other spec. Please provide a data-cite attribute for it.

But what I was expecting?: It should not throw.

Thoughts? @sidvishnoi

sidvishnoi commented 5 years ago

@saschanaz https://github.com/w3c/respec/issues/2394, https://github.com/w3c/respec/issues/2386

<a data-cite="FEATURE-POLICY">Feature Policy</a>, by default, xref will look up for "Feature Policy" in "FEATURE-POLICY" spec, which cannot be found. When it fails, it links to the spec only, and also stating an error that "feature policy" couldn't be found - in case that's a mistake trying to link to a term that doesn't exist.

If we intend to link to spec only, we have to add data-no-xref (https://github.com/w3c/respec/pull/2409), which unfortunately is an additional work. Other alternatives would be to use [[ spec ]] or [[[ spec ]]].

saschanaz commented 5 years ago

Thanks for the explanation! Given that we already have seen several breakages, maybe adding a helpful message would be good.

sidvishnoi commented 5 years ago

Agreed. First priority is to reduce the breakages, then add more helpful messages. (Hopefully both within this week)

marcoscaceres commented 5 years ago

It’s weird, as I thought “feature policy” is exported from FEATURE-POLICY.

marcoscaceres commented 5 years ago

For feature policy, it was [= Document/feature policy =] :) thanks @sidvishnoi again for the xref ui!!! 💗

AmeliaBR commented 4 years ago

Is there any update on this? What is the current best practice if I just want to link to a spec, not a particular term in that spec?

As is, I'm currently getting all sorts of spurious errors even though the generated links are exactly what I want. It makes it pretty difficult to identify real errors. The data-no-xref attribute no longer works, although turning off xref linking altogether (with xref: false in the config) solved the problem, since I'm not actually using automatic definition/IDL linking in this document.

sidvishnoi commented 4 years ago

What is the current best practice if I just want to link to a spec, not a particular term in that spec?

You can use either [[spec]] or [[[spec]]].

The data-no-xref attribute no longer works

Can you share markup or URL to the spec?

AmeliaBR commented 4 years ago

You can use either [[spec]] or [[[spec]]].

That doesn't work if you need custom link text.

Can you share markup or URL to the spec?

Markup for whole document (our hosted page is a static snapshot, so you'll need to download or use a rawgit-like proxy). Some snippets:

<a data-cite="fullscreen" data-no-xref="">fullscreen</a> mode.

Displaying a map viewer as a <a data-cite="picture-in-picture" data-no-xref="">Picture-In-Picture</a> (PIP)

The <a data-cite="geolocation-API" data-no-xref="">Geolocation API</a>
and <a data-cite="geolocation-sensor" data-no-xref="">Geolocation Sensor API</a>

Overall, I'm glad to see the XRef functionality added, but I wish it used a new data-xref-specs attribute to give it context, instead of redefining data-cite in a breaking way. But I suppose it's now been in the wild long enough that changing back would break too many specs, too.

marcoscaceres commented 4 years ago

I think what ReSpec is telling you there is correct (i.e., your usage of data-cite is incorrect)... for instance:

<a data-cite="fullscreen" data-no-xref="">fullscreen</a> mode.

"fullscreen mode" is not a defined thing in the fullscreen spec. You would need to find some explicitly exported concept to link to from fullscreen specification. Maybe [=fullscreen element=]?

If none of the exported concepts are suitable, then you need to ping the Editor of the Fullscreen spec to export a suitable definition for your spec. 

The <a data-cite="geolocation-API" data-no-xref="">Geolocation API</a>
and <a data-cite="geolocation-sensor" data-no-xref="">Geolocation Sensor API</a>

Those should be [[[Geolocation]]] and [[[geolocation-sensor]]] respectively.

AmeliaBR commented 4 years ago

The [[[shortname]]] syntax for citing a spec often doesn't work in prose because the official spec titles can be awkward or inconsistent. E.g., [[[Geolocation]]] and [[[geolocation-sensor]]] expands to ”Geolocation API Specification 2nd Edition and Geolocation Sensor”, which doesn't make sense in my sentence.

That triple-bracket syntax was always described just as a shorthand for <a data-cite="shortname">{optional link text}</a>, so I am surprised that you consider it incorrect to use data-cite to link to a spec as a whole, instead of to a particular term.

And again — the links ReSpec was generating were exactly correct! The only problem was that it was calling it an error. (Well, that and it maybe shouldn't insert <cite> elements when using author-supplied link text instead of inserting the official title.)

sidvishnoi commented 4 years ago

data-no-xref not working was a bug (#2821). You can enable xref again with that. We're also extending [[spec]] syntax to support custom text in #2822.

sidvishnoi commented 4 years ago

With the next release (tomorrow probably), we can link to a spec as:

AmeliaBR commented 4 years ago

Thanks for the very helpful updates and bug fixes @sidvishnoi!