This repository contains the AsciiDoc sources of the ALAN Documentation published at:
Help and contributions are welcome (see CONTRIBUTING.md).
For a quick overview of the status of the documents in this project, see the STATUS.md document.
SUBMODULES NOTE — This repository contains Git submodules; clone with:
$ git clone --recursive https://github.com/alan-if/alan-docsIf you've already cloned it, update via:
$ git submodule update --init
Table of Contents
- Latest News
- About This Project
- External Links
Some important news for project maintainers and contributors...
Since July 2021, this project support syntax highlighting via Rouge (Ruby).
The new Rouge toolchain uses our own custom Rouge adapter and lexer for ALAN, allowing static highlighting supporting callouts (which Highlight doesn't support). All documents that don't make use of span or highlight marker formatting in highlighted code blocks (a feature currently unsupported with Rouge) are migrating from Highlight or highlight.js to the Rouge toolchain.
Since May 2021, this project uses the new Highlight v4 version.
Since the new major version introduced some changes in the class names in the generated HTML, we've updated all Sass/SCSS sources accordingly, and Highlight v3.x will no longer work correctly (some elements wouldn't be highlighted as expected).
Since April 2021, this repository now has its own website were you can consult and download all the ALAN documentation:
PDF and HTML builds of the documents will no longer be tracked by the repository (will be ignored by Git), and will only be available through the website.
This repository was created on August 15th, 2018 by Tristano Ajmone on behalf of the Alan Interactive Fiction Development team in order to port to the AsciiDoc format the original Alan documentation, which consisted of multiple documents in various formats, and create a unified project and a toolchain to handle their conversion to different formats.
In the course of 2021, after three years of work, we finally achieved the stage where all the documents originally stored in the ALAN repository, as well as some other third party documents, were all successful recreated in AsciiDoc and made available on the project's website for online consultation or download.
Other members of the Alan group are also working on porting other Alan related documents to AsciiDoc, so hopefully this might become a collaborative project to join efforts and resources toward a unified goal.
The Alan System is distributed under the Artistic License 2.0, which includes also the documentation that ships with it.
/_assets/— shared assets:/alan-xsl-fopub/— submoduled alan-xsl-fopub repository, for XSL FOP template:/xsl-fopub/— XSL Stylesheets for PDF conversion via asciidoctor-fopub./fonts/— required fonts for PDF conversion.
/hjs/— custom highlight.js build for Alan./hl/— assets for the Asciidoctor Highlight toolchain./images//rouge/— assets for the Asciidoctor Rouge toolchain./sh/— Bash/Shell reusable scripts and modules.
/_assets-src/— assets source files:/colors/— Color schemes and palettes used in the documents./images/:/alan-logo/— Alan logo reconstructed as vector image./dia/— Dia Diagram Editor source projects for SVG diagrams.
/original-docs/— copy of the original docs being ported./sass/— Sass source files to build CSS stylesheets.
/_dev/— Project developers' stuff (testing, etc.)./alan-design/— Various WIP documents on ALAN design and internals./alanguide/— Alan 3 Beginner's Guide ported to AsciiDoc (WIP)./conversion/— ALAN Conversion Guide from v2 to v3 ported to AsciiDoc (WIP)./ideguide/— Alan IDE Reference Guide v1.0, by Robert DeFord, 2018./manual/— The Alan Manual ported to AsciiDoc./writing/— The Alan Author's Guide ported to AsciiDoc (WIP).CONTRIBUTING.md— Guidelines for contributing to this project.CONVENTIONS.md— Editors' formatting and styles guidelines.LICENSE— the Artistic License 2.0.STATUS.md— Info about the various docs, highlighters and backends.
Please, be aware of the presence of a Git submodule inside the /alan-xsl-fopub/ folder, and make sure you properly update it in your local clone of the repository to avoid regressions when commiting to the project.
For a tutorial on the common pitfalls of submodules, refer to Christophe Porteneuve's article Mastering Git submodules » The dangers we face.
For detailed info on how to use Git submodules, see:
- Pro Git book » Git Submodules — by Scott Chacon and Ben Straub.
- Learn Version Control with Git » Submodules — by Git Tower.
- Using submodules in Git - Tutorial — by Lars Vogel.
In order to distinguish between AsciiDoc documents according to their role in the project, the following file-extensions conventions are being adopted:
.asciidoc— used for Alan documentation source files..adoc— used for sub-sources in multi-file ALAN documents, i.e. imported in the main source viainclude::directives..asc— used for project docs (e.g. READMEs) and any AsciiDoc files not intendend for distribution in the Alan documentation.
Using different extensions is also required for automation scripts, which select sourcefiles by their extension during batch operations.
This is the environemnt setup used for the project by its maintainer:
ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x64-mingw32]
Asciidoctor 2.0.15
asciidoctor-fopub
asciidoctor-diagram 2.1.2
Rouge 3.26.0
Asciidoc FX v1.6.8
Dia Diagram Editor v0.97
This project provides all the required assets to highlight AsciiDoc documents containing ALAN code blocks, using Asciidoctor and a choice of different highlighters, for which Tristano Ajmone has created custom ALAN syntax definitions:
| highlighter | formats | backends |
|---|---|---|
| Highlight | HTML | Asciidoctor |
| highlight.js | HTML | Asciidoctor |
| Rouge | HTML/PDF | Asciidoctor, asciidoctor-pdf |
| XSLTHL | asciidoctor-fopub |
For more info on the various features supported by each highlighter, and how these might affect which highlighter to use for a new document, see the STATUS.md document.
In order to convert the AsciiDoc sources to any format you'll need to install Ruby and the Asciidoctor gem.
Once you've installed Ruby, you can install the Asciidoctor gem via CLI:
gem install asciidoctor
The AsciiDoc to PDF toolchain also requires setting up asciidoctor-fopub on your machine; this tool is required to convert from DocBook to PDF.
For guidelines on setting up the asciidoctor-fopub toolchain, refer to documentation of the alan-xsl-fopub submodule:
Also available locally at:
_assets/alan-xsl-fopub/README.md
This Ruby gem is an Asciidoctor extension,
Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.
It's only required to build some documents in this project, i.e. the ALAN design docs found in:
To install the Asciidoctor Diagram via the CLI:
gem install asciidoctor-diagram
Optionally, if you want to edit and build the diagram images, you'll need to install Dia on your machine too. This tool is required to build via automated scripts some images found in /_assets-src/images/.
This is a cross platform application, just download the installer matching your OS and architecture.
You don't need to install anything for documents using highlight.js; the repository contains a custom highlight.js package which is used for syntax highlighting.
Rouge is our syntax highlighter of choice in this project, so you should really install it.
This is a Ruby gem, to install it via CLI type:
gem install rouge
To edit the AsciiDoc documents I'm using both Asciidoc FX and Sublime Text 3 with the Asciidoctor Package.
Asciidoc FX is a cross platform and open source book/document editor to build PDF, Epub, Mobi and HTML books, documents and slides.
This is a great editor for AsciiDoc and offers many useful features for tracking errors and converting to various formats; but most of all it offers an in-editor live-updated HTML5 preview of the document being edited, and also supports in-browser preview with live updates.
When it comes to global editing a document or project, Sublime Text offers many powerful features which make it my first-choice editor. So I tend to do all RegEx substitutions work via Sublime Text.
The Asciidoctor package adds to Sublime Text 3 AsciiDoc syntax highlighting.
- Alan website
- Alan IF Google group
- Alan sources on GitHub — source code repository on GitHub.
- Alan IF Development team — GitHub profile and public projects.