Altering the Default Rules: A General Question

At the risk of descending further into the endless I7-vs.-T3 debate, I’m shocked that you feel that way about Eric Eve’s writing. I agree with you that readable docs are very important – that was what first attracted me to I6 back in 1998! But I find Eric’s writing style extremely friendly and approachable. The Library Reference Manual is, of course, extremely dry, but it’s a reference system, it’s not properly a manual at all.

At a guess, it would take Graham Nelson about a year and a half, a tiny handful of other people two to two and a half years, and anyone else much longer than that. :slightly_frowning_face:

Sounds like we would need to put together a team to work on that project. I don’t want to put any more on Graham Nelson, since he’s already so busy.

Isn’t this provided by the Index? For example, those text substitutions are covered in Phrasebook > Saying, and the rulebooks are covered in Rules > Standards.

Now, I agree it would be nice to have a “default” index that you can access outside the IDE, without having to compile a game first (not least because I’m often specifically trying to check the index when my game won’t compile successfully…). But I’ve been quite happy with the Index as a reference in general.

What about making a “game” that acts like a reference, with rooms catering to specific parts of the standard rules, all referenced in the index.

That sounds like it could be informative… and not entirely unfun.

Nonono, Inform 7 is the game. As reviewed here:

Review: Inform 7 - The Interactive Fiction Community Forum (intfiction.org)

Well, that thread is informative and fun to read. I’m gonna have to rethink how I think of this program.

1 Like

I could put up a fully HTML-ified version of the Project Indices resulting from compiling “Lab is a room.” in both of 9.3/6M62 and 10.1 easily enough… the doc links wouldn’t be right for 10.1, though.

2 Likes

I for one would certainly find it useful!

Concur with Daniel: Zed, please put up this HTML version of the indices !

TIA and
Best regards from Italy,
dott. Piergiorgio.

(04:00 here in Italy; a long and satisfying night of TADS3 coding…)

Famous last words. A lot more absolute links than I remembered…

9.3/6M62 Project Index

Also, I possibly lied about how easily I could do 10.1. Oops.

3 Likes

yea. now Firefox’ search for .htm/.html on your initial commit (6ddbe651f99cdb94dc9df105e2293de7c7172823) got a CPU spike toward 100% on all four 2,8 Ghz cores and ending finding more than a thousand results…

Isn’t an easy work, but I think that perhaps is scriptable (sed, awk, even perl aren’t to be underestimated when automating find&replace…)

Best regards from Italy,
dott. Piergiorgio.

EDIT: I have DL that archive, and run this little unix plumbing:

rgrep ".htm" |grep -v "<html>" |grep -v "</html>" |grep -v "doctype" |less -N

whose gives a staggering 15232 hits (dunno if there’s still too many false positives, a good chunk is filtered out by the plumbing above, I think), so I guess that automating the work with a script IS needed…

a lot of perl -pi.bkp -e andfind with -exec was involved in munging the large number of file:/// URLs into relative URLs to get from what I started with to what I pushed to github. Some time after the v10 dust has settled, I’m going to sit down and redesign inf7, which generated the HTML of the Project Index and the docs, for v10. (I am using it with v10 today, but via some seriously ugly hacks. And I had mistakenly thought the Index format was so close to unchanged in v10 it would still work, but no.)

Currently in v10 the index module hard-codes HTML output. It would be cool if maybe someday there were formatting-agnostic plain-data output and then, by default, inweb could transform that into the Project Index as the IDEs expect it.

Agreed, I’ve always wanted to design a slightly more idiomatic version of the Index which isn’t so excruciating to navigate with a screenreader, this would help a ton.

2 Likes

In past I have copypasted from the IDE the actions/commands, ending in a grep-friendly list of verbs and synonyms, and I guess is also screenreader-friendly list:

"[direction]" - Going

"abstract", a testing command not available in the final game
"actions", a testing command not available in the final game
"adjust", same as "set" 
"answer [text] to [someone]" - Answering it that  (reversed)
"ask [someone] for [something]" - Asking it for 
"ask [someone] about [text]" - Asking it about 
"attach", same as "tie" 
"attack [something]" - Attacking 
"awake", same as "wake" 
"awaken", same as "wake" 

"break", same as "attack" 
"brief" - Preferring sometimes abbreviated room descriptions 
"burn [something]" - Burning 
"buy [something]" - Buying 

