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

Re: In-sentence bib references with ReSpec

From: Cameron McCormack <cam@mcc.id.au>
Date: Thu, 21 Oct 2010 10:43:36 +1300
To: Robin Berjon <robin@berjon.com>
Cc: spec-prod@w3.org
Message-ID: <20101020214336.GB840@wok.mcc.id.au>
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.

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.

For references to IDL definitions, I would love to be able to type just

  <p>The <a>frobber</a> attribute lets…

to get something like

  <p>The <code><a href=#widl-Whatever-frobber
  class=idl-attribute>frobber</a></code> attribute lets…

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

> 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)?

> ReSpec v2 also uses different plugins to identify references and to
> generate the biblio list at the end — not sure if this would be a
> problem, but I thought I'd flag 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.

Cameron McCormack ≝ http://mcc.id.au/
Received on Wednesday, 20 October 2010 21:44:14 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:15 UTC