Comments in Extension Documentation

[capmikee]

I think someone else was complaining about this, but I’m not sure where the thread is.

I’m trying to write documentation for my extension, and I came up with a couple of problems:

1. I couldn’t find anything in Writing with Inform about how to make the examples pastable. I had to look in the source of another extension to see that you need to start it with the string “*:”. Is that documented somewhere? It really should be.

2. I tried commenting my example by unindenting the comments. That looks right in the documentation window, but it defeats the pasting feature - when you click the paste button, you only get the text from the start of the example to the first comment. The built-in examples don’t have this limitation, do they? I thought when you pasted them, the unindented text turned into bracketed text.

3. Checking how your extension documentation looks (and if your examples run correctly) is even more tedious than forcing it to recompile. In fact, at one point I was so stumped that I quit Inform and restarted it, just to see how the changes to my extension documentation looked. Is there a way to get the documentation to reload? I can’t figure it out.

[Erik_Temple]

@capmikee

I think someone else was complaining about this, but I’m not sure where the thread is.

Maybe you’re thinking of this, from the uservoice site?

@capmikee

2. I tried commenting my example by unindenting the comments. That looks right in the documentation window, but it defeats the pasting feature - when you click the paste button, you only get the text from the start of the example to the first comment. The built-in examples don’t have this limitation, do they? I thought when you pasted them, the unindented text turned into bracketed text.

You’re right: the examples in the manual don’t face this limitation. There’s another difficulty as well–for some reason, bracketed text in extension documentation is stripped out when the docs are rendered into HTML. So you can’t include straightforward pastable comments in your example code either.

In the uservoice thread linked above, Emily explains that there is extra markup in the manual examples that allows for the more sensible treatment of comments in that context. For now, the solution (workaround, really) is to use multiple paste blocks. This is less than ideal, though, because users may not realize that they need to do this (the WI examples having trained them that only one paste operation is needed); it’s also annoying to have to click multiple paste buttons, and if you prefer to read the comments in the source window (where tables look better, for example), you’re out of luck, because comments can’t be pasted.

There are potentially at least two ways to fix this problem:

1. Allow extension authors to use the same markup that is available for the manual examples.
2. Allow text in brackets to appear in the documentation HTML and to be pasted along with the example source.

I’d be happy with either, but I think 1 is a better option from the point of view of predictability–users will have the same experience pasting an example whether it comes from the manual or from an extension.

@capmikee

3. Checking how your extension documentation looks (and if your examples run correctly) is even more tedious than forcing it to recompile. In fact, at one point I was so stumped that I quit Inform and restarted it, just to see how the changes to my extension documentation looked. Is there a way to get the documentation to reload? I can’t figure it out.

I think someone mentioned here recently (or maybe on uservoice) that there is a key combination or something that will do this, at least in the Mac IDE. Maybe it was EmacsUser…?

–Erik

[eu1 (eu)]

Yes, that was me. Right-click and select ``reload’’ after recompiling a story that includes the extension. The relevant UV suggestion is at inform7.uservoice.com/forums/573 … on-compile.