In-sentence bib references with ReSpec

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

In-sentence bib references with ReSpec

Cameron McCormack-4
I would like a shorthand to include a link directly to a bibliography
entry source.  For example, let’s say I want to generate the following
sentence

  <p>You really <em class=rfc2119>SHOULD</em> read <a
  href=http://www.ietf.org/rfc/rfc2119.txt><cite>Key words for use in
  RFCs to Indicate Requirement Levels</cite></a> before throwing <em
  class=rfc2119>MUST</em> around. [<cite><a href=#bib-RFC2119
  rel=biblioentry class=bibref>RFC2119</a>]

I want some shorthand to generate the citation link.  Something like:

  <p>You really SHOULD read [[#RFC2119]] before throwing MUST around.
  [[!RFC2119]]

But I’m happy to hear a suggestion on a different shorthand format.

--
Cameron McCormack ≝ http://mcc.id.au/

Reply | Threaded
Open this post in threaded view
|

Re: In-sentence bib references with ReSpec

Robin Berjon-2
Hi Cameron,

On Oct 19, 2010, at 00:28 , Cameron McCormack wrote:
> I want some shorthand to generate the citation link.  Something like:
>
>  <p>You really SHOULD read [[#RFC2119]] before throwing MUST around.
>  [[!RFC2119]]
>
> But I’m happy to hear a suggestion on a different shorthand format.

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.

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

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




Reply | Threaded
Open this post in threaded view
|

Re: In-sentence bib references with ReSpec

Cameron McCormack-4
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/

Reply | Threaded
Open this post in threaded view
|

Re: In-sentence bib references with ReSpec

Robin Berjon-2
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/




Reply | Threaded
Open this post in threaded view
|

Re: In-sentence bib references with ReSpec

Cameron McCormack-4
Thanks for the info, Robin.  For the moment I’ve gone back to using my
own XSLT thingo, but I will probably come back to trying ReSpec at some
point.  I’ll start providing patches then, probably. :-)

--
Cameron McCormack ≝ http://mcc.id.au/