Export formats

[klembot]

Originally reported by: Thomas M. Edwards (Bitbucket: tmedwards, GitHub: tmedwards)

---

What it says on the tin. A format type which, upon Publishing to File, would see its output saved to disk, rather than the current template replacement model used by story formats. Though, being able to view an export format's output via Play would still be useful for spot checking or what have you, so that should continue to work.

This would allow something like Entweedle, for example, to publish twee source to disk, rather than having to copy/paste from its rendered HTML—which is problematic for anything more than trivial projects.

I'm not only thinking of Twee format exports here, a generic exporting method would be a nice addition, so a new format type would be better than a built-in feature—not to say that an official Twee export format couldn't be bundled. (For this reason, I do not believe this to be a duplicate of issue #41)

---

• Bitbucket: https://bitbucket.org/klembot/twinejs/issue/289

[klembot]

Original comment by mcdemarco (Bitbucket: mcdemarco, GitHub: mcdemarco):

---

No, window.close didn't work for me. It's more of a timing issue than a security issue; there's no callback or hook for determining that the download is done, except possibly in Chrome.

I'm not sure how the browser forcing a download in most cases (except, of course, Safari) is making people figure out downloading. If you want to try out the idea, or just leave it out there as a workaround until further development occurs, I put a twee exporter and saver-as-text proofing format up at https://mcdemarco.net/tools/entwee/format.js.

Example inconsistencies: when Playing or Testing a Snowman or SugarCube 1 story I get the same result (though it's not clear this actually the same, nor is it 100% obvious that when I download I will get the same thing as when I played), but playing and testing are different for Harlowe. I had it in my head for some reason that Test would give me a proofing copy, and when looking at a node or two of a test story in Snowman, it's not so clear that I'm not looking at a proofing copy because the play version is fairly plain, too.

[klembot]

Original comment by Chris Klimas (Bitbucket: klembot, GitHub: klembot):

---

@mcdemarco: Any chance that window.close() works? I forget what the rules are for when browsers will allow that, but if it works, it would prevent extra windows from lying around.

I think enscree is an interesting hack given the current limitations of Twine, but I agree with @tmedwards that we can do better, and we shouldn't make people have to figure out the ins and outs of file saving in a browser. I also like the idea of letting external scripts work directly with Twine story data because I think it would enable a lot of interesting tweaks. It's would kinda be like Babel or PostCSS for Twine.

The lack of proofing download is actually a great example of that. I haven't had the wherewithal to re-implement RTF export, so that's why there hasn't been an option to download proofing copies; you'd end up with an HTML file and a lot of confusion for users. I know Microsoft Word can open HTML, but I'd much prefer something agnostic like RTF. Anyway, this sort of functionality would allow people to write an RTF exporter.

I'm against formats manually indicating they should download as plain text because it feels limiting. What if a "format" wants to output SVG instead, or some other format? I guess I'd suggest a MIME type instead, but I'd have to think through all the ramifications.

The UI would definitely need to be clear about what is going on. Perhaps it wouldn't even draw a distinction on the user side.

We're drifting offtopic slightly here, but what inconsistencies do you see in playing/testing? Everything should appear in a new tab or window except when you choose "Publish to File".

[klembot]

Original comment by mcdemarco (Bitbucket: mcdemarco, GitHub: mcdemarco):

---

I wasn't suggesting that every export format do its own thing; I was only explaining how "the issue Entweedle can't work around" can in fact be worked around. If that's the only concern, then a new version of Entweedle (marked as a proofing format so no one would accidentally publish it in an unusable form) would address it with a lot less coding.

To expand on the rest of my comment, I think of exports as proof-like and I already find the various proof/publish/test/play options somewhat confusing, since none of them actually download in my browser, and they can do strangely different things depending on the version of Twine 2, whether I'm on the desktop or my browser, and/or the story format chosen. So adding a third type, export formats, seems more cluttering than helpful to me. On the other hand, a format type devoted to exports would make it clearer that exporting is possible--but it could also lead to the expectation of being able to import twee files.

Proofing formats suffer from the lack of a download option (as far as I can tell), so rather than add a very similar notion of export format (that would need a download option somewhere) on top of story and proofing formats, one could add the functionality of downloading/"exporting" a proof, plus a format variable to indicate that a format is intended to be rendered as plain text (and the back end support for that).

[klembot]

Original comment by Thomas M. Edwards (Bitbucket: tmedwards, GitHub: tmedwards):

---

I hardly think that we want every "export format"/"exporter"/whatever doing its own thing in regards to saving. That is a detail which easily can, and most definitely should, be handled by Twine 2.

[klembot]

Original comment by mcdemarco (Bitbucket: mcdemarco, GitHub: mcdemarco):

---

I made a format based on Entweedle in order to make a small alteration to the twee format (different formatting of passage titles) that I needed, and because it was more convenient to download as text I found a workaround to do that. The compressed code is at mcdemarco.net/tools/scree/enscree/format.js, and the relevant bit expanded is this:

#!javascript

            convert: function() {
                var output = this.export();

                var blob = new Blob([output], {type: "text/plain;charset=utf-8"});
                saveAs(blob, "enscreed" + Date.now() + ".txt");
            },

It uses a polyfill for saveAs, FileSaver.js (https://github.com/eligrey/FileSaver.js/), which I load in the header. It ideally forces a file download of a plain text blob, but in some circumstances only loads the text blob in a new browser window, which the user can then save. But there's no cutting and pasting involved. I wasn't sure the polyfill would work in the native apps, but I tried the Mac one I built from head last week sometime, and it downloaded fine (though it leaves a blank window behind--I'd recommend offsetting new windows in the native app to make it clearer the original program window is still open and running).

I set my format to a proofing format rather than a story format (like Entweedle is) since that seemed more accurate. I don't know that you really need a third category; I think a second axis (of whether to read/play in the current browser or download a file) would be clearer.

[klembot]

Original comment by Thomas M. Edwards (Bitbucket: tmedwards, GitHub: tmedwards):

---

I think maybe an easier-to-implement approach would be to give the format the passage data, say, as a JavaScript object, and then allow it to process it before being saved. […]

Assuming I understood that correctly, that's more or less what I had in mind.

[klembot]

Original comment by Chris Klimas (Bitbucket: klembot, GitHub: klembot):

---

I think maybe an easier-to-implement approach would be to give the format the passage data, say, as a JavaScript object, and then allow it to process it before being saved. (Or maybe not even call it a format but an exporter.)

To expand on TME's point for future readers (including myself): the issue Entweedle can't work around is that when you save a story with it, it saves an HTML page that renders Twee source, not actual Twee source, which adds extra steps to a workflow.