Re: Various respec enhancements ...

On Wed, Sep 17, 2014 at 2:47 AM, Robin Berjon <robin@w3.org> wrote:
> On 16/09/2014 20:01 , Tab Atkins Jr. wrote:
>>> Namespacing would work basically like this. Say you have a markup
>>> attribute
>>> and a DOM attribute both called 'unicorn'. You could have
>>> <dfn>dom:unicorn</dfn> and <dfn>attr:unicorn</dfn>, and
>>> <a>dom:unicorn</a>
>>> would link to the right one (and drop the namespace on render of course).
>>> If
>>> you need a : in your dfn, \-escaping works.
>>>
>>> Alternatives would solve the common problem of referring to the same dfn
>>> with variants (typically, plurals) for which today one has to annoyingly
>>> resort to @title. For that, just use <dfn>unicorn|unicorns|long-toothed
>>> horse</dfn>.
>>
>>
>> We've already solved this problem in Bikeshed/Shepherd, and it would
>> be a crying shame to have ReSpec try to solve it in an incompatible
>> way, as it would mean the two types of specs couldn't talk to each
>> other.
>
>
> I was aware that you'd solved the alternatives issues, which is why I was
> thinking of the same syntax, but I hadn't seen that you had the namespacing
> as well. That's pretty cool!

It's even stronger than that - some things are namespaced on not just
their type, but on what thing they're associated with.  CSS, for
example, defines a million "auto" keywords in various contexts;
Bikeshed's data model allows them to be marked up with a
"data-dfn-for" attribute containing what it's for (usually the
property name), and you can then reference that when auto-linking to
disambiguate.

>> Bikeshed's relevant documention is here:
>>
>> <https://github.com/tabatkins/bikeshed/blob/master/docs/definitions-autolinks.md>.
>> We've got a taxonomy of dfn types, which can also be applied to
>> autolinks to disambiguate.  There are multiple ways to specify what
>> type a dfn is - an explicit data-dfn-type attribute, an id matching a
>> particular pattern, a class (on the element or an ancestor) matching a
>> particular pattern, or the text of the dfn itself matching certain
>> patterns.  Bikeshed makes this all pretty trivial and turns it
>> explicit in the source for you, but ReSpec specs obviously would need
>> to be a little more explicit about things, so that the correct
>> information shows up in the source html.
>
> Actually I'm pretty sure that ReSpec could support exactly the same syntax.

The problem is that Shepherd isn't really able to do the ReSpec
transformations, so it'd need to be reflected in the source.  As an
offline processor, this is trivial for Bikeshed, but it means more
work for someone using an online processor like ReSpec.

>> I'd *really* like ReSpec and Bikeshed to agree on this stuff, so that
>> I can autolink into ReSpec specs.
>
> Note that specref has nominal support for cross reference finding, but the
> data is lacking (to say the least). You, Tobie, and I should bang our heads
> together to make this broadly available. It's not rocket surgery.

Yeah, SpecRef's cross-linking support is Anolis-inspired, where you
have to specify the id every time (and you have to uniquify IDs across
all documents, I think?).  It's a very poor data model, unfortunately.
Shepherd (maintain by Peter Linss) does all the parsing and
dfn-finding for Bikeshed, and is aware of Bikeshed's data model (me
and Peter evolved it together).  It's publicly available at
<http://api.csswg.org/shepherd/>.

~TJ

Received on Wednesday, 17 September 2014 19:37:20 UTC