mirror of
https://github.com/ganelson/inform.git
synced 2024-07-16 22:14:23 +03:00
288 lines
17 KiB
Plaintext
288 lines
17 KiB
Plaintext
# Inform 7
|
|
|
|
v{bibliographic datum: Semantic Version Number of: inform7} '{bibliographic datum: Version Name of: inform7}' ({bibliographic datum: Build Date of: inform7})
|
|
|
|
## About Inform 7
|
|
|
|
Inform 7 (April 2006-) 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.
|
|
|
|
{set name: GITHUBPAGESLINK value: docs}
|
|
{set name: WEBICON value: ★}
|
|
{set name: DOCICON value: ▶}
|
|
|
|
Inform is itself a literate program, one of the largest in the world. This
|
|
means that a complete presentation of the code, in human-readable form, is
|
|
continuously maintained alongside the code itself. So to read this, along with
|
|
technical documentation and other useful resources, turn to the companion
|
|
web page to this repository: {WEBICON} [Inform: The Program]({GITHUBPAGESLINK})
|
|
|
|
Writing and presenting Inform as a literate program was beyond the capabilities
|
|
of existing LP software, so a new system for LP called Inweb
|
|
has been spun off from Inform, and that has [its own repository](https://github.com/ganelson/inweb).
|
|
|
|
__Disclaimer__. Because this is a private repository (until the next public
|
|
release of Inform, when it will open), its GitHub pages server cannot be
|
|
enabled yet. As a result links marked {WEBICON} lead only to raw HTML
|
|
source, not to served web pages. They can in the mean time be browsed offline
|
|
as static HTML files stored in "docs".
|
|
|
|
## Licence and copyright
|
|
|
|
Except as noted, copyright in material in this repository (the "Package") is
|
|
held by Graham Nelson (the "Author"), who retains copyright so that there is
|
|
a single point of reference. As from the first date of this repository
|
|
becoming public, the Package is placed under the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).
|
|
This is a highly permissive licence, used by Perl among other notable projects,
|
|
recognised by the Open Source Initiative as open and by the Free Software
|
|
Foundation as free in both senses.
|
|
|
|
For the avoidance of doubt, the Author makes the further grant that users of
|
|
the Package may make unlimited use of story files produced by the Package:
|
|
such story files are not derivative works of Inform and do not inherit the
|
|
Artistic License 2.0 as an obligation. (This further grant follows the
|
|
practice of projects like bison, which also copy substantial code into
|
|
their outputs.)
|
|
|
|
A condition of any pull-request being made (i.e., to make suggested amendments
|
|
to this software) is that, if the request is accepted, copyright on any contribution
|
|
made by it immediately transfers to the project's copyright-holder, Graham Nelson.
|
|
This is in order that there can be clear ownership. It does not apply to the
|
|
programs duplicated here from other repositories (such as dumb-frotz) or to the
|
|
Inform GUI apps: those have their own copyrights and licences.
|
|
|
|
## Repositories
|
|
|
|
This is the "core 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 you also need Inweb and Intest, programs
|
|
spun out from the Inform project. These are __not included in the core
|
|
repository either as submodules or copies__, and have their own repositories.
|
|
* [https://github.com/ganelson/inweb](https://github.com/ganelson/inweb), maintained by [Graham Nelson](https://github.com/ganelson)
|
|
* [https://github.com/ganelson/intest](https://github.com/ganelson/intest), maintained by [Graham Nelson](https://github.com/ganelson)
|
|
* Most Inform authors use Inform as an app: for example, it is available
|
|
on the Mac App Store. While much of the UI design is the same across all
|
|
platforms, each app has its own code in its own repository. See:
|
|
* [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)
|
|
|
|
## Build Instructions
|
|
|
|
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 that passes, probably all is well. The definitive test is "make check",
|
|
which runs nearly 2500 cases through the executables, but takes 10 minutes
|
|
on an 8-core desktop and half an hour on a 4-core laptop (which will sound
|
|
something like a helicopter taking off).
|
|
|
|
## Reporting Issues
|
|
|
|
The old Inform bug tracker, powered by Mantis, has now closed, and its issues
|
|
and comments have been migrated to the new one, powered by Jira and hosted
|
|
[at the Atlassian website](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.
|
|
|
|
## Pull Requests and Adding Features
|
|
|
|
Inform is only just emerging, blinking, into the light of being open-source after
|
|
two decades of private development. It has a mature and well-used feature set,
|
|
so that new or changed functionality requires careful thought. For the moment,
|
|
its future direction remains in the hands of the original author. At some point
|
|
a more formal process may emerge, but for now community discussion of possible
|
|
features is best kept to the IF forum. In particular, please do not use the
|
|
bug trackers to propose new features.
|
|
|
|
Pull requests adding functionality or making any significant changes are therefore
|
|
not likely to be accepted from non-members of the Inform team without prior
|
|
agreement, unless they are clear-cut bug fixes or corrections of typos, broken
|
|
links, or similar. See also the note about copyright above.
|
|
|
|
The Inform licence is highly permissive, and forks which develop in quite different
|
|
ways are entirely within the rules. (But one of the few requirements of the
|
|
Artistic Licence is that such forks be given a name which is not simply "Inform 7",
|
|
to avoid confusion.)
|
|
|
|
## Inventory
|
|
|
|
**"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. (This will be enabled when the repository
|
|
becomes public: GitHub Pages does not work on private repositories.)
|
|
|
|
### 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} Web]({GITHUBPAGESLINK}/{PROGRAM}/index.html) - [{DOCICON} 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}
|
|
{tool-with-manual name: inrtps version-from: inrtps 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} Web]({GITHUBPAGESLINK}/{PROGRAM}/index.html)
|
|
{end-define}
|
|
{kit name: BasicInformKit purpose: Support for Inform as a programming language}
|
|
{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: BasicInformExtrasKit purpose: Additional support needed only if the Standard Rules are not used}
|
|
|
|
### 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} Web]({GITHUBPAGESLINK}/{WEB}/index.html)
|
|
{end-define}
|
|
{define: extension author: AUTHOR title: TITLE}
|
|
{set name: PATH value: inform7/Internal/Extensions/{AUTHOR}/{TITLE}.i7x}
|
|
* [{TITLE} by {AUTHOR}](<{PATH}>) - __v{bibliographic datum: Version Number of: {PATH}}__
|
|
{end-define}
|
|
|
|
{extension-web web: basic_inform author: Graham Nelson title: Basic Inform}
|
|
{extension-web web: standard_rules author: Graham Nelson title: Standard Rules}
|
|
|
|
Other extensions shipped with Inform are not presented as webs, but as single files:
|
|
|
|
{extension author: Emily Short title: Basic Help Menu}
|
|
{extension author: Emily Short title: Basic Screen Effects}
|
|
{extension author: Emily Short title: Complex Listing}
|
|
{extension author: Emily Short title: Glulx Entry Points}
|
|
{extension author: Emily Short title: Glulx Image Centering}
|
|
{extension author: Emily Short title: Glulx Text Effects}
|
|
{extension author: Emily Short title: Inanimate Listeners}
|
|
{extension author: Emily Short title: Locksmith}
|
|
{extension author: Emily Short title: Menus}
|
|
{extension author: Emily Short title: Punctuation Removal}
|
|
{extension author: Emily Short title: Skeleton Keys}
|
|
{extension author: Eric Eve title: Epistemology}
|
|
{extension author: Graham Nelson title: Approximate Metric Units}
|
|
{extension author: Graham Nelson title: English Language}
|
|
{extension author: Graham Nelson title: Metric Units}
|
|
{extension author: Graham Nelson title: Rideable Vehicles}
|
|
{extension author: Graham Nelson title: Unicode Character Names}
|
|
{extension author: Graham Nelson title: Unicode Full Character Names}
|
|
|
|
### 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}.i7x}
|
|
* [{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 - Inrtps 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.mk file was generated automatically by Inweb, and should not
|
|
be edited. To make changes, edit inform.rmscript and re-generate.
|