inform7/scripts/inform.rmscript

# Inform 7

[Version](notes/versioning.md): {bibliographic datum: Semantic Version Number of: inform7} '{bibliographic datum: Version Name of: inform7}' ({bibliographic datum: Build Date of: inform7})

## About Inform

Inform is a programming language for creating interactive fiction, using natural
language syntax. Using natural language and drawing on ideas from linguistics
and from literate programming, Inform is widely used as a medium for literary
writing, as a prototyping tool in the games industry, and in education, both at
school and university level (where Inform is often assigned material for courses
on digital narrative). It has several times ranked in the top 100 most
influential programming languages according to the TIOBE index. Created in April
2006, it was open-sourced in April 2022.

{set name: GITHUBPAGESLINK value: https://ganelson.github.io/inform}
{set name: WEBICON value: ★}
{set name: DOCICON value: ▶}

Inform is itself a literate program ([written with inweb](https://github.com/ganelson/inweb)),
one of the largest in the world. This means that a human-readable form of the
code is continuously maintained alongside it: see {WEBICON} [Inform: The Program]({GITHUBPAGESLINK})

Software in this repository is [copyright Graham Nelson 2006-2022](notes/copyright.md)
except where otherwise stated, and available under the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).

To consult...                     | Turn to...
--------------------------------- | -----------------------------------------
Brief news about ongoing work     | [notes/working_notes.md](notes/working_notes.md)
Licencing and copyright policy    | [notes/copyright.md](notes/copyright.md)
Branching and versioning policy   | [notes/versioning.md](notes/versioning.md)
Language evolution policy         | [https://github.com/ganelson/inform-evolution](https://github.com/ganelson/inform-evolution)
Version history and release notes | [notes/version_history.md](notes/version_history.md)
Pending changes not yet released  | [notes/release/pending.md](notes/release/pending.md)

## Repositories

This is the "core Inform" repository, holding source code for the compiler, and
for everything needed to run it on the command line. However:

* To build and test the compiler on the command line you also need Inweb and
Intest, programs spun out from the Inform project, with their own repositories:
	* [https://github.com/ganelson/inweb](https://github.com/ganelson/inweb)
	* [https://github.com/ganelson/intest](https://github.com/ganelson/intest)
* Most Inform authors use Inform as an app, not at the command line. While
the UI looks similar on each platform, they are independent code-bases and each
has its own repository:
	* [https://github.com/TobyLobster/Inform](https://github.com/TobyLobster/Inform) for MacOS, maintained by [Toby Nelson](https://github.com/TobyLobster)
	* [https://github.com/DavidKinder/Windows-Inform7](https://github.com/DavidKinder/Windows-Inform7) for Windows, maintained by [David Kinder](https://github.com/DavidKinder)
	* [https://github.com/ptomato/inform7-ide](https://github.com/ptomato/inform7-ide) for Linux, maintained by [Philip Chimento](https://github.com/ptomato)
* Proposals for changes to Inform are at the repository:
	* [https://github.com/ganelson/inform-evolution](https://github.com/ganelson/inform-evolution)
* The server-side content for the Inform Public Library (a selection of downloadable
extensions displayed within the apps) is here:
	* [https://github.com/ganelson/inform-public-library](https://github.com/ganelson/inform-public-library)

## Build Instructions

**Caution**: The `main` branch of this repository generally holds "unstable", that is,
unreleased work-in-progress versions of Inform. See [notes/versioning.md](notes/versioning.md).

Make a directory in which to work: let's call this `work`. Then:

* Change the current directory to `work`: `cd work`
* Build Inweb as `work/inweb`: see its repository [here](https://github.com/ganelson/inweb)
* Build Intest as `work/intest`: see its repository [here](https://github.com/ganelson/intest)
* Clone Inform as `work/inform`: `git clone https://github.com/ganelson/inform.git`
* Change the current directory to this: `cd inform`
* Run a first-build script: `bash scripts/first.sh`
* Check executables have compiled: `inblorb/Tangled/inblorb -help`
* Run a single test case: `../intest/Tangled/intest inform7 -show Acidity`.
* If you have time (between 5 mins and 2 hours, depending on your system), `make check`
to run the full suite of 2500 test cases.

**Caution again**: `inform7` is written in standard C99, but is a challengingly
large task for a C compiler. In the past we have had difficulties using `gcc` to
compile it, and although we believe these may now be resolved, we recommend compiling
the core Inform tools with `clang` rather than `gcc` where possible.

## Issues and Contributions

The 2006-2021 Inform bug tracker, powered by Mantis, has now closed, and its issues
and comments have been migrated to a [a Jira tracker](https://inform7.atlassian.net/jira/software/c/projects/I7/issues).
The curator of the bug tracker is Brian Rushton, and the administrator is
Hugo Labrande.

Note that Inweb and Intest have their own bug trackers
([here](https://inform7.atlassian.net/jira/software/c/projects/INWEB/issues)
and [here](https://inform7.atlassian.net/jira/software/c/projects/INTEST/issues)).
Please do not report bugs on those to the Inform tracker, or vice versa.

Members of the Inform community are welcome to open pull requests on this
repository to address minor issues - for example, to fix bugs at the tracker,
or to correct clear-cut typos or other errors. Contributions of this sort do
not need [an Inform Evolution proposal](https://github.com/ganelson/inform-evolution),
but anything on a larger scale is likely to.

## Inventory of this Repository

**"I can't help feeling that if someone had asked me before the universe began
how it would turn out, I should have guessed something a bit less like an old
curiosity shop and a bit more like a formal French garden - an orderly
arrangement of straight avenues, circular walks, and geometrically shaped
trees and hedges."** (Michael Frayn)

Inform is not a single program, but an assemblage of programs and resources.
Some, including the inform7 compiler itself, are "literate programs", also
called "webs". The notation {WEBICON} marks these, and links are provided to
their human-readable forms.

### Source for command-line tools

This most important contents of this repository are the source webs for the
following command-line tools:

{define: tool-with-manual name: PROGRAM version-from: VPROGRAM doc: DOCUMENTATION}
* {PROGRAM} - __version {bibliographic datum: Version Number of: {VPROGRAM}}__ - [{WEBICON}&nbsp;Web]({GITHUBPAGESLINK}/{PROGRAM}/index.html) - [{DOCICON}&nbsp;Documentation]({GITHUBPAGESLINK}/{PROGRAM}/{DOCUMENTATION}.html)<br>{bibliographic datum: Purpose of: {PROGRAM}}
{end-define}
{tool-with-manual name: inbuild  version-from: inform7  doc: M-ui}
{tool-with-manual name: inform7  version-from: inform7  doc: M-cu}
{tool-with-manual name: inter    version-from: inform7  doc: M-ui}
{tool-with-manual name: inblorb  version-from: inblorb  doc: M-ui}
{tool-with-manual name: indoc    version-from: indoc    doc: M-iti}
{tool-with-manual name: inpolicy version-from: inpolicy doc: M-ui}

### Kits shipped with Inform

The following webs are the source for kits of Inter code shipped with Inform (at the subtree inform7/Internal/Inter). Kits are libraries of code needed at run-time, and whose source is written in Inform 6 notation:

{define: kit name: PROGRAM purpose: PURPOSE}
* {PROGRAM} - {PURPOSE} - [{WEBICON}&nbsp;Web]({GITHUBPAGESLINK}/{PROGRAM}/index.html)
{end-define}
{kit name: BasicInformKit       purpose: Support for Inform as a programming language}
{kit name: Architecture16Kit    purpose: Support for running on 16-bit platforms}
{kit name: Architecture32Kit    purpose: Support for running on 32-bit platforms}
{kit name: WorldModelKit        purpose: Support for modelling space, time and actions in interactive fiction}
{kit name: EnglishLanguageKit   purpose: Support for English as the natural language used}
{kit name: CommandParserKit     purpose: Support for parsing turn-by-turn commands in interactive fiction}
{kit name: DialogueKit          purpose: Additional support for dialogue (under construction)}

### Extensions shipped with Inform

The following webs are the source for the two most important extensions shipped with Inform:

{define: extension-web web: WEB author: AUTHOR title: TITLE}
{set name: PATH value: inform7/Internal/Extensions/{AUTHOR}/{TITLE}.i7x}
* [{TITLE} by {AUTHOR}](inform7/extensions/{WEB}) - __v{bibliographic datum: Version Number of: {PATH}}__ - [{WEBICON}&nbsp;Web]({GITHUBPAGESLINK}/{WEB}/index.html)
{end-define}

{extension-web web: basic_inform   author: Graham Nelson title: Basic Inform}
{extension-web web: standard_rules author: Graham Nelson title: Standard Rules}

### Website templates and interpreters shipped with Inform

These are templates used by Inform to release story files within a website:

{define: websitetemplate name: NAME purpose: PURPOSE}
{set name: PATH value: inform7/Internal/Templates/{NAME}}
* [{NAME}]({PATH}) - {PURPOSE}
{end-define}
{websitetemplate name: Classic  purpose: An older, plainer website}
{websitetemplate name: Standard purpose: The default, more modern look}

These are Javascript interpreters used to release such websites in a form which can play the story files interactively online:

{define: template program: PROGRAM purpose: PURPOSE maintainer: MAINTAINER username: USERNAME repository: REPOSITORY}
* {PROGRAM} - {PURPOSE} - __{bibliographic datum: Version Number of: {PROGRAM}}__ - from [https://github.com/{USERNAME}/{REPOSITORY}], maintained by [{MAINTAINER}](https://github.com/{USERNAME})
{end-define}
* inform7/Internal/Templates - Template websites for Inform 7's 'release as a website' feature
{template program: inform7/Internal/Templates/Parchment purpose: Z-machine in Javascript maintainer: Dannii Willis username: curiousdannii repository: parchment}
{template program: inform7/Internal/Templates/Quixe purpose: Glulx in Javascript maintainer: Andrew Plotkin username: erkyrath repository: quixe}

### Documentation shipped with Inform

Two books come with the Inform apps. The source code for these books is in indoc format: the indoc tool makes those into ePubs, mini-websites, or the pseudo-websites inside the apps.

{define: book title: TITLE path: PATH topic: TOPIC}
* __{TITLE}__ - {TOPIC}. Ebook in Indoc format, stored at path {PATH}.
{end-define}
{book title: Changes to Inform                              path: resources/Changes       topic: A detailed change history of Inform 7}
{book title: Writing with Inform and the Inform Recipe Book path: resources/Documentation topic: The main Inform documentation, as seen in the apps, and in standalone Epubs}

In addition, there are:

* resources/Outcome Pages - Inbuild uses these to generate HTML outcome pages (such as those showing Problem messages in the app)
* resources/Sample Projects - Two small interactive fictions, 'Disenchantment Bay' and 'Onyx', presented as samples in the app

### Retrospective builds of Inform

New in 2022 is the ability for apps to use past instead of present versions of the
core Inform software when compiling a project. This means the core software distribution
needs to contain some form of those past versions - at minimum, the extensions and
compiler tools for (say) versions 9.1, 9.2 and 9.3.

That material is held in the "retrospective" directory. Note that documentation
from past versions (e.g., past versions of "Writing with Inform") is not included.

### Resources copied here from elsewhere

Stable versions of the following are periodically copied into this repository,
but this is not where development on them is done, and no pull requests will
be accepted. (Note that these are not git submodules.)

* inform6 - The Inform 6 compiler (used by I7 as a code generator). - __{bibliographic datum: Version Number of: inform6}__ - from [https://github.com/DavidKinder/Inform6], maintained by [David Kinder](https://github.com/DavidKinder)
	* inform6/Tests/Assistants/dumb-frotz - A dumb-terminal Z-machine interpreter. - unversioned: modified from [Alembic Petrofsky's 1998 Teletype port of Frotz](https://github.com/sussman/ircbot-collection/tree/master/dumb-frotz)
	* inform6/Tests/Assistants/dumb-glulx/glulxe - A dumb-terminal Glulx interpreter. - __{bibliographic datum: Version Number of: inform6/Tests/Assistants/dumb-glulx/glulxe}__ - [erkyrath/glulxe](https://github.com/erkyrath/glulxe), maintained by [Andrew Plotkin](https://github.com/erkyrath)
	* inform6/Tests/Assistants/dumb-glulx/cheapglk - A basic Glk implementation to support dumb-glulxe. - __{bibliographic datum: Version Number of: inform6/Tests/Assistants/dumb-glulx/cheapglk}__ - [erkyrath/cheapglk](https://github.com/erkyrath/cheapglk), maintained by [Andrew Plotkin](https://github.com/erkyrath)

* inblorb/Tests/Assistants/blorblib - Code for examining blorb files, including blorbscan, used here for validating inblorb's output in tests. - version 1.0.2 - by [Andrew Plotkin](https://github.com/erkyrath), but not currently elsewhere on Github

### Binary resources (such as image files)

* resources/Imagery/app_images - icons for the Inform app and its many associated files, in MacOS format
* resources/Imagery/bg_images - background textures used in the Index generated by Inform
* resources/Imagery/doc_images - miscellaneous images needed by the documentation
* resources/Imagery/map_icons - images needed for the World pane of the Index generated by Inform
* resources/Imagery/outcome_images - images used on outcome pages
* resources/Imagery/scene_icons - images needed for the Scenes pane of the Index generated by Inform
* resources/Internal/Miscellany - default cover art, the Introduction to IF and Postcard PDFs

### Other files and folders in this repository

* docs - Woven forms of the webs, for serving by GitHub Pages
* scripts/inform.giscript - Inweb uses this to generate the .gitignore file at the root of the repository
* scripts/inform.mkscript - Inweb uses this to generate the makefile at the root of the repository
* scripts/inform.rmscript - Inweb uses this to generate the README.md file you are now reading

### Colophon

This README.md file was generated automatically by Inweb, and should not
be edited. To make changes, edit inform.rmscript and re-generate.