Short syntax to link to fragment inside other spec

speced / respec

A tool for creating technical documents and web standards

https://respec.org/

Other

717 stars 386 forks source link

Short syntax to link to fragment inside other spec #2708

Open jyasskin opened 4 years ago

jyasskin commented 4 years ago

Important info

URL to affected spec: https://github.com/w3c/fingerprinting-guidance/pull/39/files
ReSpec version: 25.0.4
[x] I did a "hard refresh", but it's still busted.

Description of problem

What happened?:

The syntax <a data-cite="?HTML/webstorage.html#user-tracking">[HTML#user-tracking]</a> links to a fragment inside the HTML spec, but [[[?HTML/webstorage.html#user-tracking]]] does not.

But what I was expecting?:

[[[spec#frag]]] or [[spec#frag]] interprets its content like a data-cite attribute.

sidvishnoi commented 4 years ago

The [[[expand]]] syntax presently only works for spec names and local anchors, as we already have their textContent values. What should be the textContent in this case?

jyasskin commented 4 years ago

I don't have a strong opinion: it's a stylistic choice, just like the choice to render [[expand]] as "[expand]". I used "[HTML#user-tracking]" as the text content, omitting the "/webstorage.html", but including it would be fine with me.

sidvishnoi commented 4 years ago

Wouldn't the inverse be a better option where author specifies the text and ReSpec appropriately links? We already support this for definitions and IDL, we can extend support for other terms as well.

sidvishnoi commented 4 years ago

Also, how about [[[ expand | optionalTextContent ]]]? I'm not sure if it's better than data-cite syntax though. We already support [= link term | textContent =] for definitions.

jyasskin commented 4 years ago

Supporting [[[?HTML/webstorage.html#user-tracking]]] (with implied text content of "[HTML/webstorage.html#user-tracking]") and [[[?HTML/webstorage.html#user-tracking | replacement text content]]] would be fine with me. I would be sad if the | replacement text content were required.

jyasskin commented 4 years ago

For reference, Bikeshed's similar feature is described at https://tabatkins.github.io/bikeshed/#section-links.

marcoscaceres commented 4 years ago

so unfortunately we don't support this yet, but we are exploring how to add it on the Respec.org server/service. Will leave this open for now.