Concealed Index Terms on Standalone Lines Causing Vertical Gaps in PDF

[Tristano Ajmone]

• Fix all occurences of concealed index terms in standalone lines.

The presence of concealed index terms on independent lines is causing extra empty lines in the PDF document, which looks hugly (in some cases, where there are multiple Index entries, this creates a huge vertical gap in the page).

The problem only affects the PDF backend, and we need to find a solution.

Possibly, the solution could consist in shifting around the entries from a standalone line to the their context of belonging.

Example (from Chapter 3):

== 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
           | '.'
--------------------------------------------------------------------------------

where I could try to change it in (doesn't work!:

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

The above breaks syntax highlighting!

The only viable solution seems to be removing the empty line before the concealed index term:

== 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]
--------------------------------------------------------------------------------

Once I've found a solution, I should then manually fix all such occurrences in the Alan Manual.

[Tristano Ajmone]

Fixed in Dev Branch

I've managed to fix all the gaps in PR #69 (quite a huge work).

The solution is visually OK, but not ideal — I had to resort to moving the concealed index terms on independent lines from being on the line preceding a BNF source block to being right below the preceding paragraph.

For some reason, this vertical gap problem only affects the PDF via asciidoctor-fopub, and source block elements only.

The problem has to do with the invisible anchor placed in the document to allow jumping from the Index to the entry position. Ultimately, my PR fixed this visually, but the anchor is now at the end of the preceding paragraph and not on top of the actual BNF block — in some rare cases where the BNF rule occurs over a page split, the Index link will point to the end of the previous page.

Not much I can do about it except opening an Issue on the asciidoctor-fopub repo (See: asciidoctor/asciidoctor-fopub#97).

BNF Blocks at Beginning of Sections

Also, note that in case of BNF rules appearing at the start of a section (i.e. after a heading), I had to either:

• move the BNF after the first text paragraph (if the context allowed it)
• add a line of text like ("Syntax:") above it.

This is because the anchor can't be attached to a heading either, so it would create a huger gap.

Also, it's a bad idea to start a section with a code block, because headings have extra space after them, and code blocks have extra space before them, so together they already add a visual gap because of the template styles.

Overall, I think that it's better to have a section begin with some text that summarized the element being discussed, and then have the BNF follow. Otherwise, the BNF is more "cryptic" until the read has a vague idea of what it does.