Block titles should be interpolated consistently

[mojavelinux]

Block titles should be interpolated at a consistent time during the parsing phase. We need to decide when exactly this should happen (and the consequences of doing so).

Normally, a block title (defined using the dot shorthand) is interpolated lazily (on first reference). Under certain circumstances, the title is interpolated sooner than expected. One of these conditions is when the block has an id. When the id of the block is stored in the references table, the title is interpolated (for example, https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/parser.rb#L933). This produces strange side effects when using counters (and other features that affect document state) in block titles, as reported in issue #1286.

[mojavelinux]

Note that the workaround is to force eager interpolation of the title using the explicit attribute syntax with a single-quoted value.

[title='SRS-{counter:srs}']
content

[mojavelinux]

Please note that in 2.0, some steps were taken to mitigate this problem by storing the node in the refs table instead of the converted title (and the converted title is no longer stored directly).

Now the only problem is with ID generation. Since IDs are generated from the converted title, it's necessary to convert the title eagerly. Changing this behavior would be a rather fundamental change in AsciiDoc.

[arosien]

Extra info: using asciidoctor 2.0.10, block titles with counters render correctly when producing HTML, but render incorrectly when producing pdf via asciidoctor-pdf. The stated workaround fixes the problem when producing pdfs.

[mojavelinux]

The PDF problem will be mostly mitigated in Asciidoctor PDF 2, which will no longer dry run the content unless the unbreakable option is set on the block. This will solve ~90% of the cases.