W3C home > Mailing lists > Public > spec-prod@w3.org > October to December 2010

Re: In-sentence bib references with ReSpec

From: Robin Berjon <robin@berjon.com>
Date: Tue, 26 Oct 2010 10:12:10 +0200
Cc: spec-prod@w3.org
Message-Id: <A887D4D8-E390-4F59-9C0C-381CCF542DF3@berjon.com>
To: Cameron McCormack <cam@mcc.id.au>
Hey Cam,

On Oct 20, 2010, at 23:43 , Cameron McCormack wrote:
> Robin Berjon:
>> I'm open to suggestions (and implementations) but one design "rule"
>> I've tended to follow is to stay away from inventing yet another
>> wiki-like markup that ends up being just as complicated to remember
>> as the HTML it's supposed to replace. That's why there are very few
>> text-based syntactical constructs and they all tend to look a lot like
>> what you'd do in plain text anyway.
> 
> Yeah.  For the SVG 1.1SE document (as you probably know) I didn’t have
> any wiki-like markup, and instead made anything that should be
> automatically linked be referenced with a plain <a> element.

Yup.

> So maybe,
> 
>  <p>Please read <a>RFC2119</a>. [[!RFC219]]
> 
> ?  I am interested in reducing the amount I need to type, so I would
> like to avoid having to do <a class=citation>RFC2119</a> or something.

That could indeed work, the only issue is one of disambiguation. The attribute-less <a> is already used to refer to <dfn> terms. I think it would be great to enable it to refer to other things as well, we just need to make sure that people don't refer to the wrong thing too easily.

> if “frobber” is unique enough.  Maybe with <a>Whatever::frobber</a> if
> it needs disambiguation.

That would be awesome.

>> Caveats aside, the above seems reasonable, but will hit into the issue
>> that the references aren't available in a format that makes that easy.
>> An overall improvement of the referencing system has been mentioned
>> several times, but hasn't taken off yet.
> 
> Where did the biblio information come from (presumably it was
> automatically generated for W3C specs, which I guess takes care of most
> of the entries in biblio.js)?

Initially it was extracted from the DB that powers the CSS tool. There is indeed some level of automatic extraction that's possible from the W3C specs (there's tr.rdf, and a SPARQL endpoint) but that only covers W3C.

Everyone agrees the reference system needs an overhaul. Maybe we should have a quick BoF at TPAC and work out what to do to it.

>> Either way, if you have the tuits, we take patches!
> 
> I’m happy to provide patches.  I don’t know if I should be providing
> patches to ReSpec 1 or 2, though.

Provide patches against the version you're using yourself. Patching v2 is likely to be easier (it's modular and uses jQuery), but of course it's also less stable.

-- 
Robin Berjon - http://berjon.com/
Received on Tuesday, 26 October 2010 08:13:11 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Saturday, 10 March 2012 06:19:17 GMT