Re: ReSpec and references

Hey,

sorry for not answering earlier, I've been on vacation!

On Jul 28, 2010, at 21:28 , Shane McCarron wrote:
> Sadly, this is not the way ReSpec does it - and it is not super easy to change ReSpec to do it this way.  I also think it is stupid, but I think lots of the pubrules are stupid...

Now now, that's not quite the spirit ;-) This doesn't read like a pubrule to me, it's just from the manual of style. I tend to think that that's open to reasonable interpretation — what isn't is checked by the tools (and hopefully that part isn't stupid).

In this case I don't see this as a strong requirement. First, editors will often spontaneously make the first mention of a reference properly expanded. Second, they will know better what "first mention" is, whether it's the one in the abstract or the one in the intro or both, whether to reintroduce it in the 77th subsection of the 42nd section, etc. Thirdly, a number of such references are self-explicit (e.g. [XML]). Finally, there's a link *right there* to the reference section that has the full name and the link. I'd say we're good.

> Anyway, What I was wondering is if there is a way to extend the current reference architecture so that it could magically do the text leading up to the reference AND the reference itself - wrapping them in the silly cite and a elements, inserting abbr elements as needed.  My first thought was to do something like this:
> 
> [[[lead in reference string]REFERENCE]] - that would be backward compatible so existing specs wouldn't change and we wouldn't need to change the bibliography file.  On the other hand, it would not magically deal with abbreviations...

I'd like to avoid that if at all possible. The point of picking an HTML-based format with a limited set of shortcuts was to avoid the wiki-language conundrum of simplifying things to the point where you've invented a syntax that makes the raw HTML look good.

> Another idea was that we just continue to use [[REFERENCE]], but allow an extension to the biblio file that, if present, would supply the lead-in text, the reference, and any necessary abbreviations.  This would require changes to any spec that used ReSpec and used references that were so annotated though.  That seems like a bad idea.

Yup, breaking existing content bad :)

> Finally, I considered some more subtle extension combined with changing the biblio file.  Like [[@REFERENCE]] would mean insert a reference and the standard lead-in for it.  [[REFERENCE]] would work as it always had, albeit also adding the surrounding <cite> element.

Adding the <cite> is fine (I see you've done that, great!). I'm in favour of [[@REFERENCE]] if someone wants to pick it up, but I don't consider it high priority enough to put in the work myself.

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

Received on Tuesday, 17 August 2010 13:38:34 UTC