"carry", same as "take" 
"check", same as "examine" 
"chop", same as "cut" 
"clean", same as "rub" 
"clear", same as "push" 
"climb [something]" - Climbing 
"climb up/over [something]" - Climbing 
"close [something]" - Closing 
"close up [something]" - Closing 
"close off [something]" - Switching off 
"consult [something] on/about [text]" - Consulting it about 
"cover", same as "close" 
"crack", same as "attack" 
"cross", same as "enter" 
"cut [something]" - Cutting 

"describe", same as "examine" 
"destroy", same as "attack" 
"discard", same as "drop" 
"display", same as "show" 
"disrobe", same as "shed" 
"doff", same as "shed" 
"don", same as "wear" 
"drag", same as "pull" 
"drink [something]" - Drinking 
"drop [things preferably held]" - Dropping 
"drop [something preferably held] at/against [something]" - Throwing it at 
"drop [other things] in/into/down [something]" - Inserting it into 
"drop [other things] on/onto [something]" - Putting it on 
"dust", same as "rub" 

"eat [something preferably held]" - Eating 
"embrace", same as "kiss" 
"enter" - Entering 
"enter [something]" - Entering 
"examine [something]" - Examining 
"exit" - Exiting 

"fasten", same as "tie" 
"feed", same as "give" 
"feel", same as "touch" 
"fight", same as "attack" 

"get out/off/down/up" - Exiting 
"get in/on" - Entering 
"get [things]" - Taking 
"get in/into/on/onto [something]" - Entering 
"get off/down [something]" - Getting off 
"get [things inside] from [something]" - Removing it from 
"give [someone] [something preferably held]" - Giving it to  (reversed)
"give [something preferably held] to [someone]" - Giving it to 
"glklist", a testing command not available in the final game
"go" - Going 
"go [direction]" - Going 
"go [something]" - Entering 
"go into/in/inside/through [something]" - Entering 
"gonear", a testing command not available in the final game

"hear [something]" - Listening to 
"hit", same as "attack" 
"hold", same as "take" 
"hop", same as "jump" 
"hug", same as "kiss" 

"i", same as "inventory" 
"insert [other things] in/into [something]" - Inserting it into 
"inv", same as "inventory" 
"inventory" - Taking inventory 

"jump" - Jumping 

"kill", same as "attack" 
"kiss [someone]" - Kissing 

"l", same as "look" 
"leave", same as "exit" 
"light", same as "burn" 
"listen" - Listening to 
"listen to [something]" - Listening to 
"lock [something] with [something preferably held]" - Locking it with 
"long" - Preferring unabbreviated room descriptions 
"look" - Looking 
"look [something]" - Examining 
"look at [something]" - Examining 
"look inside/in/into/through [something]" - Searching 
"look under [something]" - Looking under 
"look up [text] in [something]" - Consulting it about  (reversed)

"move", same as "push" 
"murder", same as "attack" 

"nap", same as "sleep" 
"no" - Saying no 
"normal" - Preferring sometimes abbreviated room descriptions 
"notify" - Switching score notification on 
"notify on" - Switching score notification on 
"notify off" - Switching score notification off 
"nouns" - Requesting the pronoun meanings 

"offer", same as "give" 
"open [something]" - Opening 
"open [something] with [something preferably held]" - Unlocking it with 
"out", same as "exit" 

"pay", same as "give" 
"pick up [things]" - Taking 
"pick [things] up" - Taking 
"polish", same as "rub" 
"present", same as "show" 
"press", same as "push" 
"pronouns" - Requesting the pronoun meanings 
"prune", same as "cut" 
"pull [something]" - Pulling 
"punch", same as "attack" 
"purchase", same as "buy" 
"purloin", a testing command not available in the final game
"push [something]" - Pushing 
"push [something] [direction]" - Pushing it to 
"push [something] to [direction]" - Pushing it to 
"put on [something preferably held]" - Wearing 
"put [something preferably held] on" - Wearing 
"put down [things preferably held]" - Dropping 
"put [things preferably held] down" - Dropping 
"put [other things] in/inside/into [something]" - Inserting it into 
"put [other things] on/onto [something]" - Putting it on 

"q" - Quitting the game 
"quit" - Quitting the game 

