Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0001925Documentation, Examples, and Web SiteWriting with Informpublic2016-06-22 06:192017-08-17 21:07
Reportermattweiner 
Assigned To 
PrioritynormalSeveritymildReproducibilityalways
StatusnewResolutionopen 
PlatformmacOSel c.OS Version10.11.4
Product Version6M62 
Target VersionFixed in Version 
Summary0001925: "item described" is incompletely documented
DescriptionThe phrase "item described" only appears twice outside of examples: In WwI 17.17 and in RB 2.2. In 17.17 it appears in a code snippet without explanation. In RB 2.2, the explanation is as follows:

Or, similarly, if we want some combination of categories and characteristics to be recognized:

Understand "giant" as a man when the item described is tall.
"The item described" here refers to the thing being named.

But this doesn't capture all the cases in which we use "item described" outside of Understand statements, such as

The initial appearance of a door is usually "Nearby [an item described] leads [if the other side of the item described is visited][direction of the item described from the location] to [the other side][otherwise][direction of the item described from the location][end if]."

(from example 64, "Whence?") And in any case it'd be good to have this in Writing with Inform somewhere.
Minimal Source Text To Reproduce
Type "item described" into the search box.
Additional InformationI have a fear that I will get a response similar to the response about "the person asked" (http://inform7.com/mantis/view.php?id=1910 [^]): that "item described" is only documented for Understand statements and using it as a generic alias for the thing we're talking about is unsupported.

If I get this response I will cry.

(After I'm done crying I will point out that "item described" is used outside of persuasion activities in a squillion examples and a megasquillion existing codebases, and that I'm unaware of any substitute that works at all--at least with "the person asked" you can substitute "the actor" a lot of the time.)
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0004479)
zarf (developer)
2016-06-22 12:48

"The item described" is kind of a mess. It *is* intended for use in text properties of objects -- that's how it's used in example 64. But documenting this concisely isn't easy! (I'm not even sure I understand all the details myself.)
(0004480)
zarf (developer)
2016-06-22 12:49

I agree that the manual needs more on the subject, however.
(0004482)
mattweiner (reporter)
2016-06-22 13:07
edited on: 2017-08-17 21:09

I guess one thing to say might be something along the lines of "When an object has a text property, we can use 'the item described' to refer to the object whose property it is"--and then an example? This might not capture all the uses of "the item described," but it would at least not be false, if I've written it right.

In general it seems like WwI doesn't take the approach that it's necessary to document everything completely, as you have observed with spacing, so IMO it'd be OK to just describe the main function and not all the details.

(Unrelated edit: Oh, and in the additional information I should have said that "the item described" is used outside of Understand statements, not outside of persuasion activities, though that comment is pretty moot anyway.)

(0004483)
zarf (developer)
2016-06-22 15:37

Here's where it gets messy:

The Kitchen is a room.

The monkey is in the Kitchen.

The description of the monkey is "'I am [a item described],' says the monkey."

Every turn:
	let T be the description of the monkey;
	say "T: [T]".


Result:

>x monkey
"I am a monkey," says the monkey.
T: "I am nothing," says the monkey.


The text isn't really functional on its own. The template layer handles "description" and "initial appearance" in such a way as to keep "item described" properly set, but in general it's fragile.
(0004484)
mattweiner (reporter)
2016-06-22 16:00

Weeeelll, I would argue that that isn't incompatible with the thing I said--when "'I am [a item described],' says the monkey." is being used as a property of the monkey (the description), then the item described is the monkey, but when you take that text out and use independently rather than as a property of the monkey, then the item described isn't the monkey anymore. Though I confess I don't have the faintest idea of what's really going on.

Hmm:
let T be the substituted form of "[description of the monkey]";
will give you "I am a monkey" etc., which is what I'd expect

but let T be the substituted form of the description of the monkey;
gives you "I am nothing" etc., which is not entirely what I'd expect--though I guess "substituted form" requires quotation marks to do anything?
(0004716)
neroden (reporter)
2017-08-16 20:33

Let me just say I agree with Matt 100%.

This is an invaluable piece of documentation which belongs somewhere, and I'm adding it to my long list of pieces of basic and fundamental Inform documentation which only exist in obscure forum posts, bug reports, etc.

Writing with Inform is arguably the single weakest point of Inform 7; it's terrible and doesn't qualify as a manual at all due to (a) leaving out most of the vital information and (b) being extremely poorly organized. It's often easier to read through the I6T template files and the Standard Rules than to find anything in the manual. It would probably be easier to read through the ni source code, if it were released.

I am considering writing an actual manual, but the closed-source nature of ni makes it an unattractive task.
(0004719)
mattweiner (reporter)
2017-08-17 21:07

I just went back and checked an older version--the issue is that in the 6G60 documentation, at least, "item described" was explicitly defined in WI ยง5.14, "Review of Chapter 5: Text," which began thus:

1. In phrases or text to say, text in square brackets will be treated as a substitution. The thing to be said might be the name of an object:

say "[a dog]".
Text in square brackets might also be a property:

The printed name of a lamp is usually "[brightness] lamp".
The initial appearance of a person is usually "You notice [the item described]".
***Here "the item described" refers to whatever object possesses the property in question.*** (emphasis added)

Subsequently those last "Review of..." sections for each chapter were eliminated, which in this case took out the definition of "the item described."

- Issue History
Date Modified Username Field Change
2016-06-22 06:19 mattweiner New Issue
2016-06-22 12:48 zarf Note Added: 0004479
2016-06-22 12:49 zarf Note Added: 0004480
2016-06-22 13:07 mattweiner Note Added: 0004482
2016-06-22 13:09 mattweiner Note Edited: 0004482 View Revisions
2016-06-22 15:37 zarf Note Added: 0004483
2016-06-22 16:00 mattweiner Note Added: 0004484
2017-08-16 20:33 neroden Note Added: 0004716
2017-08-17 21:07 mattweiner Note Added: 0004719
2017-08-17 21:09 mattweiner Note Edited: 0004482 View Revisions


Copyright © 2000 - 2010 MantisBT Group
Powered by Mantis Bugtracker