citation in footnote

[pela9]

The extension don't seem to handle citations inside footnotes or table cells.

[0xDiddi]

I am using the (as of now) latest gem of asciidoctor-bibtex and asciidoctor v1.5.8, and am exporting to docbook.

Putting a citation inside a footnote works fine, meaning the following asciidoc produces the expected docbook output:

:bibtex-style: apa
aaaa footnote:[cite:[Author123]] aaa.

<simpara>
    aaaa
    <footnote>
        <simpara>
            <link linkend="Author123">Author (Year)</link>
        </simpara>
    </footnote>
    aaa.
</simpara>

---

As this seemed ugly to write, I created an inline macro as a shorthand to this combination.

Asciidoctor::Extensions.register do
  inline_macro :citef do
    using_format :short
    process do |parent, target, attrs|
        "footnote:[cite:[#{target}]]"
    end
  end
end

But using it, the nested cite macro is not being processed.

aaaa citef:[Lane12a] aaa.

<simpara>
    aaaa
    <footnote>
        <simpara>cite:[Author123</simpara>
    </footnote>
    ] aaa.
</simpara>

---

I'm not sure though if this is an issue with asciidoctor-bibtex or something with asciidoctor itself (maybe execution order of extensions?).

[pela9]

I think your example works because the citation is last in the footnote. When writing something like
footnote:[Some text cite:[Miller98], some more text] I get the result that the inner ']' ends the footnote and that "some more text" is left in the outside text. (I have only tested with the iee csl style.)

[0xDiddi]

I just tried that, and this:

aaaa footnote:[sdfdfdfd cite:[Author123] sdfdsfsdf] aaaa.

produces the following docbook:

<simpara>
    aaaa
    <footnote>
        <simpara>
            sdfdfdfd (
            <link linkend="Author123">Author&#44; Year</link>
            ) sdfdsfsdf
        </simpara>
    </footnote>
    aaaa.
</simpara>

However when using my shorthand macro, the effect remains the same as before, similar to what you described.

[pela9]

I can confirm that it works when using the apa style, but switching to
:bibtex-style: ieee
causes the behaviour I described earlier. So my analysis was wrong, it is probably inserted square brackets from the ieee-style ('[N]') that confuses asciidoctor and causes the footnote to be prematurely ended.

[0xDiddi]

So combining all this:

• Inline macros act on the plain input and do simple text replacing
• They are executed seemingly in arbitrary order
• Asciidoctor handles nested macros, but doesn't seem to run multiple passes

I have some ideas that may help here:

• (I thought about specifying execution order but see next point instead)
• Do bracket counting for macros. This would avoid the closing bracket of the ieee citation being counted as the close for the footnote
  • EDIT: watch out when to count here, don't count them before processing the inner macro and then close after the Nth bracket afterwards without accounting for changes in the content
• allow macros to request multiple passes
  • making it opt-in as to not break existing stuff
  • allows macros to insert other macros and have them processed
  • either request a single pass, or repeat passes until no more macros are being replaced

Lastly it seems that this is an issue in core asciidoctor and not in the bibtex extension. I'll have a look around their repo and see if they already have a similar issue and if not create one.

[pela9]

Yes, I agree with your analyses. Thanks, for helping to pin this done. And I would be grateful if you can pass this information to the asciidoctor issue list.

[rockyallen]

cite: does not work for me in table cells- the cite:[REF1] is not processed and appears unmodified in the output. Is this a different problem?

[0xDiddi]

@rockyallen That's different. The issue here was with inline macros within inline macros, whereas tables are blocks, and thus processed differently.

I just reproduced your error though, and can add that other inline macros (I tested links) work inside table cells, so it seems that one is on asciidoctor-bibtex.

But notable: most blocks in asciidoctor can be reproduced by annotating an open block, only pass-through and table blocks can not.
This leads me to believe that they are handled specially within asciidoctor, so there may be something going on there as well that causes this.

EDIT: I just tested my own inline macro inside a table, and (apart from the error above) it is being processed and produces output. So I conclude that tables generally process all inline macros, not just built-in ones.

[0xDiddi]

I just opened an issue in asciidoctor core that addresses this.

Some corrections I found while testing further:

• inline macros apparently do count brackets, but only for other macros, not for brackets that aren't part of macros
  • I guess as of now, this is justified as asciidoctor expects closing square brackets inside macros to be escaped
• there are multiple passes for inline macros, making an inline macro that inserts a link inside a footnote works just fine
  • My urge here is to blame execution order. Inserting a footnote with a link (both builtin macros) works fine, while inserting a footnote with any custom inline macro sees the footnote close with the bracket that is supposed to close the nested macro
    • I'm not opening an issue for this just yet, I assume it'll start working when the above issue is fixed

[0xDiddi]

As my issue in asciidoctor core still sits unacknowledged, and I can't stand doing nothing, I started experimenting around a bit.

Cutting straight to the point: while the cite macro looks like an inline macro, it is not. As this line in the asciidoctor-bibtex source shows, it is in fact a Tree Processor. That means that it is handled once parsing is complete, which is at some point before inline macros are processed; aka as it stands, there is no way for my code to work.

I'm not sure why this is handled this way, as the readme specifically states that

asciidoc-bib failed to follow the grammar of macros in asciidoc, thus to avoid breaking existing documents, a fork is inevitable.

Now while asciidoctor-bibtex follows the grammar of macros, the processing appears to be the old preprocessor, just wearing a trenchcoat and pretending to be a macro.

Taking a quick look over the code, it doesn't seem too hard to make it an inline macro, and in parts may even be more concise.

This then also warrants a separate issue in this repo, which I'll open in the next couple of days.

[0xDiddi]

Now while asciidoctor-bibtex follows the grammar of macros, the processing appears to be the old preprocessor, just wearing a trenchcoat and pretending to be a macro.

Let me tell you: this rabbit hole is deep. I just tried to make the cite macro an actual macro and was stopped dead in my tracks before I even really got started.

The problem here is order of execution again.

Picture the requirement: firstly, process citations, filling them in and aggregating the sources, then afterwards put the collected sources in the bibliography section.

Now look at the available asciidoctor extension points (in order of execution):

1. preprocessor (this works on the plain text before parsing)
2. block macro (does things like the bibliography)
3. block processor (this does custom block styles)
4. tree processor (works on the AST after parsing)
5. inline macros (this does text replacing for inline macros)
6. postprocessor (handles output document in backend-specific format)

Looking at this, it becomes clear why asciidoctor-bibtex is written the way it is, and that there is no easy way to solve my problems via this route.

Another thought: that order makes perfect sense from a theoretical standpoint, but it is hard to believe that in the 7 years that asciidoctor has existed, nobody ever needed to use information from inline macros in the creation of a block macro or something like this.

[mojavelinux]

I just tried to make the cite macro an actual macro and was stopped dead in my tracks before I even really got started.

The problem you're running into is that inline elements don't get processed until the conversion phase, which is streaming. This is covered by asciidoctor/asciidoctor#61. Solving this issue has a lot of consequences, so addressing it is something that has taken a lot longer than excepted.

[ProgramFan]

The macro is processed correctly but the brackets inserted disrupt the footnote inline macro.