"random", a testing command not available in the final game
"read [something]" - Examining 
"read about [text] in [something]" - Consulting it about  (reversed)
"read [text] in [something]" - Consulting it about  (reversed)
"relations", a testing command not available in the final game
"remove [something preferably held]" - Taking off 
"remove [things inside] from [something]" - Removing it from 
"responses", a testing command not available in the final game
"restart" - Restarting the game 
"restore" - Restoring the game 
"rotate", same as "turn" 
"rub [something]" - Rubbing 
"rules", a testing command not available in the final game
"run", same as "go" 

"save" - Saving the game 
"say", same as "answer" 
"scale", same as "climb" 
"scenes", a testing command not available in the final game
"scope", a testing command not available in the final game
"score" - Requesting the score 
"screw", same as "turn" 
"script" - Switching the story transcript on 
"script on" - Switching the story transcript on 
"script off" - Switching the story transcript off 
"scrub", same as "rub" 
"search [something]" - Searching 
"set [something] to [text]" - Setting it to 
"shed [something preferably held]" - Taking off 
"shift", same as "push" 
"shine", same as "rub" 
"short" - Preferring abbreviated room descriptions 
"shout", same as "answer" 
"show [someone] [something preferably held]" - Showing it to  (reversed)
"show [something preferably held] to [someone]" - Showing it to 
"showheap", a testing command not available in the final game
"showme", a testing command not available in the final game
"showverb", a testing command not available in the final game
"shut", same as "close" 
"sip", same as "drink" 
"sit on/in/inside [something]" - Entering 
"sit on top of [something]" - Entering 
"skip", same as "jump" 
"sleep" - Sleeping 
"slice", same as "cut" 
"smash", same as "attack" 
"smell" - Smelling 
"smell [something]" - Smelling 
"sniff", same as "smell" 
"sorry" - Saying sorry 
"speak", same as "answer" 
"squash", same as "squeeze" 
"squeeze [something]" - Squeezing 
"stand" - Exiting 
"stand up" - Exiting 
"stand on [something]" - Entering 
"superbrief" - Preferring abbreviated room descriptions 
"swallow", same as "drink" 
"sweep", same as "rub" 
"swing [something]" - Swinging 
"swing on [something]" - Swinging 
"switch [something switched on]" - Switching off 
"switch [something]" - Switching on 
"switch on [something]" - Switching on 
"switch [something] on" - Switching on 
"switch [something] off" - Switching off 
"switch off [something]" - Switching off 

"take inventory" - Taking inventory 
"take [things]" - Taking 
"take off [something]" - Taking off 
"take [something] off" - Taking off 
"take [things inside] from [something]" - Removing it from 
"take [things inside] off [something]" - Removing it from 
"taste [something]" - Tasting 
"tell [someone] about [text]" - Telling it about 
"test", a testing command not available in the final game
"think" - Thinking 
"throw", same as "drop" 
"thump", same as "attack" 
"tie [something] to [something]" - Tying it to 
"torture", same as "attack" 
"touch [something]" - Touching 
"trace", a testing command not available in the final game
"transcript" - Switching the story transcript on 
"transcript on" - Switching the story transcript on 
"transcript off" - Switching the story transcript off 
"tree", a testing command not available in the final game
"turn [something]" - Turning 
"turn [something] on" - Switching on 
"turn on [something]" - Switching on 
"turn [something] off" - Switching off 
"turn off [something]" - Switching off 
"twist", same as "turn" 

"uncover", same as "open" 
"unlock [something] with [something preferably held]" - Unlocking it with 
"unscrew", same as "turn" 
"unwrap", same as "open" 

"verbose" - Preferring unabbreviated room descriptions 
"verify" - Verifying the story file 
"version" - Requesting the story file version 

"wait" - Waiting 
"wake" - Waking up 
"wake up" - Waking up 
"wake [someone]" - Waking 
"wake [someone] up" - Waking 
"wake up [someone]" - Waking 
"walk", same as "go" 
"watch", same as "examine" 
"wave" - Waving hands 
"wave [something]" - Waving 
"wear [something preferably held]" - Wearing 
"wipe", same as "rub" 
"wreck", same as "attack" 

"x", same as "examine" 

"y", same as "yes" 
"yes" - Saying yes 

"z", same as "wait" 

