manual

The Alan Manual

AsciiDoc port of The ALAN Adventure Language Reference Manual.

NOTE — The ALAN Manual has now switched to Rouge for syntax highlighting!

NOTE — The AsciiDoc files in this project are intended for Asciidoctor, the Ruby implementation of AsciiDoc; some required features might not be available in AsciiDoc Python!

---

Table of Contents

• Document Status
  • Beta vs Alpha
• Folder Contents
  • Manual Source Files
    • Transcripts and Compiler Logs Sources
  • Conversion Scripts
  • Helper Files
  • Available Formats
    • PDF Version
    • HTML Version
• Building The Manual
  • System Requirements
    • Installing Ruby on Windows
  • PDF Toolchain Setup
  • HTML Toolchain Setup
• Development
  • Development Cycle
  • Maintainers Check-list
  • Annotated Tasks in Comments
  • Syntax Highlighting
  • Conversion from ODT to AsciiDoc

---

Document Status

The new AsciiDoc port of The ALAN Manual is now the official version of the manual and is publicly available in HTML and PDF format on the repository website:

• https://git.io/alan-docs

Beta vs Alpha

The ALAN Manual is available in two different versions, Beta and Alpha:

• The Beta Manual describes the latest Beta release of the Alan SDK.
• The Alpha Manual includes changes that are only in the development snapshots, which will make it into the next beta release.

Development of the Beta version takes place in master branch, whereas development of the Alpha version takes place in the alan-manual-alpha branch.

---

Folder Contents

The original files of the Alan Manual used for AsciiDoc conversion are available in:

• ../_assets-src/original-docs/
  • manual.odt
  • manual.pdf

Manual Source Files

• manual.asciidoc — The main Alan Manual file that imports all other chapters:
  • manual_00.adoc — Introduction
  • manual_01.adoc — Part I. Concepts
  • manual_02.adoc — Part II. Lexical Definitions
  • manual_03.adoc — Part II. Language Reference
  • manual_04.adoc — Part IV. Running An Adventure
  • manual_05.adoc — Part V. Hints And Tips
  • manual_06.adoc — Part VI. Adventure Construction
  • manual_a.adoc — Appendix A: How To Use The System
  • manual_b.adoc — Appendix B: A Sample Interaction
  • manual_c.adoc — Appendix C: Run-Time Messages
  • manual_d.adoc — Appendix D: Language Grammar
  • manual_e.adoc — Appendix E: Predefined player words
  • manual_f.adoc — Appendix F: Compiler Messages
  • manual_g.adoc — Appendix G: Localization
  • manual_h.adoc — Appendix H: Portability of Games
  • manual_i.adoc — Appendix I: Copying Conditions
  • manual_z.adoc — Glossary

Transcripts and Compiler Logs Sources

In order to auto-generate the compiler output and game transcripts shown in some places of the Manual, some ALAN source adventures are provided. The idea is to ensure that compiler output and code examples transcripts provided in the Manual will always reflect the current status of the Alan compiler and interpreter.

• /src_scripts/:
  • ZILexample.alan — source adventure to recreate original compiler log of F.1.
  • ZILexample.bat — batch to update compiler log.
  • ZILexample.log — Compiler log shown in "F.1. Format of messages".

Currently, the output of those scripts is manually pasted into the Manual AsciiDoc sources. For more info, see:

• /src_scripts/README.md.

Conversion Scripts

Under Windows:

• PDF_BUILD.bat — batch script to create manual.pdf document (currently ignored in repository).

Bash scripts for Linux, macOS or Bash for Windows:

• html_build.sh — bash script to create manual.html document (single file document).
• pdf_build.sh — bash script to create manual.pdf document (currently ignored in repository).

PDF CONVERSION NOTE — The PDF_BUILD.bat script now uses asciidoctor-fopub to create the PDF version of the Manual. You'll need to setup it up on your machine and add it to your system Path in order to run the conversion script.

See: Instructions on setting up asciidoctor-fopub.

Helper Files

Some files to help editing the manual:

• Alan_Keywords.txt — Alan keywords list in various formats.
• Cross-References.md — Look-up table for cross-reference links.
• Manual_Index.txt — Manual Index in plaintext (for reference).
• Manual_TOC.txt — Manual TOC in plaintext (for reference).
• RegExs.txt — frequently needed regular expressions for S&R operations.
• SNIPPTES.adoc — useful snippets to copy and paste.

Available Formats

Currently the Alan Manual is available in the following output formats:

• PDF
• HTML — as a single HTML5 document.

In the future more output formats will be supported:

• CHM Help — Can be included in any Windows code editor or IDEs that supports Alan.
• Executable eBook — A standalone .exe file (for Windows) created with an eBook compiler that takes multiple HTML pages and creates a single binary file that can be browsed offline, adding extra features not available in normal browsers.
• Website version — An online version split into multiple chapters might be made available on the Alan Docs website, at some point.

Supporting the above formats will require to split the output HTML document into individual chapters (aka HTML Chunking), instead of a single huge document. Also, the native HTML template used by Asciidoctor needs to be either tweaked or wholly replaced with a custom template.

PDF Version

After running the PDF conversion script, you'll get the following file:

• manual.pdf

The PDF toolchain uses asciidoctor-fopub to convert from DocBook to PDF, and a custom DocBook XSL template.

The DocBook XSL template is now looking good and the output PDF documents are ready for distribution.

The DocBook template and its assets have now been moved to an independent repository so that other Alan projects can use it too:

