I would like very much to read a complete, detailed description of how the default rules can be altered. Is there such a document? It’s clearly not a topic that’s covered in the Documentation. In the Docs we get snippets of this and that – basically what Graham or Emily thinks it would be most useful for us to know. But the important general concepts are generally NOT included in those pages. Or anywhere else, as far as I’m aware.
If there’s a solid general discussion of this topic that I can read, I won’t need to keep pestering y’all with my one-off questions. At the moment I’m running afoul of the “describe what’s on scenery supporters in room descriptions rule”, but there’s no point in explaining the problem if I can find the solution by reading something.
I mean I think it’s basically just as laid out in 19.5. Changing the behaviour of rules? You either remove a rule or substitute a new one, and do that either globally or under specific conditions.
I find the rub is really knowing what the standard rules are, so you can effectively monkey around with them. Here, I know the intent is for the new documentation to make that easy, but I find Zed’s page laying out the rules an indispensable resource.
I’ll try to say this without sounding snarky, but I’ll probably fail. The page you refer to, 19.5, begins with the following sentence: “Here is another way to abolish an already-existing rule:” I think it is surely quite apparent that a complete discussion of a particular functionality cannot possibly begin with the phrase “here is another way.” The text on that page, I’m sorry to say, is yet another example of a terribly incomplete discussion that tries to bottle-feed the infant author rather than presenting information in a way that would be useful to adults.
Well, it refers back to the previous section (which is about how rules are listed in rulebooks), since it wraps up with ways of delisting a rule so it doesn’t show up in any rulebooks. That’s technically different from altering a rule, so I guess that’s the logic of separating things in different sections?
Honestly while there’s definitely stuff I think the documentation isn’t good at, in this case I’m not sure I see much to kick it about – letting rulebook-listing syntax stuff leak into a section that’s about altering rule behavior seems like a bad, confusing outcome, so unless the docs were set up just dump entire chapters on users without the fine-grained sectional approach currently taken, I don’t see how you can avoid these kinds of issues, and this kind of explicit cross-referencing flagging potentially-relevant stuff in the previous or next section seems like the best you can do.
There’s no such document. After reading your I7 Handbook, and Aaron’s book, and Writing with Inform, you pore over the examples, and the Standard Rules, and the Template Layer, and this forum (I’ve learned a lot from Brady Garvin who hasn’t even been here for 8 years), and the DM4 'cause important subjects like how the parser and scope work boil down to “they work like in I6 except for where they don’t”, and Ron Newcomb’s Original Parser and Inform for Programmers, and other people’s extensions (Glimmr Canvas Animation has amazing stuff about properties you won’t find elsewhere), and the source of existing games (Counterfeit Monkey is especially rewarding, for programmers as well as its players). And ask questions here. And experiment and get used to being surprised any time you look really closely at a topic…
I’ve tried to at least provide pointers to the most important resources on The Inform 7 Documentation and Resources post. And while I appreciate Mike’s kind words, my webified Standard Rules and I6 Template Layer are a lot less relevant in a world where the v10 Basic Inform and v10 Standard Rules extensions and the v10 Kits are online. (I had finished the polished version of the Templates 3 weeks before I realized v10 was imminent – sigh. I suppose there’d be some value in having a single-page version of Basic Inform and the Standard Rules and an index to the kits, though.)
Not by a country mile. There is no explanation of anything in the Standard Rules. Not one word. It’s not a tutorial document. What I’m looking for is a tutorial document – a single long chapter that explains, in detail, exactly how everything works when it comes to altering the default behavior of the library.
I didn’t think so, but I felt it would be polite to ask. The thing is, writing a game in I7 is just not fun. It starts out being fun, but it quickly morphs into a morass of pain and confusion. And why would I do it if it’s not fun?
There are two basic reasons for the descent into the maelstrom. First, some of the syntax is one-off. Second, the Documentation is scattershot rather than comprehensive. It seems clear to me that, as a whole, Inform 7 is designed in such a way as to attract the novice IF author by making it appear to be easy to write games. This is true both of the language syntax and of the documentation. As a result, you can do simple stuff quite easily, but the moment you start trying to do anything sophisticated in order to produce a game transcript that reads fluidly, you’re on your own.
Another factor is that the library is not exactly readable. In TADS 3, the library is written using exactly the same syntax that the author uses in writing the game. (Also, it’s really, really thoroughly commented!) As a result, reading the library code to find out what you need to change is much more practical. Also, Eric Eve’s documents are well written and thorough.
It’s too bad there’s no Mac IDE for T3. That has, I think, been a roadblock in the way of its attractiveness as an authoring system. I do like the I7 IDE for the most part – it’s easily the most attractive feature of the system.
On the other hand, putting the whole of the author’s work in a single file (story.ni) was a terrible design decision. It’s much easier to find various blocks of code in the T3 IDE, because you can create as many separate files as you like. In a large game (I’m already at 34,000 words and maybe a quarter of the way through it), the I7 Contents tab is no substitute, because there are easily a hundred items in the Contents tab, and in order to find something you have to scroll up and down through a display text that lacks highlighting or color-coding.
I dunno, I think this might just be about different languages, and different approaches to documentation, being better-suited to different kinds of people? I find writing Inform 7 games really fun (I’ve done two, both in the ~80k-90k word range) and while I have pain points, the fact that the docs aren’t comprehensive in the way you mention and that there’s some irregular syntax in some areas don’t rate very highly (the fact that some stuff is inaccessible unless you venture into the here-be-dragons waters of Inform 6 is probably the biggest!)
But partially I think that’s because I’m very much an inductive, not a deductive, thinker – I actively prefer the examples plus conversational documentation approach to one that relies on long, comprehensive reference docs, since it much better matches how my brain works (the cycle @rileypb mentions above makes total sense to me). I’m a lawyer by training, not a programmer, so perhaps this common-law-ish approach to coding just fits with how I think when I’m not writing IF!
(I’m also really happy I don’t need to break my code up into different documents – I know that’s how programmers like to work these days, but for me personally, having to juggle a bunch of different sub-files and make a ton of decisions about where particular pieces should go, then have to revise those decisions after I get halfway through and the structure shifts, would be unfun in the extreme! But again, I’m used to CTRL-Fing my way through really long text documents with lots of sections and subsections and subsubsections providing structure, while highlighting and color-coding are alien to how I’m used to working)
Anyway, not to negate your experience in the slightest – it’s clear I7 kinda sucks for you in many ways – much less drag the thread into another iteration of the I7 is great/awful wars, but I do think it’s interesting to think about why different folks have such different experiences with it.
I would say that’s an important factor, yes. I’m what I call a top-down learner. In learning a foreign language, for instance, I want to read a clear explanation of the grammar. Trying to learn a foreign language by immersion (which is a popular method) drives me absolutely nuts. It’s a terrible way to learn! And I do sort of mean “terrible” in an objective sense, but this is not the place to try to explain that.
The other factor that I think plays into my response to I7 is that I’m a professional writer. (Or was. I’m retired.) I have a strong desire to make things read a certain way, and I have a low tolerance for things like default messages that just aren’t quite right. If it doesn’t read smoothly, I absolutely need to fix it. And when I try to fix it, I find myself swimming upstream against Inform’s approach, which it’s pretty clear is aimed at helping novices get started with writing IF.
I’m sure that has been part of Graham’s mandate, as he conceives of it, from the very beginning. The intent of Inform 1 through 6 was to make use of the Z-machine because it was already installed on thousands if not millions of computers. This fact gave authors a large ready-made reader/player base, And with I7, he was trying to build a new programming language that aspiring authors would find more approachable than something with a C-like syntax.
I don’t fault him for having that as an objective! And to a considerable extent, it’s clear he succeeded. The popularity of I7 proves it. But there’s only so much that one unpaid developer can do, even with thoughtful input from people like Zarf and Emily, which I’m sure he has had on an ongoing basis. As a result, some of the decisions he made along the way are, shall we say, debatable. Nor are they undoable. At this point they’re pretty much baked into the system.
What would it take to make a comprehensive tutorial of the standard rules?
On the note of multiple documents, using extensions particular to a specific project might help.
I know when I make a very large map, I actually create a “Room Index” containing all the rooms, connections and descriptions, to help me stay organized. I just include the index as an extension… though I’m not sure if that method will still work with 10, it’s been a good workaround for me with some of the more complicated parts of the code in previous versions.
I’m truly not trying to be a smart-aleck when I answer: a comprehensive reference manual for I7, including the standard extensions and kits. That would be the prerequisite basis for anyone to write a comprehensive tutorial. Without it… well, they’d never actually know how comprehensive their tutorial was, for one thing.
So, not trying to be smart-alecky either, what would it take then, to make that since the documentation we currently have, isn’t that?
Edit to add: I’ve always personally been fond of the conversational tone that the built in documentation has. I’ve read the thing cover to cover like a novel a couple of times because of it. I’d really like a version of that kind of documentation for stuff like Unity or Unreal, but I understand that it left out a significant amount of the built-in stuff a beginner doesn’t need to worry about.
I can’t say that I can relate to everyone’s complaints about the documentation in this particular instance. Chapter 19 of the documentation goes over all the ways in which you can remove or replace existing rules. (§19.4 explains how to place rules in a particular order, as well as how to replace or outright remove rules; §19.5 shows the more fine-grained approach of replacing or disabling rules only under certain conditions.) As for knowing which rules to replace, you can use the RULES command or the relevant pages of the Index. (I’m surprised nobody has mentioned the Index yet! Check/Carry out/Report rules are listed on the details page of the action they apply to, all other rules are shown in the “Rulebooks” section.)
The sections that make up part of the language definition can get pretty arcane, yes (but v10 moves those into the “Basic Inform” extension). I’ve always found the set of rules surrounding the standard actions to be pretty readable.
But, then again, I too prefer the conversational style of the I7 documentation over a dry technical reference manual, so perhaps it’s no surprise if I tell you that I always found T3’s documentation to be lackluster at best. (The things that Eric Eve covers in his manuals are very readable, but somehow he always glosses over the points that I’m looking for.)
well, TADS’s documentation mapped well-enough the complexity of the library (but I’m sure that people involuntary “reinvent the wheel” where the “wheel” is a function of method buried in the depths of T3’s library reference (hence my appreciation of Jim Nelson’s adv3/adv3lite periplus…) ) but the same can’t be sayed about I7, albeit the huge effort of documenting in the /docs directory is laudable, albeit I’m still at a loss in navigating it…
I7 being a “natural” language, ought to have a “natural” documentation, that is, a “Inform 7 dictionary” (not to be confused with the same-name section of the Index) whose elencate the words understood by I7 (for example, in the WI 11.1 we read that “Inform provides about 60 built-in text substitutions.”, but I still haven’t found a complete list of all those three or so score of text substition, and what they does (and text substition is where I7 excel thanks to the rather complete array of substitions…)), followed by an elencation of all the standard library’s rulebook (more akin to the well-known “C library reference” than TADS3’s library reference), ordered by category and alpha.
Reference Dictionary is the day-to-day reference of both writer and developers, and the Infocom Imps teached us that both human and machine dictionaries are useful for Imps, whose are both writer and coders.
this is my answer to the documentation issue, on the altering the default rules, indeed knowing what rules is and what does shows the need of adequately comprehensive and indexed documentation.
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.