Merge pull request #1472 from klembot/develop

2.8.0
klembot · Nov 27, 2023 · ba52b37 · ba52b37
2 parents b86f316 + d36cec7
commit ba52b37
Show file tree

Hide file tree

Showing 168 changed files with 16,474 additions and 42,566 deletions.
diff --git a/docs/en/src/README.md b/docs/en/src/README.md
@@ -56,4 +56,4 @@ In order to use Twine most effectively, you should spend some time reading the d
 - [Snowman](https://videlais.github.io/snowman/2/)
 - [SugarCube](http://www.motoslave.net/sugarcube/2/)
 
-You might also find the [Twine Cookbook](https://twinery.org/cookbook) useful to read. It contains example code and explanations for things Twine authors often want to do.
+You might also find the [Twine Cookbook](https://twinery.org/cookbook) useful to read. It contains example code and explanations for things Twine authors often want to do.
diff --git a/docs/en/src/SUMMARY.md b/docs/en/src/SUMMARY.md
@@ -16,6 +16,7 @@
 	- [Archiving and Exporting Stories](story-library/exporting.md)
 	- [Deleting Stories](story-library/deleting.md)
 	- [Tagging Stories](story-library/tagging.md)
+	- [Changing the Library's Location](story-library/location.md)
 - [Editing Stories](editing-stories/index.md)
 	- [Navigating the Story Map](editing-stories/navigating.md)
 	- [Undoing and Redoing](editing-stories/undoing.md)
@@ -34,6 +35,7 @@
 	- [Proofing a Story](publishing/proofing.md)
 	- [Playing a Story](publishing/playing.md)
 	- [Publishing a Story](publishing/publishing.md)
+	- [The Scratch Folder](publishing/scratch-folder.md)
 - [Managing Story Formats](story-formats/index.md)
 	- [Viewing Story Formats](story-formats/viewing.md)
 	- [Changing the Default Story Format](story-formats/default.md)
@@ -44,6 +46,7 @@
 	- [How Twine Manages Story Format Versions](story-formats/versions.md)
 - [Customizing Twine](customizing/index.md)
 	- [Setting Preferences](customizing/preferences.md)
+	- [Command-Line Switches](customizing/command-line.md)
 	- [Advanced Customization](customizing/advanced.md)
 - [Limitations](limitations/index.md)
 	- [Large Stories](limitations/large-stories.md)
@@ -57,4 +60,5 @@
 	- [If An Error Message Appears While Editing](troubleshooting/error-message.md)
 	- [If Twine Won't Start](troubleshooting/wont-start.md)
 	- [If Twine Lost Your Story](troubleshooting/lost-story.md)
-	- [If Your Story Is Damaged](troubleshooting/damaged-story.md)
+	- [If Your Story Is Damaged](troubleshooting/damaged-story.md)
+	- [If You See Visual Glitches in Twine](troubleshooting/visual-glitches.md)
diff --git a/docs/en/src/customizing/advanced.md b/docs/en/src/customizing/advanced.md
@@ -15,7 +15,7 @@ features.
 Here's a sample `user.css` that replaces the graph paper background of the story
 map with a plain gray color:
 
-```
+```css
 .passage-map {
   background: hsl(0, 0%, 75%) !important;
 }

diff --git a/docs/en/src/customizing/command-line.md b/docs/en/src/customizing/command-line.md
@@ -0,0 +1,129 @@
+# Command-Line Switches
+
+This page only applies to app Twine.
+
+In addition to preferences you set through Twine's user interface, you can
+customize app Twine's behavior through command-line switches. These change
+Twine's behavior in only the session you launch with these switches. They don't
+change preferences you have set using other methods.
+
+## Setting Command-Line Switches
+
+The way you set command-line switches depends on what operating system you use.
+
+### Linux
+
+These are set in the command that launches Twine. If you are launching Twine via
+a terminal session, you'd add them to that command. If you are launching it
+using a desktop environment like Gnome or KDE, check to documentation for your
+desktop environment for directions.
+
+### macOS
+
+There are two ways to accomplish this:
+
+- Launch Twine using the Terminal application and add the switches to the end of
+  the command launching Twine. You will need to invoke the Twine executable
+  directly, like this:
+
+```
+/Applications/Twine.app/Contents/MacOS/Twine --switch --switch2
+```
+
+- Create an AppleScript that runs the command for you. See [this StackOverflow
+  post](https://superuser.com/a/16777) for details.
+
+### Windows
+
+There are two ways to do this:
+
+- Launch Twine using the Command Prompt or Console application. Add switches to
+  the end of the command launching Twine, like this:
+
+```
+C:\Program Files\Twine\Twine.exe --switch --switch2
+```
+
+- Edit the shortcut that you use to launch Twine, or create a new one. Add
+  command-line switches to the end of the _Target_ field of the shortcut dialog,
+  following the example above.
+
+Although some applications on Windows use `/` to start command-line switches,
+Twine doesn't. It uses `--`, the same as on other operating systems.
+
+## A Reminder About Spaces and Pathnames
+
+Many command line switches used by Twine set pathnames for folders. If a folder
+in the path you want to set contains a space, you must put quotation marks
+around the entire path, like so:
+
+<code>&#x2011;&#x2011;scratchFolderPath="C:\Users\Jane Doe\twine-scratch"</code>
+
+## Backup Folder Switches
+
+### <code>--backupFolderPath=_[path]_</code>
+
+Example: <code>&#x2011;&#x2011;backupFolderPath=/Users/janedoe/twine-backups/</code>
+
+This sets the full pathname of the backup folder to use. Twine will create this
+folder if it doesn't already exist. If Twine isn't able to do this, or isn't
+able to read the files in this folder, it will show an error message whenever it
+tries to save a backup of your story library.
+
+**Never set your backup folder to a folder that has files created by other
+applications in it.** Twine can't distinguish between backups it created and any
+other files, and **will delete them permanently** when they become too old.
+
+## Graphics Switches
+
+### <code>--disableHardwareAcceleration=_[true or false]_</code>
+
+Example: <code>&#x2011;&#x2011;disableHardwareAcceleration=true</code>
+
+This disables hardware accelerated graphics in Twine. This should only be needed
+if you experience visual glitches in Twine. Disabling hardware acceleration will
+likely make Twine less performant in general.
+
+## Story Library Folder Switches
+
+### <code>--storyLibraryFolderPath=_[path]_</code>
+
+Example:
+<code>&#x2011;&#x2011;storyLibraryFolderPath=/Users/janedoe/twine-stories/</code>
+
+This sets the full pathname of the story library. For example,
+<code>&#x2011;&#x2011;storyLibraryFolderPath=/Users/janedoe/twine-stories</code>.
+Twine will create this folder if it doesn't already exist. If Twine isn't able
+to do this, or it isn't able to read the files in this folder, it will show a
+dialog box where you can choose to either use the default folder instead, or to
+quit the app.
+
+## Scratch Folder Switches
+
+You can use a different location as your scratch folder, or change the length of
+time Twine keeps files around for in the scratch folder. For example, if your
+main storage volume is a solid state drive and you'd like to avoid writing to
+it, you can use a different volume.
+
+### <code>--scratchFolderPath=_[path]_</code>
+
+Example: <code>&#x2011;&#x2011;scratchFolderPath=/tmp/twine-scratch</code>
+
+This sets the full pathname of the scratch folder to use. If this folder doesn't
+already exist, Twine will try to create it. If Twine is unable to create the
+folder at the path you've set, it will show an error message when you play,
+test, or proof a story.
+
+**Never set your scratch folder to a folder that has files created by other
+applications in it.** Twine can't distinguish between files it created and any
+other files, and **will delete them permanently** when they become too old.
+
+### <code>--scratchFileCleanupAge=_[number]_</code>
+
+Example: <code>&#x2011;&#x2011;scratchFileCleanupAge=60</code>
+
+This sets how old a file must be before Twine deletes it from the scratch
+folder, in minutes. Twine considers the last time the file was modified, not
+when it was created, when deciding whether to keep the file. To have Twine
+delete all files from the scratch folder every time you quit it, set
+<code>&#x2011;&#x2011;scratchFileCleanupAge=0</code>.
diff --git a/docs/en/src/customizing/index.md b/docs/en/src/customizing/index.md
@@ -1,3 +1,3 @@
 # Customizing Twine
 
-This section describes how you can customize Twine to fit your needs.
+This section describes how you can customize Twine to fit your needs.
diff --git a/docs/en/src/customizing/preferences.md b/docs/en/src/customizing/preferences.md
@@ -45,4 +45,4 @@ and JavaScript edit dialogs.)
 - The _Custom_ font setting allows you to specify any font that's installed in
   your computer. You _must_ spell this font name exactly right, including any
   spaces or other symbols in the font name. Capitalization doesn't matter when
-  setting a custom font.
+  setting a custom font.
diff --git a/docs/en/src/editing-stories/changing-story-format.md b/docs/en/src/editing-stories/changing-story-format.md
@@ -5,4 +5,4 @@ tab. There's a menu in the dialog that opens that allows you to set a different
 format.
 
 Story formats must be [installed in Twine](../story-formats/adding.md) before
-they appear in this menu.
+they appear in this menu.
diff --git a/docs/en/src/editing-stories/deleting.md b/docs/en/src/editing-stories/deleting.md
@@ -6,4 +6,4 @@ shortcut.
 
 Deleting passages can be undone using [the buttons in the corner of the top
 toolbar](undoing.md). (So can almost all actions in the Story Map screen, but
-because deleting stories is permanent, it's worth calling out here.)
+because deleting stories is permanent, it's worth calling out here.)
diff --git a/docs/en/src/editing-stories/editing-passages.md b/docs/en/src/editing-stories/editing-passages.md
@@ -62,7 +62,7 @@ are true:
 - It is linked to from another passage
 - It has any tags
 - It has a different size than the default
-- It is the story start 
+- It is the story start
 
 ## Text Formatting, Code, Images, Sound, Video... Basically Everything Cool
 

diff --git a/docs/en/src/editing-stories/finding-replacing.md b/docs/en/src/editing-stories/finding-replacing.md
@@ -33,4 +33,4 @@ has a good introduction to the topic.
 If you use regular expressions in your search, the _Replace_ field can also
 contain backreferences. For example, if you enter `(.)and` in the _Find_ field
 and `$1---` in the _Replace_ field, the text `Sand band` will be replaced to
-`S--- b---`.
+`S--- b---`.
diff --git a/docs/en/src/editing-stories/index.md b/docs/en/src/editing-stories/index.md
@@ -2,4 +2,4 @@
 
 When you edit a story from the Story Library screen, it will take you to a view
 of the story called the Story Map screen. You'll probably spend most of your
-time in Twine here.
+time in Twine here.
diff --git a/docs/en/src/editing-stories/linking-passages.md b/docs/en/src/editing-stories/linking-passages.md
@@ -43,4 +43,4 @@ that use story format-specific functionality, like code.
 It's possible to use more than plain text as the trigger for a link, but how
 this works is dependent on the story format you are using. It's often possible,
 for example, to enter an HTML `<img>` tag in the label part of a link. But this
-may or may not be supported by the story format you are using.
+may or may not be supported by the story format you are using.
diff --git a/docs/en/src/editing-stories/navigating.md b/docs/en/src/editing-stories/navigating.md
@@ -23,7 +23,7 @@ text field.
 This will open a dialog with a search field. Enter either the name of a passage
 or some text it contains, and a list of matching passages will appear. Twine
 uses fuzzy matching, so you don't have to enter the passage name exactly, and it
-will find close matches if you make a typo. When deciding which pasages match
+will find close matches if you make a typo. When deciding which passages match
 what you've typed, it slightly prefers matches in a passage name to what's in
 passage text.
 

diff --git a/docs/en/src/editing-stories/renaming.md b/docs/en/src/editing-stories/renaming.md
@@ -5,4 +5,4 @@ top toolbar. The only restriction on story names is that they must be unique
 among your library.
 
 You can also rename a story [in the _Story Library_
-screen](../story-library/renaming.md).
+screen](../story-library/renaming.md).
diff --git a/docs/en/src/editing-stories/selecting.md b/docs/en/src/editing-stories/selecting.md
@@ -27,4 +27,4 @@ each story in your library, so one story can use grid snapping while another
 doesn't.
 
 Grid snapping only affects passage cards when you move them. It doesn't affect
-the existing position of cards.
+the existing position of cards.
diff --git a/docs/en/src/editing-stories/stats.md b/docs/en/src/editing-stories/stats.md
@@ -11,4 +11,4 @@ _Story_ top toolbar tab. This shows:
 
 IFIDs are akin to ISBNs for books. They help catalog Twine stories alongside
 other forms of interactive fiction. You can learn more about IFIDs at [the
-Interactive Fiction Database](https://ifdb.org/help-ifid).
+Interactive Fiction Database](https://ifdb.org/help-ifid).
diff --git a/docs/en/src/editing-stories/undoing.md b/docs/en/src/editing-stories/undoing.md
@@ -13,4 +13,4 @@ When you leave the Story Map screen, either going to a different screen in Twine
 or closing the application entirely, your undo history is discarded.
 
 If the undo or redo button is disabled, that's because there's nothing to undo
-or redo yet.
+or redo yet.
diff --git a/docs/en/src/getting-started/basic-concepts.md b/docs/en/src/getting-started/basic-concepts.md
@@ -42,8 +42,9 @@ _library_ for short.
 
 If you're using browser Twine, the library is stored invisibly in your browser's
 storage. However, if you're using app Twine, you'll find your library in a
-folder named Twine in your documents folder. Or use the _Show Story Library_
+folder named _Twine_ in your documents folder. Or use the _Show Story Library_
 menu item in the _View_ menu of Twine's main menu bar (not the top toolbar).
+[This location can be changed](../story-library/location.md).
 
 Your library belongs to just you, regardless of whether you're using app or
 browser Twine. You can't share it directly with other people, but you can
@@ -76,7 +77,7 @@ for others.
 
 Twine includes four story formats when you download it, and it is possible to
 [add other story formats](../story-formats/adding.md) that people in the
-community have made. 
+community have made.
 
 - [**Chapbook**](https://klembot.github.io/chapbook/) is the youngest story
   format. It's designed to be easy to learn and to make many common tasks people

diff --git a/docs/en/src/getting-started/downgrading.md b/docs/en/src/getting-started/downgrading.md
@@ -41,4 +41,4 @@ uses.
 
 You may also need to [reset your preferences](../troubleshooting/wont-start.md).
 Although the instructions linked are for the most recent version of Twine, they
-will probably work with most older versions of Twine as well.
+will probably work with most older versions of Twine as well.
diff --git a/docs/en/src/getting-started/getting-around.md b/docs/en/src/getting-started/getting-around.md
@@ -59,4 +59,4 @@ Dialog boxes have a few controls in their title bar:
 
 You can have as many dialogs open as you have room onscreen for. Right now, the
 order of dialogs can't be changed, nor can their position onscreen be changed.
-The width of dialogs can be changed in [preferences](../preferences).
+The width of dialogs can be changed in [preferences](../preferences).
diff --git a/docs/en/src/getting-started/index.md b/docs/en/src/getting-started/index.md
@@ -1,4 +1,4 @@
 # Getting Started
 
 This section describes Twine from the ground up: how to start using it and basic
-concepts that are key to understanding how it works.
+concepts that are key to understanding how it works.
diff --git a/docs/en/src/getting-started/installing.md b/docs/en/src/getting-started/installing.md
@@ -92,4 +92,4 @@ your platform (Linux, macOS, or Windows).
     Directly](../troubleshooting/local-storage.md). Local storage is similar to
     browser cookies, which you might be more familiar with, but cookies are
     limited to 4 KB of storage, whereas local storage can hold megabytes of data
-    (the exact number is dependent on the browser).
+    (the exact number is dependent on the browser).
diff --git a/docs/en/src/getting-started/uninstalling.md b/docs/en/src/getting-started/uninstalling.md
@@ -11,4 +11,4 @@ you're using.
   to uninstall it.
 - On macOS, delete the Twine app from your Applications folder.
 - On Windows, right-click the Twine entry in your Start menu and choose
-  _Uninstall_.
+  _Uninstall_.
diff --git a/docs/en/src/getting-started/updating.md b/docs/en/src/getting-started/updating.md
@@ -2,10 +2,10 @@
 
 ## Browser Twine
 
-Browser Twine is updated whenver there's a new release, so there's no work for
+Browser Twine is updated when there's a new release, so there's no work for
 you to do to stay up-to-date. If you need to use an older version, go to
-https://twinery.org/[version number]. That is, to use 2.3.13, go to
-https://twinery.org/2.3.13. These different versions will use the same story
+`https://twinery.org/[version number]`. That is, to use 2.3.13, go to
+`https://twinery.org/2.3.13`. These different versions will use the same story
 library and preferences.
 
 Keep in mind, though, that earlier versions will have bugs the most recent
@@ -18,4 +18,4 @@ To check if a newer version of Twine is available, choose _Check for Updates_
 from the menu named _Twine_ in the menu bar (not the top toolbar). Twine will
 tell you if there's an update available and, if you like, will direct you to
 where to go to download the new version. Twine doesn't automatically update
-itself.
+itself.
diff --git a/docs/en/src/limitations/collaborating.md b/docs/en/src/limitations/collaborating.md
@@ -15,4 +15,4 @@ If you're using app Twine, using cloud storage services like Dropbox or Google
 Drive to sync your story library is not recommended. It is very easy for these
 services to get confused as to the state of your story files--they often try to
 merge changes from different sources together on your behalf--and cause your
-stories to become corrupted.
+stories to become corrupted.
diff --git a/docs/en/src/limitations/combining.md b/docs/en/src/limitations/combining.md
@@ -16,4 +16,4 @@ files, using a notation called
 If you want to have multiple, separate story files that communicate with each
 other in some way--say, for an episodic game--then how you might do that is
 specific to the story format you are using, so check its documentation for
-details.
+details.
diff --git a/docs/en/src/limitations/index.md b/docs/en/src/limitations/index.md
@@ -1,4 +1,4 @@
 # Limitations
 
 Twine, like any piece of software, isn't perfect. In this section, some
-limitations of Twine are described as well as possible ways to work around them.
+limitations of Twine are described as well as possible ways to work around them.
diff --git a/docs/en/src/limitations/large-stories.md b/docs/en/src/limitations/large-stories.md
@@ -5,7 +5,7 @@ number of passages, amount of text, or number of links.
 
 If you're using browser Twine, you are limited by the amount of storage space
 your browser allows Twine. You can see the amount of space available as a
-percentage in the corner of the Story Library screen. 
+percentage in the corner of the Story Library screen.
 
 If you're using app Twine, you're limited by the amount of space on your
 computer, but you're very unlikely to be limited by this in practice.
@@ -18,4 +18,4 @@ more. As a result, it's hard to advise specific actions if you notice that Twine
 is sluggish with your story.
 
 One possibility, though, is to [split your story](./combining.md) into multiple
-stories. 
+stories.
diff --git a/docs/en/src/limitations/multimedia.md b/docs/en/src/limitations/multimedia.md
@@ -21,4 +21,4 @@ preview it with the multimedia files.
 It is possible to use [Base64
 encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs)
 to embed multimedia directly into a Twine story, but this isn't recommended as
-it is difficult to work with and will make your stories much larger in size.
+it is difficult to work with and will make your stories much larger in size.
diff --git a/docs/en/src/limitations/source-control.md b/docs/en/src/limitations/source-control.md
@@ -10,4 +10,4 @@ stories difficult. Converting your stories to the plain-text Twee format before
 checking them into a source code repository can help with this. Command-line
 tools like [Tweego](https://www.motoslave.net/tweego/),
 [Extwee](https://github.com/videlais/extwee), and
-[twine-utils](https://www.npmjs.com/package/twine-utils) can do this for you.
+[twine-utils](https://www.npmjs.com/package/twine-utils) can do this for you.