• https://github.com/alan-if/alan-repository-template

A boilerplate for quickly creating Alan projects with all the right settings in place.

Created by Tristano Ajmone on July 13, 2019. Released into the Public Domain.

Table of Contents

• About this Template
  • What Do I Get?
    • Git Configurations
    • EditorConfig Settings
      • How to Enable ISO Encoding for Alan Files
      • How to Enable UTF-8 Encoding for Alan Files
    • README Template
  • License
• Useful Alan Links
  • Documentation and Tutorials
  • Code Examples
  • Libraries
  • Editors
  • Miscellanea

In June 6, 2019 GitHub announced a new feature to generate new repositories with repository templates. At the Alan IF Development team we promptly grasped the great potential of this new cool feature and decided to create a repository template for Alan projects, and release it into the public domain.

You can use this template to quickly create a GitHub repository for Alan projects by clicking on the Use this template button placed on the bar above the files list, or by clicking on this link.

Your new repository created using this template will be optimally configured for working with Alan tools, adventures, commands scripts and game transcripts.

For more detailed information on using repository templates, see:

• GitHub Docs » Creating a repository from a template

To learn more about the internal details of this template, consult the repository Wiki.

The template is just a boilerplate containing useful configurations designed to optimize Alan workflow in cross-platform collaborative projects.

Specifically, the repository template provides:

• Git configurations
• Editor configurations
• A README document template

The configuration files for Git and EditorConfig cover the following Alan-specific files extensions:

By default, the following Alan generated files will be excluded from the project:

• .gitattributes
• .gitignore

The template contains pre-set .gitignore and .gitattributes files with carefully designed patterns that will cover a variety of Alan usage scenarios in cross-platform environments.

The .gitattributes file defines EOL normalization settings for a variety of Alan related files, as well as covering common file extensions used in IF projects. It also provides additional settings for GitHub Linguist, to improve repository statistics and Alan source files visualization on GitHub.

The .gitignore file defines ad hoc file exclusion patterns for Alan projects, as well as covering common exclusion patterns for Windows, Linux and macOS.

• .editorconfig

The template contains EditorConfig settings for Alan files plus some generic Git repository settings, designed to offer support across multiple editors and IDEs, as well as to provide optimal source code previews on GitHub.

The EditorConfig file format is an application-agnostic standard for defining consistent coding style conventions for multiple developers working on the same project across various editors and IDEs. A growing number of editors and IDEs support EditorConfig out of the box, and numerous plug-ins and extensions are available for editors that don't.

One of the main benefits of the EditorConfig settings is the ability to enforce ISO-8859-1 encoding on Alan files (*.alan, *.i, *.a3s, *.a3t) and prevent accidental UTF-8 file-corruption from copy-&-paste operations. Most editors that support EditorConfig should be able to enforce ISO-8859-1 strictness on Alan sources via the .editorconfig file.

IMPORTANT! Since Alan Beta8 introduces support for UTF-8 encoded Alan files, the template doesn't set any encoding for Alan files. You should manually edit the .editorconfig file according to your needs (instructions below).

As of Jun 2015, GitHub natively supports EditorConfig files within repositories. The .editorconfig file in this template will improve Alan sources visualization on GitHub. Although GitHub doesn't recognize Alan source files natively, it will honour the EditorConfig settings of this template.

To enforce ISO-8859-1 encoding (i.e. Latin1) on Alan files, edit the .editorconfig file and change the charset key for ALAN IF to latin1:

## ALAN IF
##########

# Common settings for all Alan files
[*.{alan,i,a3s,a3t}]
indent_style = space
indent_size = unset
charset = latin1

WARNING! If you use EClint to validate project sources, don't use charset = latin1, because EClint is buggy and will report false-positive errors for validly encoded ISO-8859-1 files! (See edmao/eclint#169) Just keep charset = unset.

Alan Beta8 introduces support for UTF-8 encoded Alan files. If you're working with UTF-8 encoded Alan files, you should edit the .editorconfig file and change the charset key for ALAN IF to either utf-8-bom or utf-8, depending on whether you're adding a BOM to the files or not (it's advisable to do so):

## ALAN IF
##########

# Common settings for all Alan files
[*.{alan,i,a3s,a3t}]
indent_style = space
indent_size = unset
charset = utf-8-bom

• README.md

You also get this markdown README document that you're reading right now, which contains the Useful Alan Links section providing links to various Alan related assets, which you might reuse in your project. It's a well structured and polished markdown document, with many reference links to Alan assets (at the end of the source document) which might come handy — and could spare you a good amount of typing, if you're going to link to other Alan projects.

If you don't need the README file you can just trash it, but chances are that you'll be adding a README.md file to your project anyway, so you might as well just overwrite it, or keep the reference links that you need. After some initial thoughts, I finally decided that it was better to include this README file in the template, for the benefit of those wishing to offer links to the Alan community and assets, rather than leave it out. For those who'll need it, it's going to be a true time-saver, while those who don't need it shouldn't be bothered much by having to delete/overwrite it.

To the extent possible under law, Tristano Ajmone has waived all copyright and related or neighboring rights to the ALAN Repository Template. This work is published from: Italy.

The ALAN Repository Template is released into the public domain via the CC0 1.0 Universal dedication, so that it might be freely used for any project, without causing licenses conflicts and without imposing any restrictions or obligations (not even crediting or linking back).

No Copyright

The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.

You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission. See Other Information below.

Other Information

• In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights.
• Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law.
• When using or citing the work, you should not imply endorsement by the author or the affirmer.

• www.AlanIF.se — the Alan website.
• Alan IF Google Group — for community help, announcements and discussions.
• Alan sources on GitHub — source code repository on GitHub.
• Alan IF Development team — GitHub profile and public projects.

• Alan Docs — GitHub repository for Alan documentation.
• The Alan Manual — online-readable version of the latest ALAN Adventure Language Reference Manual.
• Alan Cookbook v2 — by Anssi Räisänen.
• The Alan Beginner's Guide — by Michael Arnaud (2006). Tutorial source files available.
• Alan IDE Reference Guide — by Robert DeFord (2018).

• Alan by Examples — community driven collection of examples to learn Alan.
• Samples & examples for Alan v3 — on Alan website.

• Alan Standard Library — by Anssi Räisänen, GitHub repository.
• Alan Library v0.6.2 — an earlier (but still working) library (2002–2007), mainly used to compile legacy adventures.
• Alan StdLibLab — experimental playground for variations on the Alan StdLib.
• Alan Italian — Italian port of the Alan StdLib.

• AlanIDE — a complete Alan Integrated Development Environment, built in Java/Eclipse by Alan developer Thomas Nilefalk. For more info, see:
  • AlanIDE info page.
  • Alan IDE Reference Guide — by Robert DeFord (2018), PDF document.
  • AlanIDE sources — JAVA source files, on GitHub.
• Sublime Alan IF — Sublime Text 4 package for Alan 3 (working Alpha).

• Alan Goodies — a collection of assorted assets for Alan.
• Alan Builder — a Travis CI compliant build tool for Alan IF adventures projects.
• Alan Bugs Testbed — collaborative project to report and test Alan bugs.
• Alan Repository Template — A boilerplate for quickly creating Alan repositories with the right settings.