diff --git a/notes/release/10-1-0.md b/notes/release/10-1-0.md index ac73b0f3d..7eacd18b8 100644 --- a/notes/release/10-1-0.md +++ b/notes/release/10-1-0.md @@ -9,16 +9,135 @@ log contains some of each. ## Overview -Not yet written. +This first release built on the entirely rewritten Inform code-base contains +relatively little change in the language specification, but the move to an +Inter-based architecture, together with full support for command-line tools, +results in many new lower-level features. -## Language +Because of the scale of internal disruption since [version 9.3](9-3.md), an +exhaustive list of small changes is difficult to compile. Past release notes +have served as interim documentation on new facilities, but this repository +now provides all of that more easily. In particular: -## Documentation, examples and extensions +- The entire source base has been [published as a literate program here](https://ganelson.github.io/inform/). +- The compiler is now available as three command-line tools: + - `inbuild`, the new build manager, has a [manual here](https://ganelson.github.io/inform/inbuild/M-ui.html); + - `inform7`, the compiler proper, has its [manual here](https://ganelson.github.io/inform/inform7/M-cu.html); + - `inter`, a code-generator and linker for Inter code, has [a third manual here](https://ganelson.github.io/inform/inter/M-ui.html). +- Internally, two major new concepts have arrived: + - [Inter](https://ganelson.github.io/inform/inter/M-ti.html), a new intermediate + representation used inside the compiler; + - [kits](https://ganelson.github.io/inform/inbuild/M-agtk.html), which evolved + from the old concept of "template files" and "template code". -## Problem messages +Inform release notes have historically also included brief release notes on new +features and bug fixes in the apps for Windows, MacOS and Linux. But those have +their own repositories, and their own release notes, so from now on these +core Inform release notes will only mention major app changes. + +## Language changes + +As noted, there are surprisingly few changes to the outward-facing language +since [version 9.3](9-3.md). + +- The semantic versioning standard, see [semver.org](semver.org), has been + adopted throughout the Inform tools, and in particular is what `inbuild` + uses internally. As part of that, extensions can now give any valid + Inform semver as their version numbers. See [this implementation](https://ganelson.github.io/inweb/foundation-module/7-vn.html) + for exactly what the rules are, but there won't be anything surprising. + Past extension version numbers in the form `9` or `9/861022` are automatically + converted to `9.0.0` or `9.0.861022` as a semver, but are still legal. + So for example this: + ``` + Version 3.1.4 of Sliced Pie by Marvin Dougal begins here. + ``` + is now legal in the opening declaration of an extension, and + ``` + Include version 3.1 of Sliced Pie by Marvin Dougal. + ``` + is legal as a way to include that extension. The Inform build manager + `inbuild` allows v3.1.4 to be used to meet a request for v3.1 because + semver rules say that it ought to be compatible. See the + [inbuild manual](https://ganelson.github.io/inform/inbuild/M-ui.html) for + how to store multiple versions of the same extension side-by-side. + +- When I6-syntax material is spliced into Inform source text with the + `Include (- ... -)` construction, that material now has to comply with + the same rules applying to the source code for kits, also written in an + I6 syntax. In both cases, the material in question is no longer being + compiled to Z-code or Glulx virtual machine assembly language by `inform6`; + it is now being compiled to Inter intermediate code by a completely + different mechanism in `inter`. Most of the time users will never notice + the difference, and in any case `Include (- ... -)` is an expert-level + feature really only intended for complex extensions. However, there are + a handful of differences, notably: + - `for` loops written the old-fashioned way, with semicolons instead of + I6's preferred colons in the header, are not allowed. Changing the + semicolons to colons fixes any problems. + - With `inform6`, local variable names are allowed to coincide with statement + names: thus you can have a local called `style` even though this is also + a statement keyword. With `inter` this is not the case and such words + are reserved. The workaround is simply to rename the local in question. + +- The `Include (- ... -)` construction previously provided a way to specify + where an inclusion should occur - before or after certain headings or + template files. Those syntaxes have all been removed, since they now have + no meaning. (They assumed the code would always be literally spliced together + into an Inform 6 output file: this is now far from true.) So, for example, + ``` + Include (- ... -) before "Parser.i6t". + ``` + now has no meaning; `Parser.i6t` no longer even exists, and there's no + sense of ordering in any case. In practice the code-generator is now much + better at avoiding code-ordering issues, and this removes any need for + inclusions to be before or after anything, so just deleting those words + will usually make everything okay: + ``` + Include (- ... -) before "Parser.i6t". + ``` + However, `instead of` is more problematic. This was typically used by + extensions to replace a function inside one of the old template files with + a new implementation. That remains possible, but must be written differently: + ``` + Include (- + [ BadOldFunction; + print "This is my deluxe new version!^"; + ]; + -) replacing "BadOldFunction". + ``` + In fact this also works for variable and constant names, among other forms + of declaration. In each case, though, the idea is to supply a different + declaration for the same Inter symbol, which has to be a symbol defined + in one of the kits. + +- Suppose that the main source text creates a command verb `PURLOIN`: this + clashes with the definition of `PURLOIN` made by `CommandParserKit`, a testing + command intended not to play any part in actual play. In previous versions + of Inform, such clashes were annoying enough that authors generally had to + avoid those command verbs entirely. But Inform now automatically detects + clashes of this sort, and silently changes the debugging command by putting + an exclamation mark `!` in front. In this example `PURLOIN` would have the + meaning in the source text, and `!PURLOIN` the meaning in the kit. Note + that preference is given to non-meta commands (i.e., those affecting the + world model) over testing commands. + +- In text substitutions, a local variable name is preferred over an adaptive + verb; e.g. if `index` is both the name of a local variable and also the + infinite of a verb `to index`, so that text such as `"Consider [index]."` + is ambiguous - print the value of the variable, or print an inflected + form of the verb? - Inform will now give the local variable name priority, + on the general grounds that local definitions should override global ones. + +- Adjective inflection in English has been improved: thus + - `big` to the comparative `bigger` and superlative `biggest` + - `long` to the quantity `length` + +- Numerous maxima have been removed (for example, the limit on object name length + has gone), or raised (for example, the limit on quoted text length was raised to 8K). + +- The `Options.txt` file, if used, is now expected to be encoded as UTF-8, not + ISO Latin-1. In practice it almost always contains ASCII characters anyway. ## Bug fixes -## Mac OS X app - -## Windows app +To follow. diff --git a/notes/working_notes.md b/notes/working_notes.md index 38c2a2b2e..56f055394 100644 --- a/notes/working_notes.md +++ b/notes/working_notes.md @@ -14,6 +14,18 @@ notably the MacOS app, which is being modernised to support Dark Mode. ## News items +### Release notes (8 August 2022) + +Not a thrilling development, but we continue to get things organised ready for +formal releases of Inform from this repository. As part of that, the entire +[archive of release notes of past Inform releases](version_history.md) is now +converted to Markdown and migrated here. + +In the past, changes to Inform were logged in a sort of ebook, and indeed this +could even be downloaded in ePub format. That was before we had this repository, +though, and the ebook is being discontinued. Release notes here are clearly +easier to maintain, and to link to commits and issues. + ### State of Inform talk (30 July 2022) [The text and slides](https://ganelson.github.io/inform-website/talks/2022/07/31/narrascope-iii.html)