Alan IF Documentation Project
This repository is dedicated to the conversion of the Alan documentation to AsciiDoc. Help and contributions are welcome (see
- Alan Manual — HTML Live Preview (short URL: https://goo.gl/DNnGx8)
- Alan Manual — PDF download
- Alan IDE Reference Guide — PDF download
- Alan 3 Beginner's Guide — HTML Live Preview
- Alan Author's Guide (WIP) — HTML Live Preview
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
- About This Project
- About Alan Documentation
- External Links
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 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
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.
The Alan System is distributed under the Artistic License 2.0, which includes also the documentation that ships with it.
/hjs/— custom highlight.js build for Alan.
/hl/— assets for the Asciidoctor Highlight toolchain.
/alan-xsl-fopub/— submoduled alan-xsl-fopub repository, for XSL FOP template:
/_assets-src/(assets' source files):
/colors/— Color schemes and palettes used in the documents.
/original-docs/— copy of the original docs being ported.
/sass/— Sass source files to build CSS stylesheets.
/_dev/— Project developers' stuff (testing, etc.).
/alanguide/— Alan 3 Beginner's Guide ported to AsciiDoc (WIP).
/ideguide/— Alan IDE Reference Guide v1.0, by Robert DeFord, 2018.
/manual/— The Alan Manual ported to AsciiDoc (WIP).
/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.
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 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.
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
In order to convert the AsciiDoc sources to any format you'll need to install Ruby and the Asciidoctor gem.
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:
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
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:
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 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:
- Reference Manual (ODT document)
- Author's Guide (ODT document)
- Conversion Guide (ODT document)
- Alan Design Documentation (Word document)
- Alan Rules (RTF document)
- 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
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
- Alan website
- Alan IF Yahoo group
- Alan sources on Bitbucket — source code repository on Bitbucket.
- Alan sources on GitHub — source code repository on GitHub.
- Alan IF Development team — GitHub profile and public projects.