Asciidoctor :: Discussion

Footnotes and cross references in Asciidoctor 0.1.4

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

3 messages Options

rwinch

Oct 01, 2013; 11:04pm

Footnotes and cross references in Asciidoctor 0.1.4

I'm using Asciidoctor 0.1.4 and am having difficulty figuring out the syntax to support footnotes with cross references. For example the following sample does not render a link within the footnote:

= Footnotes and cross references

Footnotes don't appear to render cross references.footnote:[This footnote doesn't render the link <<more-info>>.] This works though <<more-info>>.

= More Info

Any help is appreciated!

Thanks,
Rob

mojavelinux

Oct 05, 2013; 12:48am

Re: Footnotes and cross references in Asciidoctor 0.1.4

Administrator

Rob,

You've uncovered an inconsistency between AsciiDoc and Asciidoctor. Although both implementations process macros in the same order, the way Asciidoctor handles footnotes introduces a variation.

AsciiDoc Python only partially processes footnotes. It wraps the footnote text, but otherwise leaves it in place. The remainder of the work is performed by JavaScript when the page loads. Since the text remains in place, it is subject to subsequent macro processing, which includes cross references.

Asciidoctor, in contrast, processes footnotes entirely. When it finds a footnote, it extracts the text from the flow of the document, preventing it from being further processed. Since the cross reference macro processing happens after footnote processing, the cross references don't get interpreted.

I've filed an issue so that, one way or another, the cross references in a footnote are processed: https://github.com/asciidoctor/asciidoctor/issues/676

Fortunately, there is a workaround for this problem. In almost all cases like this, an inline pass macro gives you the control you need to force processing of text. Here's how you would use the pass macro in the example you gave:

```asciidoc

= Footnotes and cross references

Footnotes render cross references if they are inside a pass macro.footnote:[This footnote renders the link pass:specialcharacters,macros[<<more-info>>].] This works as well, <<more-info>>.

= More Info

more info content

```

You don't need to escape the closing square bracket at the end of the pass macro since pass macros are processed before any other macros. By the time footnotes are processed, this is what Asciidoctor sees:

....

footnote:[This footnote renders the link \e0\e.]

....

[TIP]

Asciidoctor 1.5.0, you'll be able to use the substitution name shorthands to make the pass macro less verbose:

```asciidoc

footnote:[This footnote renders the link pass:s,m[<<more-info>>].]

```

That certainly looks a lot more reasonable.

Hopefully that allows you move forward!

-Dan

On Tue, Oct 1, 2013 at 5:04 PM, rwinch [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'm using Asciidoctor 0.1.4 and am having difficulty figuring out the syntax to support footnotes with cross references. For example the following sample does not render a link within the footnote:

= Footnotes and cross references

Footnotes don't appear to render cross references.footnote:[This footnote doesn't render the link <<more-info>>.] This works though <<more-info>>.

= More Info

Any help is appreciated!

Thanks,
Rob

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Footnotes-and-cross-references-in-Asciidoctor-0-1-4-tp671.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | http://google.com/profiles/dan.j.allen

rajsingh

Feb 16, 2014; 4:00am

Re: Footnotes and cross references in Asciidoctor 0.1.4

This isn't working for me. See:
http://www.geopackage.org/spec/#_footnote_1

I want to put a link to http://www.geopackage.org/spec/#B25 in footnote 1.
I've tried all of these and nothing gives me the right result.

The first 16 bytes of a GeoPackage SHALL contain “SQLite format 3” {req1_foot1} in ASCII <<B4>>.

:req1_foot1: footnote:[SQLite version 4 pass:specialcharacters,macros[<<B25>>], which will be an alternative to version 3, not a replacement thereof, was not available when this specification was written. See Future Work clause in Annex B.]

:req1_foot1: footnote:[SQLite version 4 $$B25$$, which will be an alternative to version 3, not a replacement thereof, was not available when this specification was written. See Future Work clause in Annex B.]

:req1_foot1: footnote:[SQLite version 4 <<B25>> (reference B25), which will be an alternative to version 3, not a replacement thereof, was not available when this specification was written. See Future Work clause in Annex B.]

Help!?!?!