Re: [ReSpec] dated versions of works in progress

On May 18, 2010, at 15:22 , Dan Connolly wrote:
> On Tue, 2010-05-18 at 11:45 +0200, Robin Berjon wrote:
>> Well, the primary reason is that, as usual, tools are perfectly well hidden deep inside dated space so that they can't ever be found :)
> 
> It is indeed frustrating that the recent redesign clipped some
> links/paths from the tech reports page to the tool,
> but I don't think "dated space" has much to do with findability.

In this case, indeed not, but if one can't complain about dated space also in bad faith then is life really worth living?

> It's the top search hit for "bibliography generator" on our site
> (or "w3c bibliography generator" on your favorite search engine).
> That does require knowing it exists.

Yup. I searched for various things (I think "bibliography database" might have been one of them) when I was looking into this but I didn't stumble upon this tool. Is there a master list of all tools? I would find that quite useful (but I'm guessing that there's no way to automate the generation of such a list).

> I'd expect typical readers of this mailing list to know about it,
> though, since it's discussed here from time to time and
> one of the tools linked from the archive cover page.

I guess I didn't pay attention back when I didn't need it, and forgot about it.

>> That being said, I don't get the impression that it would address the needs that ReSpec has.
>> The idea of references in ReSpec is that you just mention [[DAHUT]] in the body of the text,
>> and it will automatically insert an entry in the references section, and make that text a link.
>> So it needs a label to biblio entry mapping which it doesn't look like tr-biblio-ui provides.
>> I guess we could have a label to URI mapping and call to this tool,
> 
> I wonder if the shortnames would serve for the [[DAHUT]] label; if so,
> you could skip the mapping table.

That's certainly a good idea. Part of the problem though is that existing labels still need to work lest content be broken. But using shortnames for automatic updates would certainly be the way to go.

>> but that would only work
>> while online — I want ReSpec to as much as possible work
>> completely offline (e.g. on the plane)
>> and from the local file system (the only exception
>> being the TR CSS which can't be loaded that way).
> 
> I think the bibliography generator is just one XSLT script
> plus a copy of tr.rtf... but I suppose getting it running
> locally is a bit fidgety, compared to just some javascript code.

Right, the idea is that an editor can just checkout ReSpec and their spec, and will not need to learn any tooling whatsoever — the browser's enough.

That being said I've been having updating from tr.rdf on my todo list for a while now. It would only handle the W3C references but that would already be helpful. I'd have to run the tool regularly to keep it in sync but I can live with that. I guess I'll do it when I get some round tuits to spend on v2.

> I'm sure we could provide a JSON version of tr.rdf. I wonder
> if that would help.

It would make the parsing more straightforward but I have no issue handling tr.rdf as is. I'd probably do it in Perl so as to update the existing DB, without requiring that the end users have access to it anyway.

That being said, I think that having a tr.json would be a good idea in general.

>> Also, the ReSpec bib DB (which was pilfered from Bert's CSS spec generation
>> tool) has a lot of references that aren't W3C specifications.
> 
> Maintaining that sort of thing by hand gives me the willies.
> Oh well... different strokes, I guess.

Oh yeah, me too. At least v2 switches to individual HTML snippets over the v1 big JSON file which breaks every single ReSpec spec whenever someone commits it with a syntax error :) But interestingly enough, so far the current system has worked pretty well, I think mostly thanks to the fact that people immediately took it upon themselves to update it (as the log shows http://dev.w3.org/cvsweb/2009/dap/ReSpec.js/bibref/biblio.js).

But yes, automating references to W3C specs is certainly planned, and I guess that it could handle RFCs as well. For other references though, I'm not sure how much we can do.

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

Received on Tuesday, 18 May 2010 15:29:16 UTC