Feature: Mechanism to exclude passages from published files

[klembot]

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

---

It would be nice if there were some mechanism to mark that a passage should not be published (whether actually publishing or testing/debugging), though it should still be stored to/restored from archives.

Twine 1 has the Twine.private tag to accomplish this.

In Twine 2, the feature could be a special tag or some kind of passage flag.

---

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

[klembot]

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

---

This is a thorny issue because a lot of Twine 2's design assumes that there is no source/publish distinction. I think it's a net positive that a published story can be moved back into the editor without loss of data (apart from trivial stuff like zoom level -- I know you had mentioned this in another issue).

We could certainly have passages marked as "do not publish", but that would also mean "do not archive" which I think would cause users to shoot themselves in the foot, not understanding the implication.

I have idly considered a "strip" utility for Twine 2 which would erase all dev-related info from a Twine 2 story (e.g. passage positions), but I feel like that is something that should be unofficial.

[klembot]

Original comment by Leon Arnott (Bitbucket: L, GitHub: Unknown):

---

FWIW the main reason I intentionally left annotations in the compiled HTML file is for insurance if the original .tws is lost (which happens more often than you'd think) - as the annotations are essentially the "comments" of the story's code, having them retained when retrieving a story from built HTML is something of a boon. It can be combined with Twine.private if its contents really mustn't get into the public's hands.

WRT the topic at hand: I think bringing back special tags for this sort of functionality would be a good idea, insofar as I can't currently think of a more elegant way to attach special metadata to passages.

[klembot]

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

---

I was thinking about it mostly for notations, yes. However….

In Twine 1, the annotation feature (tag really) only makes fat passages (by fat, I mean they are 4× the size of normal passages), which is nice in a passage which is meant to be a developer note (since, hopefully, you can read it from the story map). It does not, however, cause those notational passages to be excluded from the compiled/published files. (I've seen authors write significant notes in those things, and they really don't need to be copied into the published files.)

Anyway, if the annotation feature did both in Twine 2, then that would fill the bill nicely, yes.

[klembot]

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

---

I've considered adding the annotation functionality from Twine 1 -- perhaps this would get at what you're thinking of?

[Philip-Sutton]

Seven years on (!) I'd like to argue in favour of this proposed enhancement. I've belatedly transitioned this year to Twine 2.3.15/SugarCube 2.36.1 (desktop on windows) from Twine 1.4.3 so the issue has come up for me now.

The main way that I use Twine is to create interactive educational tools where the interaction is not just between the reader and the twine story but between the reader and the developers of the twine story. The stories invite real life feedback from the readers to the story developers and the stories are updated constantly in the light of that feedback and further learning by the developers. Given this process of constant upgrading, it is valuable to store draft improvement ideas in the story file that they relate to - in non-printing (unlinked) passages. Though most readers are unlikely to look inside the output .html file, it is easier for the developers to feel free to say whatever they want in the hidden development passages without having to be concerned about it being read by some end users.

--

I've read all the comments related to this issue (#103) and they make really important points. I now agree that the full content of the developer version of Twine 2 stories should be saved into the archive files - private comments and all.

Chris suggested the idea of creating a strip utility to run using the archive file. This functionality exist. Thomas says that it is possible to run Twine 2 html files through Tweego and this will strip passages that have a Twine.private tag.

In my use case I need to update stories on the web very frequently so the time taken to run a strip utility becomes significant.

With all this in mind, I think an ideal set-up would be to have two methods for saving stories built into Twine 2:

• to create archive files with complete content (as occurs now)
• to create stripped files (minus private passages and minus within-passage comments that are marked up with a special 'private' comment code.)

So in my use case I would save stories twice to create a full archive file and a stripped file that would then be loaded to the web.

[greyelf]

note: I agree in principle that there is a need for a feature like the one described in this Issue.

Two potential issues I see for the storage of "exclude passages" are:

1. Currently in the Desktop release (of the application) a Story Project HTML file is basically just a 'published' HTML file saved in a location pre-determined by the Desktop application. That application's 'automatic backup' system does something similar.
2. The "Import from File" feature is often used be end-users to recreate a Project from a 'published' Story HTML file when the original Project was lost for some reason, like the Desktop release's ability to lose Projects or the flushing of the Local Storage of the web-browser being used for the Web-browser release of the application.

So if the behaviour of a Project file to also containing the associated Story Format template is to continue the 'build' process would need to be changed so that it knew when to build a "publish like" file that includes the "exclude passages", and when not build one that doesn't.

And how will these "exclude passages" be recreated when a Project is lost for some reason?

[Philip-Sutton]

I agree that the default behaviour for developing Twine projects should be to create archive files with all the content (public and private).

I also agree that the Twine developer environment should warn developers about the risk of creating project files that have confidential material stripped - so that developers know that the confidential material cannot be recovered from a stripped file (tautological - but nevertheless something that needs to be reinforced in the mind of developers.

The risk entailed in creating a stripped file exists currently for those who know they can use Tweego to do the job.

I've revised my suggested design for the exclusion of confidential information from specialised stripped output files to take account of the issues that everyone has raised:

• a settings menu item is added to the right hand panel of the Twine 2 story list screen
• in 'settings' (as above) an option is included to activate the production of 'stripped' output files - with the developer presented with a warning of the risk entailed in creating stripped files before the option is activated.
• once the creation of stripped files is activated then the option to do this is added to the project specific action options in the Story list screen and the project map screen
• inside the stripped .html file (in commented text) there should automatically be a statement that the file has been stripped of private information and that accessing the private information will require the use of a standard archive file.
• there will need to be a special passage tag and within passage comment markup that relates exclusively to private (confidential) information so that normal non-printing passages and in-passage comments are retained in the stripped output file while the confidential passages and comment lines are removed.

[HiEv]

I don't really see an elegant solution to the problem of storing/hiding/not including notes from within the Twine editor. Most people either just keep their notes in a separate file or put it in a passage that's not connected to anything.

That said, I do see a fairly simple solution by doing things slightly differently: create a custom proofing format which stores notes based on IFID. It would keep the notes entirely separate from the Twine file itself, but allow you to access the notes for any story from the Twine editor with only a click or two. You'd also want to have a mechanism in the proofing format to export/import the notes and possibly browse other stories' notes, but it solves all of the other complexities discussed above.

Perhaps as an update to the Paperthin proofing format? (Which, I'll be honest, I never use. I tend to have Illume as my default proofing format.)

[Philip-Sutton]

A further suggestion.....

Context: Chris said: " I think it's a net positive that a published story can be moved back into the editor without loss of data". I strongly agree with this.

Chris said: "I have idly considered a "strip" utility for Twine 2 which would erase all dev-related info from a Twine 2 story (e.g. passage positions), but I feel like that is something that should be unofficial." I think we could build on this approach.

So here's my suggestion: Why not treat a strip utility a bit like a story format? ie. it could be optionally loaded into twine.

I would suggest that if it is loaded, that twine always auto-generates two files into the same folder - one would be the current archive file and the other file would be the stripped file that would be given a name in this sort of format: "story-name"-stripped.html

In this way the stripped file is marked with a 'warning'

The advantage that I see in this approach is that the production of the stripped file is fast, it guarantees that the archive file is produced or is not accidentally lost, and it marks the stripped file with a warning, and by making the strip utility an addon it is clear that it is modifying the core twine function so needs to be thought about carefully like we have to do when a choosing story format.