Looking at p. 16.4 of Writing with Inform, I find this:
That seems quite straightforward. But when I run the example game embedded in that page, which contains Table 4 - Recent Monarchs, here are the results:
Is this a mistake in the manual, or am I just being dense, as usual?
The showme verb prints information on an object in the model world. The showme phrase prints information on an object, value, anything you like. Since Inform doesn’t have parsing capabilities for most of those, this is only usable in your source code, not typed into the game at runtime.
When play begins:
showme the contents of table 4.This really ought to be explained on that page, oughtn’t it? Especially given the context – “It’s intended for authors to see when testing, not for players to see.” The showme command is quite explicitly used during game testing, NOT when writing code that will run in debug mode only, for testing purposes.
It’s also the case (I just tested it) that using showme in source code does NOT do the same thing as the showme command used during game testing. Really, it ought to.
But the important thing, with respect to peering at the contents of a table, is that scissoring the showme phrase into source code in order to examine the contents of a table and then recompiling is not a step that ought to be necessary. The showme command is a debugging command; as such, it ought to be able to spot table names.
The good news is, the #ifdef ideas Erik Temple has recommended for inserting non-release code into games aren’t actually necessary, because the phrase showme in source code does nothing in the release version. I just tested that too.
Every gray-boxed phrase you find in the Inform documentation is a phrase to be used in the code–in fact that’s the technical meaning of “phrase” as explained in WI §2.2. The SHOWME command is introduced in §2.7 (not in a gray box) and the showme phrase is introduced in §11.4 and distinguished from the SHOWME command. That’s not to say that it might not sometimes be nice to have a brief note explaining the difference when a new use of the showme phrase occurs, but the information is in Writing with Inform (and in section titles, so it’s even easy to find as those things go). It probably would be a little clearer to add to the end of the sentence you mentioned “…so this phrase will do nothing in the release version of the game” or something like that.
Letting the SHOWME command spot table names as well as things in the world would require a prohibitive amount of parser hacking, I’m pretty sure. The command runs through the parser with all the associated reliance on the dictionary–if you look at the dictionary table names are not a kind that can be understood by the parser.
Maybe impractical, but it would still be a nice feature.
I think my underlying observation is that the documentation simply assumes that everybody reading it will understand at a glance that the word “phrase” has a particular, restricted meaning in Informese. Clearly, this is not the case. I’ve written and released two games in I7, and I had forgotten that (if I ever knew it).
The fact that the phrase is differentiated from the command on 11.4 is, I think, irrelevant. People who write manuals quite often seem to assume that the reader will read the manual from front cover straight through to back, as if it were a novel (and remember everything that was read) – but that’s almost never the case. Indeed, part of my motivation for writing the Handbook in the first place was that I felt Writing with Inform needed more cross-referencing.
“Impractical” is understating it. From my poking around in the parser I think you would have to do something like the following:
–have a “showme [number]” command for every kind, like “number,” that can be understood by the parser
–have a “showme [text]” command to trap kinds like table names that can’t be understood by the parser
–autogenerate some kind of list of texts to match against the texts that get caught by the “showme [text]”
–actually do the comparison in a way that doesn’t require the author to type things out character-for-character
–probably something similar for variables? After all you can do “showme the match list” in code, why not as a debugging command, if we have that?
–probably need something to account for things whose internal names are different from their understood names (otherwise we’ll have a situation where “showme the bread knife” might work in code but not at the command prompt, if the bread knife is privately named or some such)
–other stuff, probably
As for the documentation, I agree that it could use more cross-referencing. I don’t think the “phrase” business is crucial, it’s that stuff in gray boxes is consistently code. In this particular case where there is a command that’s very similar to a bit of code it might be worth reminding the reader that they’re two different things.