If you have heard well, I think the issue is solved :wink:
sorry for the “talkfest” (the auditory equivalent of a “wall of text”) and

Best regards from Italy,
dott. Piergiorgio.

It’s a good reference, but it’s missing the links—part of why I find the index list useful is because it’ll also give me, for example, the full list of default rules for each action.

Agree on this, but in my case, I often need to look up what synonyms are implemented for a standard verb, and occasionally (remember, I’m Italian, english is a 2nd language…) finding the correct -ing, instead of correcting :wink:

Best regards from Italy,
dott. Piergiorgio.

Oh, Jim, you’re not wrong.

I’ve cursed (to myself) at Graham Nelson repeatedly over the years for writing an undocumented language.

Inform 7 needs a reference manual. It does not have one. Until this year when it was released as open source, it was impossible for anyone other than Graham and Emily to write one, and they didn’t bother to write one. Writing With Inform is no good. Yes, I have read the whole thing. It is severely insufficient. It does not do what it needs to do. It is a tutorial, but a tutorial is not sufficient for a language. A language needs a reference manual.

Maybe we can write one now.

Pros and cons of Inform 7:

I think the “natural language” thing is a mistake – it’s an unachievable and confusing illiusion. But I think the more verbose style (using words rather than punctuation – ALGOL rather than C !) and identifiers with whitespace were a good idea, so I don’t think this harms the language too much.

Hard tab indentation was a really bad decision. But a Python-style allowance for space-based indentation would rescue it.

The rules-based design is excellent and exactly what’s needed. The rule priority structure is superior to Dialog. Writing the individual rules imperatively is much easier for most people than the full rules-based design of Dialog, particularly when it comes to text gluing.

The text gluing and substitution is very strong. Though the newline systems are really weird. I think those can’t be fixed at this point but at least I documented them.

The lack of a reference manual, however, is crippling.

FWIW, it’s quite feasible to break a game into multiple files using extensions, which is what all the writers of large games did. It’s not encouraged by the IDE, unfortunately.

We would have to write the reference manual because Graham has been frankly unwilling to. Which is his right. He’s had years to do so, he knows perfectly well that it’s crippling to the language and infuriating to the users, and he hasn’t done it. Frankly he may not be constitutionally suited to writing reference manuals: the I6 Designer’s Manual turned out to be incomplete and missing information, as I discovered recently. We will have to do it, and it is now possible since the code has been open-sourced.

Documenting the actual I7 syntax and data types is probably the most critical part of a reference manual. I’ve been able to decipher everything in the Standard Rules. But there is quite a lot of utter weirdness in the I7 syntax where stuff which seems like it ought to work doesn’t. Zed has reported some of it as bugs. I haven’t sat down to decipher the syntax tables in the C source code for the Inform 7 compiler yet.

As a footnote, the DM4 was what convinced me I could write IF, back in 1998. Its tone is friendly and approachable. At the time I had no idea it was incomplete; it just suited my taste!

I think the I7 manual attempts to take the same tone. And it has the same attractive veneer! But because I7 is both deeper and more peculiar than I6, the I7 docs are, on the whole, less successful than the DM4. At least that’s my personal opinion.

My own Inform 7 Handbook is now rather out of date, and it’s certainly not a reference manual! It’s just an alternative approach to writing friendly documentation.

I have no idea how hard it would be to write a reference manual. I use the TADS/adv3Lite Library Reference Manual a lot, but nobody ever wrote it. It was assembled automatically using the comments in the source code as text. So I guess the first question I would have would be, now that I7+ is open-source, is the source code fully commented? I haven’t looked at it…

1 Like

While I7 definitely has its flaws, this seems unnecessarily ad hominem.

I know I’ve said this before, but I think the biggest issue with the natural language thing is that it’s billed as making the code easier to write.

It doesn’t. If you don’t know the exact wording the Standard Rules used to define a phrase, you need to look it up, just like you need to look up the argument order of strncmp if you forget where the length goes. (It goes at the end, which I have had to look up an embarrassing number of times. For some reason I always want it to come first.)

It makes the code easier to read. And that’s a big deal! Your average piece of code needs to be read many more times than it needs to be written, so making writing a little bit harder for the sake of making reading a lot easier is a good tradeoff.

I think the natural language side would be of more interest to your average programmer if this was emphasized more, because imo it’s I7’s single best selling point.

4 Likes