Re: Thinking about cross references and ReSpec

On Wed, Oct 1, 2014 at 10:10 PM, Shane McCarron <shane@aptest.com> wrote:

> There was an earlier thread where one side-discussion was about cross
> references.  Basically, Bikeshed and Shepherd have a system for doing
> cross-document references to things like terms.  I like the concept of
> this, but of course Bikeshed and Shepherd are document processors, not
> client-side magic like ReSpec, so....
>
> I have this *idea*.  Or maybe it is an concept that could be turned into
> an idea if I expand upon it.  Something like this:
>
>    - Adopt the Bikeshed syntax for definitions.  This is fairly rich, and
>    is well documented at [1].
>
> Agreed.

>
>    - Define a 'protocol' that ReSpec can use to query / update a
>    definition service with the data from a and dfn elements, respectively.
>    - Provide a reference implementation of a service that supports the
>    protocol.
>
> So what I'll be working on will have a JSON over HTTP API.

>
>    - Add code to the def / a module of ReSpec that uses the protocol to
>    communicate with a document-defined end point.
>
> So in theory a family of documents could coordinate their term definitions
> by all pointing to the same service endpoint.  In the PFWG we have a number
> of documents where this would be a huge help.  I imagine if such a service
> were available, a lot of other groups that rely upon ReSpec would find it
> much easier to reference definitions where they live rather than importing
> them.
>
> There are some obvious flaws in a design like this (overhead, speed,
> fragility, exposure to DoS).  But I don't feel the risks are much worse
> than the current specref use.  We would need some sort of registry in the
> reference implementation to help control where updates can come in from,
> etc.
>

My plan for this solution is to do daily crawling of relevant specs and
extract the dfn and put them in a DB. Further refinements could include a
search API, like I added for Specref and exposed within Respec.

P.S.  Tobie, I know that you were talking about something in this space for
> Q4... and maybe this is what you are already thinking about.  If so,
> consider this brainstorming / requirements gathering.
>

My focus will be on the gathering the data and providing a JSON API. Not on
actual implementation within ReSpec (which I won't have cycles for at that
time, I'm afraid).

--tobie