Re: [ReSpec] dated versions of works in progress

On Tue, 2010-05-18 at 11:45 +0200, Robin Berjon wrote:
> On May 17, 2010, at 16:06 , Dan Connolly wrote:
> > I think I saw, in the ReSpec source code, its own bibliography
> > of W3C specs. Why is that?
> > 
> > Does the bibliography generator not suffice for some reason?
> > http://www.w3.org/2002/01/tr-automation/tr-biblio-ui
> 
> 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.

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. That search tells
me it's linked from the standards faq.
  http://www.w3.org/standards/faq

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.
 http://lists.w3.org/Archives/Public/spec-prod/#tools
(though it's called "extractor" rather than "generator"
there, which doesn't help people remember how to search
for 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.

>  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.

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

> 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.

> By the way it looks like there's a small bug in the tool. If it doesn't recognise an URI you get:
[...]
> Which isn't the best response, some indication of error would probably be
> more helpful for any tool chained behind this one.

Yeah... so far, nobody has been bothered enough to fix that.

> Thanks for the pointer!

Sure.

-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/
gpg D3C2 887B 0F92 6005 C541  0875 0F91 96DE 6E52 C29E

Received on Tuesday, 18 May 2010 13:21:50 UTC