[I7-1970] [Mantis 2006] Documentation inside example in extension project causes miscompilation

[curiousdannii-testing]

Reported by : dfremont

Description :

In an example inside an extension project, having any non-indented text (which is displayed as explanatory text in the extension's documentation) causes Inform to not include any subsequent code in the "story.ni" file generated when you hit "Go!" or "Test".

I'm not finding where the fact that you're allowed to do this is discussed, but it's certainly helpful and is used by the WI Examples and some of the built-in extensions.

Steps to reproduce :

Test Extension by Blah begins here.
Test Extension ends here.

---- DOCUMENTATION ----

Example: * Foo - zog.

    *: "Foo"

    Blor is a room.

Blah blah blah.

    *: When play begins, say "Hooray!"

Additional information :

The generated "story.ni":

"Foo"

Blor is a room.

imported from: [Mantis 2006] Documentation inside example in extension project causes miscompilation

• status: Closed
• resolution: Resolved
• resolved: 2022-04-11T00:40:00+10:00
• imported: 2022/01/10

[curiousdannii-testing]

557058:4c095ffd-6d6f-47ce-9e73-77c613347b86:

Comment by mattweiner :
I don't think this is allowed--I recall one of the devs saying somewhere that the markup for WI Examples is more complicated than the markup you can do for extensions.

[curiousdannii-testing]

557058:4c095ffd-6d6f-47ce-9e73-77c613347b86:

Comment by mattweiner :
For what it's worth, I found the comment I was referring to:

https://inform7.uservoice.com/forums/57320-general/suggestions/849631--extensions-revise-extension-example-presentation

Emily says the examples in the main documentation have a different markup, in part because, unlike extension examples, they can be preprocessed. Perhaps built-in extension examples can also be preprocessed? I dunno.

The paste button for examples came from this suggestion of approximately the same vintage:
https://inform7.uservoice.com/forums/57320-general/suggestions/751728--extensions-examples-paste-button-for-extension-e
and maybe never got documented. I agree that that's a documentation bug, and that it also might be nice to have the distinction between author-written extensions and built-in extensions explained. Especially because sometimes we learn to format examples from the extension code (that's where I found out about "*:".)

(Also I should make it clear that I'm not speaking with any official authority here, I'm just going by what I saw on uservoice.)

...actually, which examples in the built-in extensions are you seeing that are formatted like the WI examples in this way? I just went through several and none of them had interrupted code like this. The "Watchtower" example in Locksmith looks like this, but it's actually two separate paste buttons (the code after the non-indented bit is optional, in case you don't want Leif to be able to unlock the door automatically).

[curiousdannii-testing]

557058:4c095ffd-6d6f-47ce-9e73-77c613347b86:

Comment by dfremont :
Perhaps, but as I mentioned this feature is already being used, e.g. in the built-in extension Locksmith by Emily Short. If this is not allowed it should be removed from the built-in extensions, and if it is allowed it should be described in WI 27.12.

In fact now that I look at WI 27.12 it doesn't even mention that you need a "*:" to get the code paste button to appear. Even if only one code section is allowed, that syntax needs to be explained (is it somewhere else and I just can't find it?).

[curiousdannii-testing]

61eedb62875fc10070240916:

Fixed via this commit: https://github.com/ganelson/inform/commit/5d6c6d073c52dab25e0ee7ba7488c08062081448

Comment from Graham Nelson:
Inform was behaving as intended, so in that sense this wasn't a bug, but I accept the point that the documentation does not explain this. I've added a passage to "Writing With Inform".