Fix PDF Vertical Gaps

[tajmone]

This commit fixes #65 by removing every vertical space gaps in the PDF Manual due to concealed index terms on independent lines preceding a BNF code block (as well as other encountered gaps too).

In some section that began with a BNF rule, in order to avoid the vertical gap I had to either:

• Move down the BNF rule after the first text paragraph.
• Add a short paragraph (eg: "Syntax:") before the BNF rule.

---

Before merging:

• [ ] Wait that PR #67 is merged into Beta7-prep.
• [ ] Fix revnumber and revdate accordingly.
• [ ] Squash together into a single commit any further changes.

After merging:

• [ ] Delete branch beta7-prep-PDF-gaps.

---

Live Preview links

These links point to the beta7-prep-PDF-gaps branch, and will work even after force-pushing to the PR:

• HTML Manual
• PDF Manual

[tajmone]

@thoni56, here's the full list of the vertical gaps fixed in the document:

• §3.1. An Adventure: adventure, declaration, start_section.
• §3.2. Options: option.
• §3.4. IMPORT: import.
• §3.5. Classes: class.
• §3.5.1. Inheritance: inheritance.
• §3.6. Instances: instance.
• §3.7. Properties: property.
• §3.7.2. Initial Location: initial_location.
• §3.7.3. NAMEs: name.
• §3.7.4. PRONOUNs: pronouns.
• §3.7.5. Attributes: is, attribute_declaration.
• §3.7.6. INITIALIZE: initialize.
• §3.7.7. DESCRIPTION: description (statement), description (checks).
• §3.7.8. Articles and Forms: forms, mentioned.
• §3.7.9. CONTAINER: container_properties, limits, header, extract.
• §3.7.11. ENTERED: entered.
• §3.7.12. EXITs: exit.
• §3.7.13. SCRIPTs: script, step.
• §3.8. Additions: addition.
• §3.9. SYNTAX Definitions: syntaxes.
• §3.9.1. Indicators: indicator.
• §3.9.2. Parameter Restrictions: parameter_restrictions.
• §3.10. VERBs: verb.
• §3.10.3. Verb CHECKs: verb.
• §3.10.4. DOES Clause: does.
• §3.10.5. Verb Alternatives: verb_alternatives.
• §3.10.6. Verb Qualification: qualifier.
• §3.12. Rules: rule.
• §3.13. SYNONYMS: synonyms.
• §3.14. MESSAGEs: messages.
• §3.15. PROMPT Section: prompt.
• §3.16. START Section: start_section.
• §3.17. Statements: (string), style_statement, (DESCRIBE), (SAY), (LIST), (SHOW), (PLAY), (LOCATE), empty_statement, strip_statement, event_statement, cancel_statement, make_statement, increase_statement, set_statement, include_statement, exclude_statement, if_statement, depend_statement, use_statement, stop_statement, repetition_statement, score_statement, visits_statement.
• §3.18. WHERE Specifications: where.
• §3.19. WHAT Specifications: what.
• §3.20. Expressions: attribute_reference, expression, (RANDOM), (Logical), (Class), (what), transitivity, aggregate_expression, filters.
• §4.2. Words, Identifiers and Names: identifier, id (Quoted Identifiers).
• §4.3. Numbers: number.
• §4.4. Strings: string.
• §4.5. Filenames: import.
• §D.1. Description: adventure.

A FEW NOTES:

• All section numbers refer to the HTML doc, for there's currently a difference in numbering between HTML and PDF versions of the Manual.
• In some section that began with a BNF rule, in order to avoid the vertical gap I had to either:
  • Move down the BNF rule after the first text paragraph:
  • §3.5. Classes
  • §3.10. VERBs
  • §3.17.1. Output Statements:
    • LOCATE Statement
    • EMPTY Statement
    • STRIP Statement
    • CANCEL Statement
    • MAKE Statement
    • SET Statement
    • INCLUDE Statement
    • EXCLUDE Statement
    • IF Statement
    • DEPENDING ON Statement
    • USE Statement
    • STOP Statement
    • TRANSCRIPT Statement
  • §3.20. Expressions:
    • Attribute References
    • Class Expressions
    • The Whereabouts of an Entity
    • Aggregates
    • Filters
  • Add a short paragraph (eg: "Syntax:") before the BNF rule:
  • §3.7.8. Articles and Forms
  • §3.7.9. HEADER and ELSE
  • §3.7.11. ENTERED
  • §3.10.3. Verb CHECKs
  • §3.10.4. DOES Clause
  • §3.10.5. Verb Alternatives
  • §3.10.6. Verb Qualification
  • §3.12. Rules
  • §3.13. SYNONYMS
  • §3.17.1. Output Statements:
    • String Statement
    • STYLE Statement
    • DESCRIBE Statement
    • SAY Statement
    • LIST Statement
    • SHOW Statement
    • PLAY Statement
    • INCREASE and DECREASE Statements

[tajmone]

@thoni56,

you might want to look at the sections listed above after:

• Add a short paragraph (eg: "Syntax:") before the BNF rule:

I've explained in #65 why I needed to do that. I didn't want to alter the text dramatically, so I've just added "Syntax:" when I couldn't swap the BNF with the first paragraph.

This allows for easy substitution, in case you don't like it — and maybe prefer something like "Grammar rule:", or otherwise.

In any case, we can always polish the text later, but right now I wanted to get rid of those horrible vertical gaps in the PDF (they were quite huge and visible).

Also, I think that syntax element sections should always start with a brief sentence describing the purpose and use of the element, immediately followed by its BNF grammar, and then all further explanations and examples.

[thoni56]

Is there a way for me to get at a PDF with this change without building it?

I should probably set up the toolchain anyway, but I thought to give quick feedback.

I don't have any general objections except that if there is this type of "restrictions" it will be hard to remember, e.g. that grammar rules section need to have a paragraph before it. (I like when we can fix so that the problem can't happen again, but I know that is your ambition too!)

[tajmone]

Is there a way for me to get at a PDF with this change without building it?

Yes, I could rebuild the PDF and amend the PR, but .... I fear this might disrupt the current status of things due to Asciidoctor having been updated since these PRs, which would introduce further conflicts.

You can peek at the Live HTML preview of the Manual, as per this PR status, at this link:

• https://htmlpreview.github.io/?https://github.com/alan-if/alan-docs/blob/8ee4f4547a7cf90d2df4664429a29435e9c496d4/manual/manual.html

but this won't show the changes in the PDF (which is what this PR addresses).

We should wait for the branch conflicts to be solved first, to avoid further messing the conflicts status. Also, this PR can't be merged until PR #67 is merged (don't remember why).

I'll try to build a PDF preview of this and send it to you via email, tonight.

[tajmone]

PDF Live Preview

The PR actually does contain a PDF preview of the document (forgot about it):

• https://github.com/alan-if/alan-docs/blob/8ee4f4547a7cf90d2df4664429a29435e9c496d4/manual/manual.pdf

Although it's not the best of Git practices to include built documents (HTML, PDF, etc.) in the actual commits, I did always include them to simplify previewing the results and discussing them without having to rebuild the whole thing (unfortunately, the toolchain is still a bit complex to set-up, and dependencies might get updated often).

[tajmone]

Great! I'll have to wait for PR #67 to be merged before merging this one, and also handle the various tasks mentioned at the top.

[tajmone]

PR Manually Merged

Due to the problems with the PR info not being updated after the force push, I've opted to manually merge the PR branch and close this PR.

The issue of GH not updating is a known problem, so in this case I deemed it safer to drop the PR procedure.