Re: References Re: What are the requirements/problems? Re: Working on New Styles for W3C Specifications

On Dec 14, 2011, at 11:45 , Dominique Hazael-Massieux wrote:
> But note that the JSON file would have the same problem as the RDF one,
> namely that the order of the editors would be wrong — getting this fixed
> in the RDF file has been a long standing bug. 
> 
> A few questions, though:
> * do we want the equivalent of ReSpec.js' biblio.js, or a JSON file with
> more structured data on the specs?
> * if the latter, can anyone propose a sample of what the JSON properties
> should be?

I think that there are two results that an API can useful return. One is the decomposed version with multiple properties, and the other is just the (polyglot) HTML that one needs to inject into the specs to make a proper reference. I don't have a preference, just pointing out that we might not need to descend into data modelling hell and might be able to get away with HTML snippets.

Just FYI, after parsing all the references that people use in ReSpec-generated specifications (there were ~850) I found the following data model that can describe pretty much all of them except really degenerate cases.

• Identifiers. That's just a string (e.g. HTML, XML10, or WEBIDL-20110918). There can be multiple identifiers pointing to the same reference.

• References. These contain (all are optional unless otherwise indicated):
    - Document name. Required.
    - Editors. Ordered list of simple names.
    - et al. Whether to include "et al." at the end of the editors' list.
    - URI. Where to find the document.
    - Date. Overall a free-form string (there only seems to be consistency inside given organisations).
    - Status. Maturity level, depends on organisation.
    - WIP. A boolean indicating whether this should be flagged as "Work In Progress".
    - Additional notes. Some HTML that provides some extra notes, for whatever reason.

The above is far from perfect, but it flies.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon

Received on Wednesday, 14 December 2011 11:07:51 UTC