Skip to content

alan-if/alan-repository-template

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 

Repository files navigation

ALAN Repository Template CC0 Badge

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

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:

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

What Do I Get?

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

Specifically, the repository template provides:

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

ext description
.alan Alan source files.
.i Alan source modules.
.a3s Alan commands script (aka solution files).
.a3t Alan game transcripts.
.ifid Source adventure IFID file.

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

ext description
.a3c Alan compiled adventures.
.a3r Alan compiled adventures' resource file.
.log Compiler/ARun log files.
.sav Saved games (used for testing).

Git Configurations

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 Settings

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.

How to Enable ISO Encoding for Alan Files

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.

How to Enable UTF-8 Encoding for Alan Files

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 Template

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.

License

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.

Useful Alan Links

Documentation and Tutorials

Code Examples

Libraries

Editors

Miscellanea