flow: Merged <release> 'v2.2.0' to <master> ('default').

Author: mcdemarco

.flow

@@ -0,0 +1,7 @@
+[branchname]
+hotfix=hotfix/
+develop=develop
+master=default
+release=release/
+support=support/
+feature=feature/

README.md

@@ -6,15 +6,38 @@ To add DotGraph to Twine 2, use this URL (under Formats > Add a New Format): [ht
 
 To add DotGraph to Twine 1, create a new folder called `dotgraph` inside your targets folder, then download this file [https://mcdemarco.net/tools/scree/dotgraph/header.html](https://mcdemarco.net/tools/scree/dotgraph/header.html) and place it inside the `dotgraph` folder.  (See the Twine wiki for more information about installing and using story formats in Twine 1.)
 
+To use DotGraph to graph a published story, open an already-dotgrapphed story in a browser and add a question mark followed by the story's URL.
+You can also do this by typing in the URL at the DotGraph site [here](https://mcdemarco.net/tools/scree/dotgraph/#DotGraph.as.a.Service).
+
+## Notes
+
+The start node is double-circled, as are any unreachable nodes.  Traced nodes are hex-shaped.  When color is on, nodes that are linked but do not exist are colored white.  When color by length is on, all other nodes are colored in shades of red (shorter than average) to blue (longer than average) based on the relative length of their contents.
+
+The cluster and color by tag options use the first tag on each passage unless *Use last tag* is checked; optionally detected special tags are ignored in this ordering.  Optional detection of an "End" tag changes the shape of "end" passages to an egg (and puts diagonals on loose ends and disconnected nodes).  Optional detection of a "checkpoint" tag changes the shape of checkpoint passages to a diamond.  The omit by tag(s) option omits the passage regardless of tag order.
+
+Stray or misplaced nodes can result from the omit tags setting, or from duplicate passage names or other linking issues.
+
+The layout engine options change the graph style; some options are slower than the default ("dot").  Some options are only supported under the "dot" engine, such as clustering by tag and choosing the graph direction (the arrows).  You can find a [brief description (PDF)](https://graphviz.gitlab.io/_pages/pdf/dot.1.pdf) of the engines and fuller documentation for each one on GraphViz's [documentation page](https://graphviz.org/documentation/).
+
+The image format is SVG.
+
 ## Troubleshooting
 
 DotGraph may fail to draw the graph in some versions of Twine 2 due to issues with Chrome;
 in that case it will still give you the text of the dot source file, as well as some links to sites online that can render it for you.
 
 DotGraph may fail to save the SVG in Safari; if it fails, try a different browser.
 
+## SnowStick
+
+SnowStick is a bit of JavaScript and CSS you can add to stories that use Snowman-based story formats in order to track your reading/proofing progress and graph it with DotGraph.  It can also be used without DotGraph.  See [its separate README](snowstick/README.md) for more details.
+
 ## Versions
 
+### 2.2.0
+
+Add SnowStick (a reading tracker integrated with DotGraph), support for configuration using the DotGraphSettings passage (a safer and more flexible spot than StorySettings, though the latter is still supported), viewing another story by URL (a quicker way than by loading the story and this format into Twine), and Graphviz engine options (after updating to the latest [viz.js](http://viz-js.com) to fix some special character issues).
+
 ### 2.1.0
 
 Add a text tracing option and and support for configuration using the StorySettings passage.

grunt/build.js

@@ -42,7 +42,7 @@ module.exports = function(grunt) {
 		var data = {
 			name: '{{STORY_NAME}}',
 			passages: '{{STORY_DATA}}',
-			vizScript: '<script src="https://mcdemarco.net/tools/scree/dotgraph/viz.js" type="text/javascript"></script>',
+			vizScript: '<script src="https://mcdemarco.net/tools/viz/viz.js" type="text/javascript"></script><script src="https://mcdemarco.net/tools/viz/full.render.js" type="text/javascript"></script>',
 			script: '<script>' + grunt.file.read('build/dotgraph.js') + '</script>'
 		};
 
@@ -55,7 +55,7 @@ module.exports = function(grunt) {
 		var data = {
 			name: '{{STORY_NAME}}',
 			passages: '{{STORY_DATA}}',
-			vizScript: '<script>'  + grunt.file.read('lib/viz.js') + '</script>',
+			vizScript: '<script>'  + grunt.file.read('lib/viz.js') + '</script><script>'  + grunt.file.read('lib/full.render.js') + '</script>',
 			script: '<script>' + grunt.file.read('build/dotgraph.js') + '</script>'
 		};
 
@@ -68,7 +68,7 @@ module.exports = function(grunt) {
 		var data = {
 			name: 'DotGraph',
 			passages: '<div id="storeArea" data-size="STORY_SIZE" hidden>"STORY"</div>',
-			vizScript: '<script src="https://mcdemarco.net/tools/scree/dotgraph/viz.js" type="text/javascript"></script>',
+			vizScript: '<script src="https://mcdemarco.net/tools/viz/viz.js" type="text/javascript"></script><script src="https://mcdemarco.net/tools/viz/full.render.js" type="text/javascript"></script>',
 			script: '<script>' + grunt.file.read('build/dotgraph.js') + '</script>'
 		};
 
@@ -81,7 +81,7 @@ module.exports = function(grunt) {
 		var data = {
 			name: 'DotGraph',
 			passages: '<div id="storeArea" data-size="STORY_SIZE" hidden>"STORY"</div>',
-			vizScript: '<script>'  + grunt.file.read('lib/viz.js') + '</script>',
+			vizScript: '<script>'  + grunt.file.read('lib/viz.js') + '</script><script>'  + grunt.file.read('lib/full.render.js') + '</script>',
 			script: '<script>' + grunt.file.read('build/dotgraph.js') + '</script>'
 		};
 

lib/full.render.js

@@ -1,6 +1,6 @@
 {
   "name": "DotGraph",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A proofing format to make a Graphviz graph of a story.",
   "author": "M. C. DeMarco",
   "license": "MIT",

lib/viz.js

@@ -0,0 +1,77 @@
+# SnowStick
+
+SnowStick is a bit of JavaScript and CSS you can add to stories that use Snowman (or other story formats based on it), in order to track your reading/proofing progress and graph it with DotGraph.  SnowStick can be used without DotGraph, in which case you can still tell where you've been by the link styling (crossed-out for completed branches, squiggly underlining for previously visited links, and no alteration for unvisited links).
+
+## Installation
+
+### Twine 2
+
+1. Put the javascript from `snowstick.js` into your Story JavaScript using the Twine menu item *Edit Story JavaScript*.
+2. Set a mode manually at the top of the javascript (see below).
+3. Put the CSS from `snowstick.css` into your Story Stylesheet using the Twine menu item *Edit Story Stylesheet*.
+
+### TweeGo
+
+1. Save the files `snowstick.js` and `snowstick.css` to the directory that contains your story file(s).
+2. To change the mode, edit the configuration at the top of `snowstick.js` using your favorite text editor.
+
+### Twine 1 or Twee
+
+(This applies to any Twee processor, including TweeGo if you prefer to do it this way.)
+
+1. Put the javascript from `snowstick.js` into a passage tagged *script*.
+2. Set a mode manually at the top of the javascript (see below).
+3. Put the CSS from `snowstick.css` into a passage tagged *stylesheet*.
+
+## Mode
+
+SnowStick has two main `modes`, *proof* and *read*; you should set one at the top of the SnowStick JavaScript (where you can also set some minor configuration options):
+
+    var config = {
+      mode: 'read',
+	  openBookmark: true,
+      leafedMessage: ' (all children checked) ',
+	  tags: false,
+	  bar: false
+    };
+
+In *proof* mode:
+
+* the passage title, overall percentage read, and (optionally) tags appear in a footer, and a note appears when the branch is completely proofed; you can change the note using the `leafedMessage` option
+* the percentage can be replaced with a gradient bar by setting the `bar` option to *true*
+* the passage is only marked proofed when the footer checkbox is checked off.
+* the links are restyled according to whether they're completely new, already proofed, or completed.
+
+In *read* mode:
+
+* the percentage read is the only added UI element (hover on it for details, including optional tags);
+* the percentage can be changed from text to a bar by setting the `bar` option to *true*
+* the passage is automatically marked read when read.
+* the links are restyled according to whether they're completely new, previously read, or completed.
+
+There is also a *clear* mode for clearing all read data from the current browser.
+You can use this to start fresh on the current story, or to switch between Twine 1 stories. (See *Issues* below).
+
+In *off* mode, SnowStick is turned off (without uninstalling the code).
+
+## Bookmarking
+
+SnowStick will, optionally, start the story from the passage you left off at.  If the story format is managing your story state (or if state matters), you may want to turn this feature off by setting `openBookmark` to *false*.  You can switch it on and off again as necessary to restart the story.
+
+## Issues
+
+SnowStick stores its data in your browser's localStorage, so for it to work you must open your story in the same browser and not clear or disable your browser's local storage while reading.  You can make changes to the story and republish it, however, without confusing SnowStick.  (If you change the IFID, it will be treated as a different story.)
+
+In certain cases, such as Twine 1 stories and other stories without IFID, SnowStick will need to be cleared between stories.  To read more than one such story at a time, use a different browser for each story (*e.g.,* Chrome vs. Brave).  (This is not a concern for Twine 2 stories that have distinct IFIDs.)
+
+The total passage count includes special and unreachable passages, so you may not hit 100%.
+
+## ToDo
+
+It would be nice to validate the current read/leaf lists against the full passage list (in case passage names change), but that could slow things down and should perhaps be a separate mode.
+
+## Versions
+
+### 0.1
+
+Betaish.

package.json

@@ -0,0 +1,70 @@
+/* SnowStick 0.1
+   supporting CSS for snowstick
+   see snowstick.js for details
+ */
+
+/* the footer only appears in proofing mode, not in reading mode */
+
+#snowstick-footer {
+    background-color: lightsalmon;
+    position: bottom center;
+    width:100%;
+    padding-left:3px;
+}
+
+.snowstick-bar #snowstick-footer {
+  background-color: white;
+  background-image: linear-gradient(to right, lightsalmon, white 1%);
+}
+
+#snowstick-name {
+    font-weight:bold;
+    font-style: italic;
+}
+
+/* the percentage read always appears; 
+   remove it by setting display to none instead of inline-block */
+
+#snowstick-percent {
+    display: inline-block;
+    float: right;
+}
+
+.snowstick-read #snowstick-percent {
+    color: darkslategray;
+    padding:3px 6px;
+    border: 1px solid slategray;
+    border-radius: 3px;
+}
+
+.snowstick-bar.snowstick-proof #snowstick-percent {
+    width: auto!important;
+}
+
+.snowstick-bar.snowstick-read #snowstick-percent {
+    display:block;
+    position:fixed;
+    left:0;
+    bottom:0;
+    height:2px;
+    width:1%;
+    background-color: rgba(204,136,41,0.45);
+    border: 0;
+    border-radius: 0;
+}
+
+/* styling of completed leaf nodes and of read (or proofed) nodes */
+
+body.snowstick a.snowstick-read {
+    text-decoration-style: wavy;
+    text-decoration-line: underline;
+    text-decoration-color: #cc8929;
+    border: none;
+}
+
+body.snowstick a.snowstick-leaf,
+body.snowstick a.snowstick-read.snowstick-leaf {
+    text-decoration-style: solid;
+    text-decoration-line: line-through;
+    text-decoration-color: black;
+}