Concealed Index Terms Causing Vertical Gaps in PDF

[tajmone]

Problem Description

The presence of concealed index terms on independent lines above source code blocks is causing extra empty lines in the final PDF document, which look ugly (in some cases, where there are multiple Index entries, each on its own line, this creates a huge vertical gap in the page).

This problem only affects PDF documents created via DocBook backend + asciidocto-fopub, and it only seems to affect code listings and section titles (but could affect other elements too).

I'm not sure if the problem is on the DocBook side or on asciidocto-fopub, but I thought this would be a good place to create an issue for it.

Expected Solution

The asciidoctor-fopub toolchain should be able to better handle anchors of this type, avoiding empty lines in the final document which break up the intended spacing of document elements.

Real Case Example

This is taken from a real Asciidoctor project:

• source: manual_03.asciidoc
• PDF output: manual.pdf

For more details, see alan-if/alan-docs#65.

Here you can see the concealed index terms preceding the [source,bnf] block:

== SYNTAX Definitions

The (((SYNTAX, construct))) `Syntax` construct is used to specify the allowed structure of the player's input.
Each definition defines the syntax for one `Verb`.
The effects triggered by the player input are declared using the `Verb` construct (see <<VERBs>>).

(((BNF, rules of, SYNTAX)))
[source,bnf]
--------------------------------------------------------------------------------
syntaxes = 'SYNTAX' {syntax}

syntax = id '=' {element} syntax_end

element = id
        | '(' id ')' [indicator]

syntax_end = parameter_restrictions
           | '.'
--------------------------------------------------------------------------------

In the final PDF there's a vertical gap, possibly due to the way the anchor is generated.

Workaround Solution

The only viable workaround seems to be appending the concealed index term right below the preceding paragraph, and then leave an empty line after it:

== SYNTAX Definitions

The (((SYNTAX, construct))) `Syntax` construct is used to specify the allowed structure of the player's input.
Each definition defines the syntax for one `Verb`.
The effects triggered by the player input are declared using the `Verb` construct (see <<VERBs>>).
(((BNF, rules of, SYNTAX)))

[source,bnf]
--------------------------------------------------------------------------------

This fixes the gap, but the anchor is now on the preceding paragraph, not the code block — and, in those rare cases where the page splits between the two, the Index link will point the paragraph page, not the expected code block!

Also, separating the Index entries from the elements they belong to is far from ideal, for it's easy to overlook them and add new text between the entry and the intended indexed item, at the risk of creating Index entries pointing to the wrong text.

[mojavelinux]

Index terms directly above a listing block are not associated with that listing block. Instead, they are creating a separate paragraph. AsciiDoc doesn't currently support the syntax you are looking for. You would have to associate the index terms with either the title of the listing block or the previous paragraph.