Inform 6 reference addendum (draft)

In some of the recent threads here, people have asked questions about I6 features that aren’t covered by the DM4.

Most of the answers are in the release notes document (https://ifarchive.org/if-archive/infocom/compilers/inform6/ReleaseNotes.html). But that’s hard to search and sometimes only has brief summaries of new features.

I have written up an overview of everything that’s been added to the I6 compiler since the DM4 was written. (The DM4 covers Inform 6.21.) I guess it’s still brief summaries, but at least it’s now organized in alphabetical lists.

This just covers the compiler and the Inform 6 language, not the library. (David Griffith handles the library.)

Draft is here: https://eblong.com/zarf/tmp/I6-addendum.html

This is a temporary URL. I expect it will move to the IF Archive or somewhere once it’s finalized.

Does this make sense? Have I left anything out?

7 Likes

Perhaps something could be said about case with compiler directives. The compiler accepts any sort of capitalization, CamelCase, etc. An issue was filed with the standard library that in accordance with the DM4, a compiler directive should be first letter capitalized and the rest lowercase. @Zarf and I had a brief discussion about this and came to the agreement that it wasn’t important enough to change the caps of directives in the glk-dev package. Let’s discuss this. Should capitalization be standardized?

mhm… it’s clear for me. I suspect that there’s an obvious whose should be spelled out, namely that Replace should follow the inclusion of library/extension files, but this is a comment on a language documentation came from one who code programs since early 80s or so… this is my mileage.

Best regards from Italy,
dott. Piergiorgio.
(just awake…)

Right, the compiler directive question… my position (from that discussion) is that the compiler has always treated directives as case-insensitive. The compiler treats nearly all symbols as case-insensitive, with the exception of print tokens:

print (The) foo, (the) foo, (A) foo, (a) foo;

The DM4 mostly writes directives in title-case (Ifdef, Object, Zcharacter) but there are some exceptions. The I6 templates in I7 make no attempt to be consistent; they use IFDEF, ifdef, Ifdef interchangeably.

I say it would be absurd to declare at this late date that directives must have a particular capitalization. The only result would be to break a huge amount of existing source code.

Therefore, the DM4’s use of title case should be regarded as a house style, rather than a requirement of the language. I’ll put a note in the document saying so.

2 Likes

Please add an appropriate license allowing others to be able change, share, and improve it into the future.

The natural place for changes to things like the language and etc. to end up would seem to be the DM4. My understanding is that the need for an Addendum comes from Graham Nelson making the DM4 legally unmodifiable while yet allowing changes to Inform 6. Let’s not repeat the same mistake and then, after more more changes are made to the language and etc. in the future, we end up with Addendums-upon-Addendums-upon-Addendums as each of them are legally unmodifiable.

One way to ensure people being able to change, share, and improve it into the future would be to apply GPL-3.0-or-later, as it would not allow someone to make changes that didn’t also come with that permission. Failing that, another idea might be using the Artistic License 2.0 which I assume the Inform Release Notes are already under. Using the same might be good for consistency. Or at the very least a simple

“Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.”

I will add an appropriate license; thanks for reminding me.

I feel like this goes with the DM4 rather than with the source code, so it should have a CC license rather than GPL. Probably CC-BY-SA-4; that’s the license that covers most of the contents of the http://inform-fiction.org/ site at this point.

That’s sort of technically true, I guess? But not in practice.

I can’t imagine just plunking some updates or corrections into the DM4. That has nothing to do with its copyright status. The DM4 is so strongly in Graham’s voice that, even if the text were CC-licensed, I wouldn’t feel comfortable rewriting any of it.

I can imagine a new edition of the DM4 coming out. That would be with Graham’s permission and active assistance. He could stick this addendum into it if he wanted.

1 Like

Agree, Lord Nelson of Inform ought to be informed of this issue (yes, pun intentional…)

My personal opinion is that the best solution must be a DM4r (we have already a DM3r, after all…) and the best context should be the release of the announced of Inform 8/whatever.

Another improvement, thinking carefully on, is giving a pointer to the chapter/paragraph the addenda apply; not everyone known programming manuals from cover to cover, after all.

Best regards from Italy,
dott. Piergiorgio.

Inform 8???

I am fortunate to have a hard copy of DM4 (and IBG). Almost all of DM4 is still accurate. Most of the needed changes are additions. The reference addendum format seems appropriate from an author’s perspective and the fact that I6 is very mature and stable.

(The next release is going to be called Inform 7 version 7.10, as far as I know.)

Chapter references are a good idea, thanks.

1 Like

I’ve added the license statement and chapter references.

Does anybody have any other comments before this goes up?

https://eblong.com/zarf/tmp/I6-addendum.html

2 Likes

Now that there are more than just one library available for use with Inform6, how should that be discussed in this document or any future versions of the Designer’s Manual or Beginner’s Guide?

1 Like

Agree. My concern (whose I admit that failed to explain clearly in my murky post above) was that there’s another replace, modifier of extend, ch.30. and w/o references, there was risk of confusion…

Thanks and my
Best regards from Italy,
dott. Piergiorgio.

(I believe OnyxRing goes back to 2004, as an alternative I6 library.)

This only addresses the compiler, obviously. But you’re right that there should be some explanation, since the DM4 deals with the compiler and library as a unit. I’ll add a paragraph to the introduction.

1 Like

(Actually it’s Platypus that’s the alternative I6 library. Onyx Ring is an extension. I’ve been misremembering that for as long as both have existed…)

I added some introductory text about libraries.

2 Likes

I like the green ink clarification. Well evidenced and the clarification are very clear and understandable.

[jokes on RN Admiralty elided]

Best regards from Italy,
dott. Piergiorgio

1 Like

This is now posted on the I6 web site:

https://inform-fiction.org/manual/I6-Addendum.html

It’s linked from the front page (https://inform-fiction.org/) and a couple of the DM4 index pages (https://inform-fiction.org/manual/download_dm4.html). The temporary URL at the top of this thread is gone now.

Further updates are easily managed; I intend to keep this page up to date as new I6 features are added.

Thanks for the comments and suggestions.

2 Likes