• https://github.com/alan-if/alan-xsl-fopub

The template is now included in this project via Git submodules, so you'll need to make sure that the submodule is correctly initialized in your local copy of the repository.

For full instructions on how to setup the PDF toolchain and all its dependencies, see:

• https://github.com/alan-if/alan-xsl-fopub#instructions

HTML Version

After running the HTML conversion script, you'll get the following file:

• manual.html

The Manual relies on Asciidoctor's native HTML backend for building the HTML version, so you won't need to install any extra tools beside Asciidoctor, except for some extra Gems required by Asciidoctor.

The generated HTML document is now fully standalone (embedded images and CSS), except for the fonts which are obviously loaded from the Internet at load time (this won't change):

• Google fonts: Open Sans + Noto Serif + Droid Sans Mono
• font-awesome.min.css — Font Awesome CSS stylesheet.

Building The Manual

To convert the Manual yourself, below are some instructions on how to do it, and which dependencies are required.

To build the HTML Manual under any OS, open a Bash terminal in this folder and type:

./html_build.sh

To build the PDF Manual under Windows, open a command prompt in this folder and type:

PDF_BUILD.bat

To build the PDF Manual under Linux or macOS, you'll have to open a Bash terminal in this folder and type:

./pdf_build.sh

System Requirements

In order to build the Manual to any format you'll need to install Ruby and the Asciidoctor gem:

• https://www.ruby-lang.org
• https://asciidoctor.org

Installing Ruby on Windows

Under Windows OS, you can install Ruby two ways:

1. via the Ruby Installer for Windows.
2. via the Chocolatey/Chocolatey GUI package manager, which will simplify installing and updating the Ruby Installer for Windows:
   • Chocolatey — The package manager for Windows.
   • Chocolatey GUI — A nice GUI on top of the Chocolatey command line tool.
   • Chocolatey » Ruby — Ruby package for Chocolatey (installs Ruby Installer for Windows).

The latter solution is the advised way to proceed because (although it requires to first setup Chocholatey and its GUI) it will greatly simplify keeping Ruby and all its dependencies always up to date with a single click.

PDF Toolchain Setup

The PDF toolchain requires asciidoctor-fopub to convert from DocBook to PDF.

The DocBook XSL template is now looking good and the output PDF documents are ready for distribution.

The DocBook template and its assets have now been moved to an independent repository so that other Alan projects can use it too:

• https://github.com/alan-if/alan-xsl-fopub

The template is now included in this project via Git submodules. See the DocBook XSL Stylesheets section for more details.

Once the PDF toolchain is correctly setup, you can then build the PDF document via the following scripts:

• PDF_BUILD.bat — batch script for Windows.
• pdf_build.sh — bash script for Linux and macOS.

HTML Toolchain Setup

The Manual relies on Asciidoctor's native HTML backend for building the HTML version, so you won't need to install any extra tools beside Asciidoctor.

Once Asciidoctor is correctly setup, you can then build the HTML document by using the following scripts:

• html_build.sh — bash script for Linux and macOS.

Development

The Alan Manual is being actively maintained, there's always room for improvements and new contents. If you wish to contribute to its development, read the rest of this document and check the currently pending tasks on the repository Dashboard (issues, milestones and projects):

• Issues » Alan Manual — Issues relating to "The Alan Language Manual".
• Milestones » Alan Manual Improve Contents — Fix and improve current contents of the ALAN Manual.
• Milestones » Appendix G: Localization — Update Appendix G: Localization.
• Project » Alan Manual (dev) — Planning future changes and improvements to the ALAN Manual.

Development Cycle

The Manual in master branch will always represent the latest Alan SDK release (currently, Beta releases), whereas development in the alan-manual-alpha branch reflects the status of the latest Alan development snapshots (i.e. Alpha releases), which will be merged into master branch once the next beta release is ready.

Maintainers Check-list

Whenever a new Alan Beta version is released, before merging the updated Manual into master branch:

• The autogenerated scripts in src_scripts/ should be updated again using the new Alan SDK binaries, and the generated output added to the Manual contents in order for it to reflect the latest SDK.

Annotated Tasks in Comments

I've also annotated in comments various pending tasks as I've encountered during the proofreading stage. These tasks vary from errors which need to be corrected ASAP to improvements and ideas that could be handled sometime in the future.

As a convention, all commented annotations inside document source files will begin with "// @" to allow finding them quickly via Search functionality (eg, "// @TODO:", "// @FIXME:", "// @NOTE", "// @CHECKME", "@IMPROVE", etc.).

In some tasks I've also added either @thoni56 or @tajmone, to indicate the user that should address the issue. As a rule, I've used @tajmone in annotated tasks which I'll need to address at some point in the future, acting as reminders; and I've used @thoni56 for tasks that require Thomas' attention or approval.

Syntax Highlighting

The HTML version uses Rouge for syntax highlighting the code in the Manual, while the PDF version uses XSLTHL (included in asciidoctor-fopub).

Conversion from ODT to AsciiDoc

The original ODT document was first exported to Office Open XML using LibreOffice, and the resulting .docx file was then converted to AsciiDoc using pandoc:

pandoc ^
     -f docx ^
     -t asciidoc ^
    --wrap=none ^
    --atx-headers ^
    --extract-media=extracted-media ^
        manual.docx ^
     -o manual.asciidoc

Although some styles were lost in the process, the final ADoc was a rather good starting point. The single source document was then split into multiple files according to chapters and appendixes.