Support cites in footnotes, via double-angle-bracket xref format

[andrewcarver]

Issue #78 asks for asciidoctor-bibliography to work with cites in footnotes. Given Asciidoctor's current functionality, and given this extension's architecture as a Preprocessor, working correctly with cites in footnotes will be problematic so long as the extension uses the square-bracketed, xref:targetID[citation-text] form of xrefs.

The double-angle-bracketed, <<targetID,citation-text>> form of xref is the form that asciidoctor-bibtex uses; which is why the latter extension handles cites in footnotes. I have not found any impairment of functionality, or other disadvantage whatsoever to changing asciidoctor-bibliography to do likewise. This would resolve Issue #78.

[andrewcarver]

Hmm... I see(from Travis-ci) that the "comma-escaping" part of my new method is being used for formatted_citations in some ways I didn't expect... it works correctly, I believe, for creating xrefs, since the comma in those (double-angle-bracketed) xrefs is a metacharacter. But it's being used in contexts in which comma is NOT a metacharacter... which I didn't expect :-/ Any immediate suggestions?

[andrewcarver]

I think the method that my new one replaced, Citation#escape_brackets_inside_xref!, "escaped" this problem (no pun intended) by not doing ANYTHING (including escaping ]) except where it detected {{{ and }}} had been inserted into the formatted_citation. My method neglected to check that, before escaping commas. I'll attempt to remedy that oversight, and see if that helps...

[andrewcarver]

Well, that didn't help the problem, so far as I can see.

But I'm beginning to think that this Travis-CI test is just "set up to fail", on this different form of xref. That is, it's simply not taking into account that in this kind of xref, between << and >> comma is a metacharacter (separating id from citation-text)--so, we must escape non-meta-commas!!!

Would you not agree with that evaluation?

[andrewcarver]

WOOPS-- I know I saw the commas being escaped in someone else's xrefs--I think it must have been the stuff asciidoctor-bibtex was doing--but, trying it just now WITHOUT such escaping, it works OK!! Let's see how Travis-CI likes that approach!

[andrewcarver]

AH! Travis-CI likes that a LOT better: it found only 2 "errors". But in effect, they both just said, "Hey, you didn't do what we expected--we expected square-bracketed xrefs, but you gave us angle-bracketed!!" (Which was what I was TRYING to do!!)

expected: "(xref:bibliography-default-Erdos65[foo Erdős, Heyting, & Brouwer, 1965 bar])" got: "(<<bibliography-default-Erdos65,foo Erdős, Heyting, & Brouwer, 1965 bar>>)"

expected: "(xref:bibliography-default-Einstein35[Einstein, Podolsky, & Rosen, 1935, pp. 41-43]; xref:bibliography-default-Erdos65[seeErdős, Heyting, & Brouwer, 1965])" got: "(<<bibliography-default-Einstein35,Einstein, Podolsky, & Rosen, 1935, pp. 41-43>>; <<bibliography-default-Erdos65,seeErdős, Heyting, & Brouwer, 1965>>)"

[andrewcarver]

You'd need to change your Travis-CI check, as well, then. But that would, I expect, involve about the same number of lines changed! (2 or 3 :D

[ronaldtse]

@andrewcarver really appreciate the PR! @paolobrasolin @opoudjis @nattfodd would you have time to review this? Thanks!

[ronaldtse]

@CAMOBAP795 could you have a look at this? We want to keep the xref:targetID[citation-text,opts] and enable the <<targetID,citation-text,opts>> style of citation.

Basically this fully overrides the original Asciidoctor citation mechanism. (i.e. if you define a reference in * [[[xxx,yyy]]], blah format in Asciidoctor, this gem will not be able to see it.)

[paolobrasolin]

Thanks for your precious work, @andrewcarver.

I'm cleaning up your changes and merging today.