Closed pela9 closed 5 years ago
@pela9 apologies for the late response. Indeed it is something that we should allow.
@paolobrasolin would you have time to look into this? Thanks!
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., 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.
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).
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.
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."
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.
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!
Perhaps when asciidoctor-bibtex started out, it was using the square-bracket xrefs.
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.
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.
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 ;)
Let me add, that IMHO this is a dandy bibliography extension. And this (two-line) emendation would make it, well, just terrific!
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.
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),xref
s do not work in footnotes even in vanilla asciidoctor
,asciidoctor
parser, see asciidoctor/asciidoctor#61.At least three solutions exist.
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.
Just released v0.9.2 including this fix.
Many thanks, Paolo and Ronald!
asciidoctor-bibliography don't seem to handle a citation inside a footnote, which is a rather common scenario