The manual says: “As these examples begin to show, Inform source imitates the conventions of printed books and newspapers whenever there is a question of how to write something not easily fitting into words.”
But how is “Your watch reads [time of day].” anything like the convention of a printed book or newspaper? And even if it is, why does it matter?
Another example given is how this:
“Simon says, ‘It’s far too heavy to lift.’”
Actually becomes this:
Simon says, “It’s far too heavy to lift.”
That’s more a convention of programming, not printed books and newspapers. I think the manual trips itself up sometimes, saying more where saying less would be better or saying something obliquely where a more direct route would be less ambiguous. That whole sentence from the manual doesn’t even need to be there. Unless there’s something I’m missing. Does the fact that Inform is said “to imitate the conventions of printed books and newspapers” matter in some broader context?
Then again, maybe it’s just poor wording? The full statement from the manual:
“As these examples begin to show, Inform source imitates the conventions of printed books and newspapers whenever there is a question of how to write something not easily fitting into words. The first example of this is how Inform handles headings, but to see why these are so useful we first look at Problems.”
So if the first example is in a section that follows, then “these examples” have NOT begin to show this, I guess.
And what would the convention of a printed book be? Text substitutions are rather Inform-specific.
And the second example is according to the conventions of the language. In English single-quotes are used whenever it is necessary to have quoted text within quoted text.
I think it is specifically referring to the “Simon says” example. In normal prose, when you quote a quote, you interchange single and double quotes. That is:
Simon actually said, “It’s far too heavy to lift.”
In my document about Simon, I wrote “Simon actually said, ‘It’s far too heavy to lift.’”
And I7 takes its cue from this in handling quote marks in the source text.
The square-bracket convention is standard for quotes, when the actual quote needs rewording but the editor wants to avoid misrepresenting the original.
But this seems like a needless correlation to introduce in the context of Inform. In Inform you are doing string interpolation or expression insertion. It has nothing to do with rewording direct quotes or anything like that. I don’t know. I guess I can see it, but I keep coming across areas in the Inform manual where I have to stop and say: “Wait? What? What does that have to do with anything?” Sometimes saying less truly is better and I think Inform sometimes tries to draw all these correlations with other writing mediums when, really, it doesn’t seem to matter all that much.
Ignore it if it’s not useful to you to know this, but for what it’s worth, this is Graham explaining the motive behind certain decisions. Not everything in Inform can correlate to examples in standard written text, it’s true; however, there were lots of times during the design process where we said, “okay, how do books present this kind of information? Does that offer a guideline that’s useful to us?”
I think it’s a matter of degree. That Inform takes any inspiration from the conventions of books is noteworthy enough, in comparison to other programming languages.
Still, as the old saying goes, you can write BASIC in any language, so press ahead with whatever style may please you, such as:
There is watch in room.
Time of day of watch is initially “9:02 AM”.
Carry out examining watch:
now examine text printed is true;
let x be text;
let x be "Your watch reads ";
let x be x + time of day of watch;
let x be x + “.”;
say x;
say line break;
To decide what text is (X - text) + (Y - text): decide on “[X][Y]”.
To me - someone with minimal non-IF programming experience - this would read as ‘in Inform you are doing flooberferwation and scumblebarengation.’ But ‘we use text in square brackets when we’re referring to the same thing but different wording, much like you do when you’re editing a quote’ is a pretty familiar concept, even if that’s not precisely what’s going on.
To 10 print (message - text) 20 goto 10:
say "[message][line break]";
10 print message 20 goto 10.
BASIC is a room.
When play begins:
10 PRINT "I am the best!!"
20 GOTO 10
BASIC is a room.
To (line - number) PRINT (msg - text): (- .basic_{line}; print (TEXT_TY_Say) {msg}; new_line; -).
To (line - number) GOTO (dest - number): (- .basic_{line}; jump basic_{dest}; -).
When play begins:
10 PRINT "Hello.";
20 GOTO 40;
30 PRINT "This is never printed.";
40 PRINT "Goodbye.";
Line numbers in this model are functional, and GOTO works as expected. The I6 compiler even checks for duplicate and missing line numbers at compile time. (But there’s no attempt to execute lines in line number order. They’re really just jump labels behind the scenes.)
Don’t go making infinite loops, hear, they sadden the IDE.
I get what you’re saying but just taking the above and reading it: I could argue that’s fairly confusing. Editing a quote? A non-programmer or non-writer may read that as something to do with quote marks in the source. When I read “same thing but different wording”, I don’t see that applying all the time. For example, from a learning perspective, that might not obviously explain this:
The watch says [time of day].
I would rather just say: “Square brackets are used when you want to insert information into the text. The text in the square brackets will not be repeated literally, but will instead be replaced by a particular value that Inform knows about. In this case, Inform keeps track of the time of day and will put whatever the current value is in place of [time of day].”
Or something like that. That’s a far cry from correlating that with “editing a quote” but, to your point, it also doesn’t bring up “string interpolation” or terms that might not be useful to non-programmers.
Maga’s example was meant to answer your question about how the syntax for string substitution was based on a convention used in print media. The section of the manual explaining these substitutions, starting at WI chapter 5 IIRC, is more along the lines of “text in square brackets is not printed literally, Inform substitutes in the appropriate string.”
I pointed out that the second is not necessarily a “familiar concept”. It might be to some, but then string interpolation is to some as well.
I do know that the manual eventually gets around to saying roughly what I said above. Actually, though, the manual says:
And here I would say “text substitutions” is a pretty good term. But that’s my point. My example about the newspaper/print correlation has to sit with the part I just quoted. Compare that also when the manual says:
Most likely people are used to the manual by now. I’m coming to this with fresh eyes so things are going to stick out to me.
So what you have (correctly) identified is that Inform, and the manual in particular, is not intended to be all things to all people, and that it’s primarily addressed to people more familiar with writing conventions than programming ones. (Programmers are more capable of fending for themselves in this kind of context.)
Fair enough. You make a good point. I guess I would argue there’s very little in the manual primarily addressed at people familiar with writing conventions of stories, which is what I presume we’re doing here. We’re not journalists nor writing newspaper articles. I guess it seems like the manual vacillates a bit between trying to be various things to various people. Maybe that’s been successful, though. I’m still learning and I’ll be the first to admit I tend to perhaps focus a bit too much on stuff that may not matter. Thanks for your insight.
