Fix PDF Vertical Gaps #69

tajmone · 2019-09-11T12:38:33Z

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 App G. Localization #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:

Finally confirmed that asciidoctor-fopub now works correctly with Java versions >= 8 (gradle error fixed). Now the project switches to using Java JDK 12. - Add note about switching to Java 12. - Update alan-xsl-fopub documentation. - Update the submodule pointer to alan-xsl-fopub. For more info, see: - asciidoctor/asciidoctor-fopub#87 - asciidoctor/asciidoctor-fopub#88

Add link to new ALAN repository on GitHub, alongside the Bitbucket link.

In new `writing/` folder add AsciiDoc port of the "Alan Author's Guide" (_The ALAN Adventure Language Author's Guide_), taken from Alan source repository: https://github.com/alan-if/alan/tree/master/doc/manual/writing.odt Document is fully ported, but contents incomplete. It's development moves to this project, replacing its development in the ODT format on the Alan source repository. Closes Issue #48.

Add `.editorconfig` file to enforce ISO-8859-1 on Alan sources and ensure consistent code styling across different editors and IDEs. Also improves Alan sources visualization on GitHub. Form more info, visit: https://editorconfig.org/ Closes #53.

Update all existing Bash and batch build scripts: * Add consistent header info e annotations. * Add public domain note via the Unlicense (where applies). Update all Bash scripts for building PDF docs, and add new ones where missing: * Fix incomplete template path in some script. * Abort if executed under Bash for Windows, due to asciidoctor-fopub not being able to find default template images (e.g. admonitions icons). For more info, See #66.

New `_assets/sh/` folder with reusable Shell/Bash script modules: * `_print-funcs.sh` -- ornamental text color and formatting funcs. Update READMEs accordingly.

Add batch and Bash scripts to update the alan-xsl-fopub Git submodule: * `xsl-alan-fopub-update.bat`/`.sh` These scripts first cd to the submodule directory, force checkout master branch and pull, then also issue a git submodule update command: git submodule update --remote --merge _assets/alan-xsl-fopub This ensures that both the local copy of the repository as well as its submodule pointer are correctly updated. The batch script also rebuilds all PDF documents that rely on the custom XSL template: * `manual/manual.pdf` * `alanguide/alanguide.pdf` * `_dev/styles-tests/styles-preview.pdf` * `_dev/styles-tests/tests-syntax-highlighting.pdf` * `_dev/styles-tests/tests-typography.pdf`

Run `xsl-alan-fopub-update.bat` to update the submodule pointer to the latest version of alan-xsl-fopub, and rebuild all PDF docs. The template update removes URL footnotes for links, which were being added for the benefit of printed documents -- but looked ugly on PDF docs, which provide active click-able links. Fixes #64.

tajmone · 2019-09-11T12:39:54Z

@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 · 2019-09-11T12:53:51Z

@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 · 2020-09-16T10:36:22Z

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 · 2020-09-16T10:44:18Z

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 · 2020-09-16T11:03:40Z

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 · 2020-09-16T19:23:29Z

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.

Add proper configurations to `.editorconfig` and `gitattributes`, and polish all Git settings files (See #72). Add `validate.sh` script to check that all sources meet the new code styles conventions, via the EClint tool (Node.js): https://www.npmjs.com/package/eclint Enable Travis CI validation of code styles consistency in every commit and PR, via the `validate.sh` script.

Update the alan-xsl-fopub submodule to the latest version, which added its own EditorConfig settings to prevent the settings of the Alan-Docs repo to be applied also to the submodule's directory. (See #72)

Amend all markdown files until they pass EditorConfig validation via EClint. (See #72)

Amend all shell and batch scripts to pass EditorConfig validation via EClint. (See #72)

Amend all ALAN source files until they pass EditorConfig validation via EClint. (See #72) Most changes consist in adding an empty line at the file end, especially in the ALAN Guide `lib/` and `mylib/` folders. Note that due to EClint's poor support for Latin1 validation, some ALAN sources containing non-ASCII characters are being excluded from econding validation/enforcement via `charset=unset` (See #73).

Amend two AsciiDoc sources that didn't pass EditorConfig validation via EClint. (See #72)

In view of the upcoming Alan 3.0 beta7 release, we shall do all changes to the Manual in this `beta7-prep` development branch, which we'll then squash into master once beta7 is publicly available. Merge branch `handle_elisions` into `beta7-prep` and resolve conflicts on Chapter 5 source by using "theirs" stategy. (See #40 for a discussion on this)

Moved one level up sub-section of §3.17, *Repetition Statements*, which was wrongly portraided as a subsection of *Actor Statements*. Also, change Manual version to v0.1.91-PreReleaseBeta7, which will be kept as temporary development version until ready to merge into `master` when Alan Beta7 is ready (it will become v0.1.91). From now only the date of the manual should be changed.

In §3.7 *SCRIPTs* add links to USE and STOP statements when mentioned in text; although the subjects are strictly realated they are far apart from each other in the Manual, so cross-reference links are most useful here for the reader. And, viceversa, in §3.17 *Actor Statements* > *USE Statement*, add a link to *SCRIPTs*, to allow reader to easily navigate back & forth between these two closely-related sections.

Fix some cross references that were wrongly cased due to the merge of `handle_elisions` branch which still used to old naming convention for Manual sections. (See #40)

Add new batch `_assets/images/SVG_OPTIMIZE.bat` to optimize all SVG image files using SVGO (Node.js): https://www.npmjs.com/package/svgo Optimize `predefined-classes.svg` (57.6%): 14.896 KiB -> 6.317 KiB

In "§3.8. Additions", remove the `[inheritance]` part from the BNF rule of additions, which was only creating confusion to the reader. See discussion on Alan-IF Yahoo: https://groups.yahoo.com/neo/groups/alan-if/conversations/topics/3809 Closes #46.

In new `xtra-docs/` folder, add the AsciiDoc conversion of the docs found in the `doc/design/` folder of Alan repository. See Issue #48.

* Change folder of `xtra-docs/` to `alan-design/` (see #33). * Update `alan-design/README.md` and better specify the context of these docs. * In main README link to new folder in the "Project Contents" section.

First Glossary draft with an initial entry (*stropping*) and some commented-out pending entries TBD later on (Closes #54). Update contents of "§4.2. Words, Identifiers and Names": * Add "Stropping" sub-section. * Add `stropping` anchor. * Add `stropping` Index entry. * Revise and improve contents of this section: * More examples. * Extra admonitions. * Polish text. Clean-up, polish and update README files in Alan Manual directory. Referenced Issues: #36, #50, #54, asciidoctor/asciidoctor#3248.

In "Appendix F.2. Message Explanations" remove references to error 209 ("First element in a SYNTAX must be a player word.") which is no longer a compiler error. For more info, see: #61 and alan-if/alan@43d21d53.

In various places the word "rule" was formatted as if it was an Alan keyword (i.e. styled as inline code, `Rule`), which it isn't. Amend to it by replacing all occurrences with the word "rule" emphasized (i.e. _rule_) to distinguish it from the general term "rules". Closes #57.

Polish text and add new contents to "App G. Localization": * Provide some general guidelines on how to approach localizing Alan to new languages. * Explain how to exploit *noise* Player-Words and `Synonyms` in i18n to handle articles variations in languages with grammatical gender. * Add "Useful Links" section at the end. * Annotate problems and TODOs (via comments). * Update "G.5. Word Order" (TBD): provide answers to annotated questions regarding the possibility of using `Syntax`es with param in first position. Update TBD admonition note accordingly. (See #61) * Rebuild HTML & PDF Manual. Change document `revremark` to "Beta7 Ed. work".

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.

tajmone · 2020-09-18T13:00:31Z

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.

tajmone added 8 commits July 25, 2019 11:18

Link to GitHub Repo

a071058

Add link to new ALAN repository on GitHub, alongside the Bitbucket link.

Add EditorConfig Settings

f6cfe79

Add `.editorconfig` file to enforce ISO-8859-1 on Alan sources and ensure consistent code styling across different editors and IDEs. Also improves Alan sources visualization on GitHub. Form more info, visit: https://editorconfig.org/ Closes #53.

Add Shell Scripts Assets

43d67b9

New `_assets/sh/` folder with reusable Shell/Bash script modules: * `_print-funcs.sh` -- ornamental text color and formatting funcs. Update READMEs accordingly.

tajmone added 📖 Alan Manual Issues relating to "The Alan Language Manual" 👑 PDF Format Issues with conversion to PDF format ⚠️ important Priority: High 🔨 asciidoctor-fopub Tool: asciidoctor-fopub (PDF toolchain) labels Sep 11, 2019

tajmone added this to the Alan Beta7 milestone Sep 11, 2019

tajmone requested a review from thoni56 September 11, 2019 12:38

tajmone self-assigned this Sep 11, 2019

tajmone added this to To do in Alan Manual Beta7 Release via automation Sep 11, 2019

tajmone mentioned this pull request Sep 11, 2019

Concealed Index Terms on Standalone Lines Causing Vertical Gaps in PDF #65

Closed

1 task

tajmone mentioned this pull request Sep 11, 2019

App G. Localization #67

Closed

thoni56 added 2 commits September 15, 2020 20:41

Correct typo for Java versions

ff02399

Remove references to bitbucket

4c64f96

tajmone mentioned this pull request Sep 16, 2020

Fix Manual Beta7 Dev Branches and PRs #71

Closed

13 tasks

Alan Manual Beta7 Release automation moved this from To do to In progress Sep 16, 2020

thoni56 approved these changes Sep 16, 2020

View reviewed changes

tajmone and others added 19 commits September 18, 2020 00:02

Update Submodule

a94236f

Update the alan-xsl-fopub submodule to the latest version, which added its own EditorConfig settings to prevent the settings of the Alan-Docs repo to be applied also to the submodule's directory. (See #72)

Fix Code Styles: MD Files

cad368f

Amend all markdown files until they pass EditorConfig validation via EClint. (See #72)

Fix Code Styles: Shell Scripts

96c193c

Amend all shell and batch scripts to pass EditorConfig validation via EClint. (See #72)

Fix Code Styles: ADoc Files

6e7adb1

Amend two AsciiDoc sources that didn't pass EditorConfig validation via EClint. (See #72)

Fix Broken XRefs

0b9a6ce

Fix some cross references that were wrongly cased due to the merge of `handle_elisions` branch which still used to old naming convention for Manual sections. (See #40)

SVG Optimization

fec432e

Add new batch `_assets/images/SVG_OPTIMIZE.bat` to optimize all SVG image files using SVGO (Node.js): https://www.npmjs.com/package/svgo Optimize `predefined-classes.svg` (57.6%): 14.896 KiB -> 6.317 KiB

Manual: Fix Additions BNF

81c9ae6

In "§3.8. Additions", remove the `[inheritance]` part from the BNF rule of additions, which was only creating confusion to the reader. See discussion on Alan-IF Yahoo: https://groups.yahoo.com/neo/groups/alan-if/conversations/topics/3809 Closes #46.

Add ALAN Design Docs

9ec953d

In new `xtra-docs/` folder, add the AsciiDoc conversion of the docs found in the `doc/design/` folder of Alan repository. See Issue #48.

Rename Xtra-Docs

6c91a4f

* Change folder of `xtra-docs/` to `alan-design/` (see #33). * Update `alan-design/README.md` and better specify the context of these docs. * In main README link to new folder in the "Project Contents" section.

Update with new unified command line switches

b337966

Remove Error 209

beab8e0

In "Appendix F.2. Message Explanations" remove references to error 209 ("First element in a SYNTAX must be a player word.") which is no longer a compiler error. For more info, see: #61 and alan-if/alan@43d21d53.

tajmone force-pushed the beta7-prep-PDF-gaps branch from 8ee4f45 to 2d906b1 Compare September 18, 2020 12:58

tajmone closed this Sep 18, 2020

Alan Manual Beta7 Release automation moved this from In progress to Done Sep 18, 2020

tajmone deleted the beta7-prep-PDF-gaps branch September 19, 2020 19:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix PDF Vertical Gaps #69

Fix PDF Vertical Gaps #69

tajmone commented Sep 11, 2019 •

edited

Loading

tajmone commented Sep 11, 2019

tajmone commented Sep 11, 2019

thoni56 commented Sep 16, 2020

tajmone commented Sep 16, 2020

tajmone commented Sep 16, 2020 •

edited

Loading

tajmone commented Sep 16, 2020

tajmone commented Sep 18, 2020

Fix PDF Vertical Gaps #69

Fix PDF Vertical Gaps #69

Conversation

tajmone commented Sep 11, 2019 • edited Loading

Live Preview links

tajmone commented Sep 11, 2019

tajmone commented Sep 11, 2019

thoni56 commented Sep 16, 2020

tajmone commented Sep 16, 2020

tajmone commented Sep 16, 2020 • edited Loading

PDF Live Preview

tajmone commented Sep 16, 2020

tajmone commented Sep 18, 2020

PR Manually Merged

tajmone commented Sep 11, 2019 •

edited

Loading

tajmone commented Sep 16, 2020 •

edited

Loading