Skip to content
Alan IF Documentation Project
HTML Other
  1. HTML 98.4%
  2. Other 1.6%
Branch: master
Clone or download
tajmone Alan Author's Guide
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.
Latest commit 73d4f88 Aug 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_assets-src Alan Author's Guide Aug 13, 2019
_assets
_dev
alanguide Submodule: Alan XSL Fopub Apr 19, 2019
ideguide
manual
writing
.gitattributes
.gitignore
.gitmodules
CONTRIBUTING.md
CONVENTIONS.md Update Conventions Sep 5, 2018
LICENSE Initial Commit Aug 15, 2018
README.md

README.md

Alan IF Documentation Project

This repository is dedicated to the conversion of the Alan documentation to AsciiDoc. Help and contributions are welcome (see CONTRIBUTING.md).

SUBMODULES NOTE — This repository now contains Git submodules; clone with:

$ git clone --recursive https://github.com/alan-if/alan-docs

If you've already cloned it, update via:

$ git submodule update --init

Table of Contents


Latest News

Some important news for project maintainers and contributors...

Switching to Java JDK 12

Since July 2019, this project is using asciidoctor-fopub with Java JDK 12. At the time the project was created, there was a problem with gradle that prevented using Java versions above v8; the problem has been fixed since (but Tristano only recently managed to actually test it locally and start using JDK 12).

So, anyonw still using Java 12 for asciidoctor-fopub should now switch to JDK 12, which fixes many security issues.

Switching to Dart Sass

Since March 11 2019 this project has switched from using Ruby Sass to the newest Dart Sass because starting from March 26 2019 Ruby Sass will no longer be maintained.

Since Dart Sass behavior is slightly different from Ruby Sass, anyone working on the repository Sass sources must ensure to switch to Dart Sass to avoid creating divergent CSS stylesheets.

The easiest way to install Dart Sass on Windows, and keep it always updated, is to install it via Chocolatey.

From Ruby Sass homepage:

Ruby Sass will continue to be maintained until 26 March 2019. During this maintenance period, bugs will be fixed as much as possible but no new features will be added. The only exception is for features that are necessary to support new CSS syntax, which will continue to be added.

Dart Sass, the new primary implementation, doesn't always behave 100% the same as Ruby Sass—it implements a number of behavioral changes that were planned for Ruby Sass, but were never implemented in a stable version. To make migration easier, recent versions of Ruby Sass emit warnings for any code that won't be compatible with Dart Sass. Ongoing maintenance includes adding any warnings for new behavioral differences, if they come up.

Once the maintenance period ends, Ruby Sass's repository will be archived, no more changes of any kind will be made, and no new releases will be cut.

About This Project

This repository was created on August 15th, 2018 by Tristano Ajmone on behalf of the Alan Interactive Fiction Development team.

At the present stage, Alan documentation consists of multiple documents in various formats; the goal of this project is to port them all to AsciiDoc and create a unified project and a toolchain to handle conversion to different formats.

Other members of the Alan group are also working on porting other Alan documents to AsciiDoc, so hopefully this might become a collaborative project to join efforts and resources toward a unified goal.

Being still a young project, may aspects are still vaguely defined and open to suggestions.

License Terms

The Alan System is distributed under the Artistic License 2.0, which includes also the documentation that ships with it.

Project Contents

Git Submodules

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:

File Extensions Conventions

In order to distinguish between AsciiDoc documents according to their role in the project, the following file-extensions conventions are being adopted:

  • ".asciidoc" is used for Alan documentation source files.
  • ".adoc" is 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.

Development Enviroment Info

This is the environemnt setup used for the project by its maintainer:

Ruby 2.6.1p33 (2019-01-30 revision 66950) [x64-mingw32]
Asciidoctor 2.0.6
asciidoctor-fopub
Asciidoc FX v1.6.8
Dia Diagram Editor v0.97.2

Project Dependencies

AsciiDoctor

In order to convert the AsciiDoc sources to any format you'll need to install Ruby and the Asciidoctor gem.

Asciidoctor-fopub

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

Dia Diagram Editor

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/.

Syntax Highlighting

Tristano Ajmone has created an Alan syntax definition for Highlight, the cross platform syntax highlighter by André Simon. The Alan syntax is now part of the official Highlight distribution:

We're planning to integrate Hihglight into the Asciidoctor workflow in order to syntax highlight the code examples in the documentation. For more info, see Issue #2106 at Asciidoctor.

Work Tools

To edit the AsciiDoc documents I'm using both Asciidoc FX and Sublime Text 3 with the Asciidoctor Package.

Asciidoc FX

Asciidoc FX is a cross platform and opensource 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.

Sublime Text Asciidoctor

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.


About Alan Documentation

The complete (unported) Alan documentation can be found at:

Which is divided into three sub-foldered groups of documents:

  • /manual/:
    • Reference Manual (ODT document)
    • Author's Guide (ODT document)
    • Conversion Guide (ODT document)
  • /design/:
    • Alan Design Documentation (Word document)
    • Alan Rules (RTF document)
  • /guide/:
    • Alan 3 Beginner's Guide (AsciiDoc) by Michael Arnaud

Standard Library Documentation

Furthermore, there's the documentation for Anssi Räisänen's Alan StdLib:

Which consists of:

  • Alan Standard Library 2.x User's Manual (PDF)
  • Quick Reference for ALAN Standard Library v2.x
  • The Very Quick Start Guide for ALAN Standard Library v2.x

Alan Cookbook

Last but not least, there's The Alan Cookbook (available on Alan IF Yahoo group):

  • The Alan Cookbook (PFD & txt) by Anssi Räisänen

External Links

Alan

AsciiDoctor

Highlight

You can’t perform that action at this time.