citation in footnote

[pela9]

asciidoctor-bibliography don't seem to handle a citation inside a footnote, which is a rather common scenario

[ronaldtse]

@pela9 apologies for the late response. Indeed it is something that we should allow.

@paolobrasolin would you have time to look into this? Thanks!

[andrewcarver]

I've found a workaround. The problem arises because having inline macros of the standard form (e.g., xref:Anderson98[Anderson & Lebiere, 1998] inside footnotes gives Asciidoctor difficulties: nesting of square brackets seems to be a parsing challenge (or something). This is the form of xref asciidoctor-bibliography uses, though, to establish the citations' links to the bibliography.

asciidoctor-bibtex had no trouble when citations were in footnotes; that's because it used the double-angle-bracket form of xref instead (e.g., <<Anderson04,Anderson et al.&#44; 2004>>). Asciidoctor has no parsing-difficulties when it finds this kind in footnotes, because it introduces no square brackets.

I've just finished writing and testing (somewhat) a patch of asciidoctor-bibliography that uses this double-angle-bracket form of the citation xrefs. On my test-file, it worked beautifully: It also did something that asciidoctor-bibtex could NOT do, which is support citations in quote-attributions in a quote-block style attribute-list (see User Manual https://asciidoctor.org/docs/user-manual/#quote ).

The question is, then, whether there is any reason not to use this double-angle-bracket form of xrefs: is there some situation(s) in which it is not as robust as the style that uses square brackets?

It actually takes very little code change to do this (all in citation.rb). I could set up a PR if you're interested in testing it.

[pela9]

Some more notes:

Asciidoctor can handle nested builltin inline macros, but it seems that asciidoctor-bibliography (and asciidoctor-bibtex) can't handle a nested cite:[...] macro inside another, e.g.

footnote:[abc cite:[KEY] def] is parsed as: "footnote:[abc cite:[KEY]" + "def]"

(I actually use asciidoctor-bibtex and found initially the same problem there, which I have reported also on its issue list. I use asciidoctor for translation to docbook only, haven't checked if there is the same problem with other output formats).

[andrewcarver]

Yes, good point. Asciidoctor does fine with nested square brackets when it's from an inline macro it recognizes and processes. The cite:[] "macro" though, is a cow from someone else's field. Not seeing it as a macro, Asciidoctor figures the footnote has ended, once it sees the first ]. Thus the parsing-anomalies.

[andrewcarver]

Actually that's a bit over-simplified: When asciidoctor-bibliography is in use, Asciidoctor never has to parse a cite:[] "macro", because the extension has actually replaced all those--with Asciidoctor xref macros--by the time Asciidoctor starts parsing. However, as mentioned, asciidoctor-bibliography is replacing the cite:[] "macros" with xref:target[] macros--which end with square brackets too. When Asciidoctor sees that ], it says, "End of footnote."

[andrewcarver]

I'm not really sure, though, why that should be: Asciidoctor should, it seems, be able to parse the square-bracket version of the xref macro, since as you say, it can handle others OK. All I know is that it likes the double-angle-bracket form much better, inside footnotes.

[andrewcarver]

The only way you can get one of the square-bracket xrefs to work inside a footnote, is to escape the closing square-bracket:

xref:bibliography-default-Anderson98[Anderson & Lebiere, 1998\]

That works fine in a footnote in Asciidoctor. But of course, a bibliography extension cannot do that all the time, because outside of a footnote (or another macro?) the xref doesn't work at all!

[andrewcarver]

Perhaps when asciidoctor-bibtex started out, it was using the square-bracket xrefs.

[andrewcarver]

And you are correct that in the DocBook conversion, a non-escaped-end-bracket xref:targetID[citation-text] in a footnote will get parsed as a link--but its closing square bracket and the rest of the footnote (including the created </link> endtag) get pushed out of the footnote. However, it's even worse with the HTML conversion: there, the xref doesn't get processed at all, but remains in its current form--except that those same bits get pushed out of the footnote.

[andrewcarver]

You can see my initial offering, in PR #81. There's an issue Travis-CI uncovered which I've followed up with a comment, and will look into further.

[andrewcarver]

Travis-CI has, now, no substantive complaint in PR #81: only two "errors", both amounting to, "We expected the square-bracketed xrefs, and you gave us angle-bracketed instead!!" But that's the whole point of the exercise ;)

[andrewcarver]

Let me add, that IMHO this is a dandy bibliography extension. And this (two-line) emendation would make it, well, just terrific!

[thom4parisot]

Another workaround I found is referencing the citation to make it appear in the bibliography and to reference it via an xref link to display it properly in the footnote:

:dumb_variable: cite[kent_beck_manifesto_2001]

Bla footnote:[Agile Manifesto (<<bibliography-default-kent_beck_manifesto_2001, Beck and al., 2001>>)] blah.

[paolobrasolin]

Thanks everybody for your initiative and thoughtful inputs.

I'm gonna recap the situation:

• asciidoctor-bibliography citations do not work in footnotes (thanks @pela9 for reporting this),
• this is caused by the fact that xrefs do not work in footnotes even in vanilla asciidoctor,
• which in turn is caused by a non-trivial problem with the asciidoctor parser, see Parse inline markup during the parse phase (use recursive descent parser) asciidoctor/asciidoctor#61.

At least three solutions exist.

1. Quoting the closing bracket of the citation macro within the footnote as suggested in Issue with square brackets within inline macro asciidoctor/asciidoctor#3251 (comment); this is too disruptive and needs much smarter parsing to work, as already stated.
2. Citing a key, tossing it away and manually writing the citation text as shown by @oncletom above; this is useful, but just as a manual workaround.
3. Letting asciidoctor-bibliography use the double angled bracket form while interpolating the cross-references as suggested by @andrewcarver. This is the winner IMO: it's using proper features of vanilla asciidoctor and after some testing I see no evidence of failure.

I'll clean up @andrewcarver's #81 (which implements 3) and merge it.

[paolobrasolin]

Just released v0.9.2 including this fix.

[andrewcarver]

Many thanks, Paolo and Ronald!