[move this line to the end of the source and it will no longer compile.]
A reward is a kind of thing. A punishment is a kind of thing.
The player carries a reward called a Christmas present. The player carries a punishment called a lump of coal.
There is a woman called Little Sally in the living room.
Instead of giving a reward to sally:
say “Oh, thank you Santa!”;
Instead of giving a punishment to sally:
say “Sally bursts into tears.”;
[/code]
But if I put the definitions of reward and punishment at the end, the compiler can’t find them anymore:
Is this how things are supposed to be, or is it a bug?
Inform is pretty tolerant about the order of code in a lot of cases, but kind definitions aren’t one of them. If you don’t declare what a “reward” is before you define an object that is a reward, Inform doesn’t know what you’re talking about.
It’s covered in the manual if you’re adept at reading between the lines and using a little imagination, yes. The example that the manual gives doesn’t quite spell out the problem that Mikee ran into. The example shows an object being successfully created, but not being what you expected.
It’s easy to reproduce the problem by adding this to the example in the manual:
[code]In the Crypt is an open coffer called the vampire’s resting place.
A coffer is a kind of container.[/code]
My own feeling (and yes, I’ve written manuals) is that a manual should always provide every detail that may be needed. A manual should not skimp. Inform’s manual not infrequently takes the opposite tack. Presumably in the interest of brevity, so as not to intimidate the novice with thorny details, it sometimes fails to explain important stuff.
I think of the O’Reilly Learning X/Programming X manuals in this situation. The “introductory” manual doesn’t give you all the details, but it’s enough to get you started. It’s intended to be read once, as a tutorial. Then the detailed manual can be used as a reference - it never needs to be read straight through, because the introductory manual should teach you how to find things in it.
Maybe the Recipe Book is aiming to be the reference - I haven’t read enough of it to know for sure yet.
Where does your Handbook lie in relation to these examples, Jim? I started reading it, but it seemed more like an introduction and less like a reference, and I really need a reference right now.
The Handbook (which in any case hasn’t been updated to cover 6E72) is not a reference, no. It’s a “here’s how to do useful stuff” guide.
I’ve only glanced at Aaron’s book, so I can’t say how well it would meet that need.
The Recipe Book is definitely not a reference either.
I’d like to see the existing “Writing with Inform” significantly expanded, to cover numerous details that are now being swept under the rug. But it would be difficult for a 3rd party to do the rewrite, because of the way the underlying HTML is structured. What appears in the IDE as a single page is actually several pages that are kept in sync somehow during rewrites. Each time you open a different example within a page, you’re switching to an entirely new HTML page that has the same basic text, augmented by the text in the example.
This has to be a headache to maintain. I’m pretty sure there are easier ways to do it in HTML. I’ve never asked why they did it that way.
Ron Newcomb has written a document called, I believe, “Inform 7 for Programmers.” But it’s not exactly a reference either.
If someone would like to give the Handbook more reference-like features … hey, go for it! The .odt file is available for download from my web page. Naturally, I’d appreciate being kept in the loop, but you’re free to do what you like, as long as you credit me for my work.
How adept at reading between the lines do you have to be? You’re given these statements:
and
It seems like a very simple 2+2 to take these two statements and conclude that you need to declare the kind ‘reward’ before using it. The only issue is knowing the first statement exists, which is why I pointed the original poster to the correct place in the documentation.
I agree that no reading between the lines is necessary in this case. But finding the relevant information in the documentation remains a challenge.
In regards to the introduction/tutorial model, it occurred to me that Kernighan & Ritchie does a great job at being both. It doesn’t hurt that C is a very straightforward language, but being well organized and having a good index helps too. After reading many computer manuals, (and trying to write a little documentation), I’ve realized how hard that is to do. The Inform manual doesn’t really have an index, just a keyword search. I don’t like the keyword search because it hits so many irrelevant sections. A topic search, or even an anachronistic browsable Index, would go a long way towards making things findable. But fundamentally I think the ordering of chapters and the placement of information within them is deeply sub-optimal. Even within a single section, I think the presentation of information could often be improved:
The list of headings and the information about their hierarchy are in two separate paragraphs. Why not write something like this?
Taking a more general view is harder for me, but I’ll make an attempt: I’m not sure The Source Text should be chapter 2 at all, and I’m not sure the sections of Chapter 2 even belong together. A lot of this stuff (like use options) could be dealt with much later. To get started with a simple game, you don’t need headings or use options. This seems to be a chapter about syntax, but shouldn’t the syntax of each kind of statement belong in a chapter about that statement?
“Things” sounds more like a chapter that should come first, but even there I see something strange. Section 3.5 is called “Kinds.” That’s the name of the next chapter! If I’m looking through the contents, which of these sections should I read to learn about kinds of things? Maybe kinds should come before things? Maybe they should be in a chapter together?
After Things, I would expect to see Actions. But there are two chapters I have to read first before I get there, Text and Descriptions. Are those really chapters about things? Maybe the chapters need to be grouped into parts (why is part above chapter and section below chapter? I never get that one right.) Text looks like a combination of things we need to know really early on (maybe even before Things!) and stuff that I really don’t want to look at right at the beginning.
5.2 is “How Inform reads quoted text” - very important! So important, in fact, that the first line acknowledges that we had to cover some of this in Chapter 2 already. 5.2 introduces the syntax for text substitutions - but those were introduced in 5.1, “Text With Substitutions.” Already we’re caught in a maze of twisty little cross-references.
Then in the same chapter we have Unicode. Certainly relevant to quoted strings, and perhaps to names of things in the source, but definitely not as fundamental as Things and Actions, and it could come much later, in a more reference-oriented section of the manual. There’s already a split-up chapter for Advanced Text… oh wait, that’s a chapter about indexed text. Why doesn’t it say so?
Sorry, I’m getting out of control here… I hope I’m not sounding too cranky. Say, does Inform need volunteers to help with writing the next edition of the manual?
