extwee 2.3.0 → 2.3.1

package/docs/README.md

@@ -1,4 +1,4 @@
-# Extwee
+<a name="readme-top"></a>
 
 [![codecov](https://codecov.io/gh/videlais/extwee/branch/master/graph/badge.svg)](https://codecov.io/gh/videlais/extwee)
 
@@ -8,13 +8,31 @@
 
 [![NPM Badge](https://nodei.co/npm/extwee.png?downloads=true)](https://www.npmjs.com/package/extwee)
 
+## Table of Contents
+
+<ol>
+  <li><a href="#story-compilation">Story Compilation</a></li>
+  <li><a href="#format-support">Format Support</a></li>
+  <li><a href="#usage">Node and Web API</a></li>
+  <ol>
+    <li><a href="#objects">Objects</a></li>
+    <li><a href="#parsers">Parsers</a></li>
+    <li><a href="#compilers">Compilers</a></li>
+  </ol>
+  <li><a href="#documentation">Documentation</a></li>
+  <li><a href="#command-line-usage">Command-Line Usage</a></li>
+  <li><a href="#config-file-usage">Config File Usage</a></li>
+  <li><a href="#escaping- meta-characters">Escaping Meta-Characters</a></li>
+  <li><a href="#license">License</a></li>
+  </ol>
+
 ## Story Compilation
 
-The process of *story compilation* converts human-readable content, what is generally called a *story*, into a playable format such as HyperText Markup Language (HTML) able to be read by another application such as a web browser. The result is then presented as links or other visual, interactive elements to a player or reader, depending on the work created.
+The process of *story compilation* converts human-readable content, what is generally called a *story*, into a playable format such as HyperText Markup Language (HTML). The result is then presented as links or other visual, interactive elements for another party.
 
-The term *compilation* is used because different parts of code are put together in a specific arrangement to enable later play. As part of Twine-compatible HTML, this means combining story format JavaScript code with story HTML data.
+The term *compilation* is used because different parts of code are put together in a specific arrangement to enable later play. As part of Twine-compatible HTML, this means combining JavaScript code (generally a "story format") with story HTML data.
 
-Extwee is **not** an authoring tool. It cannot be used to create story content. This data must be created using other tools or processes. Extwee can then *compile* the story with story format code to produce something playable.
+Extwee is **not** an authoring tool. It cannot be used to create story content. This data must be created using other tools or processes. Extwee can then *compile* the content with story format code to produce something playable.
 
 Playable formats are the following and require external story formats[^1] to enable play:
 
@@ -38,48 +56,22 @@ Twine 2 supports exporting a collection of stories (known as a *library*) in the
 
 ## Format Support
 
-Extwee is a story compilation tool supporting multiple historical and current Twine-compatible formats.
-
-<table>
-    <tr>
-        <td>Format</td>
-        <td>Input</td>
-        <td>Output</td>
-    </tr>
-    <tr>
-        <td><a href='https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md'>Twine 1 HTML (2006 - 2015)</a> </td>
-        <td>Yes</td>
-        <td>Partial support. Twine 1 HTML can be produced, but the StorySettings optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee.</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md">Twine 1 TWS (2009 - 2015)</a></td>
-        <td>Yes</td>
-        <td>Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format.</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md">Twine 2 HTML (2015 - Present)</a></td>
-        <td>Yes</td>
-        <td>Yes</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md">Twine 2 Archive HTML (2015 - Present)</a></td>
-        <td>Yes</td>
-        <td>Yes</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md">Twee 3 (2021 - Present)</a></td>
-        <td>Yes</td>
-        <td>Yes</td>
-    </tr>
-    <tr>
-        <td><a href="https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md">Twine 2 JSON (2023 - Present)</a></td>
-        <td>Yes</td>
-        <td>Yes</td>
-    </tr>
-</table>
+Extwee supports multiple historical and current Twine-compatible formats.
+
+| Format                                                                                                                           | Input | Output                                                                                                                                                                                |
+|----------------------------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Twine 1 HTML (2006 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md )          | Yes   | Partial support. Twine 1 HTML can be produced, but the  `StorySettings`  optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee. |
+| [Twine 1 TWS (2009 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md )                | Yes   | Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format.                                                |
+| [Twine 2 HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md )      | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 Archive HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md ) | Yes   | Yes                                                                                                                                                                                   |
+| [Twee 3 (2021 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md )               | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 JSON (2023 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md )       | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 Story Format (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md )       | Yes   | Yes                                                                                                                                                                                   |
 
 **Note:** Round-trip translations can present problems because of required fields and properties per format. Some metadata may be added or removed based on the specification being followed.
 
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## Node and Web API
 
 The following objects and methods are available in Node.js or browser contexts.
@@ -96,6 +88,10 @@ An object must be created using either the `new` keyword in JavaScript or as the
 
 Story and Passage objects can generate multiple output formats: `toTwee()`, `toTwine1HTML()`, `toTwine2HTML()`, and `toJSON()`. Stories cannot be played in a browser without the corresponding compiler combining it with story format data.
 
+The StoryFormat object supports `toString()` method of producing a tab-separated JSON output and `toJSON()` method of generating JSON output matching the Twine 2 Story Format Specification.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ### Parsers
 
 Translates output formats such as HTML, Twee, JSON, or JSONP into objects.
@@ -109,6 +105,8 @@ Translates output formats such as HTML, Twee, JSON, or JSONP into objects.
 - `parseTwine2HTML()`
 - `parseTwine2ArchiveHTML()`
 
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ### Compilers
 
 Compiles story, story formats, or other data into an archive or playable format.
@@ -116,16 +114,31 @@ Compiles story, story formats, or other data into an archive or playable format.
 - `compileTwine2HTML()`
 - `compileTwine1HTML()`
 - `compileTwine2ArchiveHTML()`
+- `compileStoryFormat()`
+
+To create playable Twine 1 HTML, an `engine.js` file must be supplied. (See [Story Format Archive](https://github.com/videlais/story-formats-archive/tree/main/official/twine1/engine/1.4.2) for available Twine 1 `engine.js` file.)
+
+Compilation of a story format adds the necessary function wrapper to convert the JSON output, via `toJSON()`, to JSONP.
+
+### Support Functionality
+
+Multiple Twine formats support using [an IFID](https://ifdb.org/help-ifid) to identify one work from another.
 
-**Note:** In order to create playable Twine 1 HTML, an `engine.js` file must be supplied.
+As part of its API, the Extwee method `generateIFID()` can be used to create a new IFID for a `Story` object or as part of other processes.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## Documentation
 
-Extwee has documentation on individual source files hosted on GitHub Pages.
+Extwee has [documentation hosted on GitHub Pages](https://videlais.github.io/extwee/#/).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## Command-Line Usage
 
-Extwee supports a command-line interface for four general scenarios:
+Extwee supports a command-line interface for four general scenarios.
+
+**Notes:** As of Extwee 2.2.5, short and long command-line option flags are separated. Short options use one hyphen followed by one character and all long options begin with two hyphens and a name as word.
 
 ### Compiling Twee 3 + Twine 2 Story Format into Twine 2 HTML
 
@@ -141,27 +154,38 @@ De-compile Twine 2 HTML into Twee 3:
 
 ### Compiling Twee 3 into Twine 1 HTML
 
-Enabling Twine 1 mode requires using the `-t1` or `--twine1` flag.
+Enabling Twine 1 mode requires using the `--twine1` long flag.
+
+Because Twine 1 story formats can be split across files, compilation requires the "engine" from Twine 1 named `engine.js`, the name of the story format, and then its `header.html` template code and the optional but often included `code.js` file.
+
+(Refer to the [Story Formats Archive](https://github.com/videlais/story-formats-archive) for access to historic `engine.js` and other files.)
 
-`extwee -t1 -c -i <tweeFile> -o <Twine1HTML> -engine <engineJS> -name <storyFormatName> -codejs <CodeJS> -header <header>`
+`extwee --twine1 -c -i <tweeFile> -o <Twine1HTML> --engine <engineJS> --name <storyFormatName> --codejs <CodeJS> --header <header>`
 
 ### De-compiling Twine 1 HTML into Twee 3
 
-Enabling Twine 1 mode requires using the `-t1` or `--twine1` flag.
+Enabling Twine 1 mode requires using the `--twine1` flag.
 
-`extwee -t1 -d -i <twine1HTML> -o <outputTwee>`
+`extwee --twine1 -d -i <twine1HTML> -o <outputTwee>`
 
-## Roadmap
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-Each major version has its own GitHub project:
+## Config File Usage
 
-- [Road to Extwee 2.2.0](https://github.com/users/videlais/projects/2)
-- [Road to Extwee 2.4.0](https://github.com/users/videlais/projects/4)
+When invoked from its command-line interface using `npx extwee`, it will look for a `extwee.config.json` file in the local directory. If found, and its fields are valid, processing will use the values found in the file.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## Tree Shaking Support
 
-For [advanced tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) patterns, most formats are broke into `compile.js` and `parse.js` files exporting associated `compile()` and `parse()` functions. When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.
+For [advanced tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) patterns, most formats are broke into `compile.js` and `parse.js` files exporting associated `compile()` and `parse()` functions.
+
+When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## License
 
 Distributed under the MIT License. See `LICENSE.txt` for more information.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>

package/docs/_sidebar.md

@@ -1,5 +1,4 @@
 - Installation and General Usage
-  - [Binaries (stand alone)](/install/binaries.md)
   - [Using NPX (as part of workflow)](/install/npx.md)
   - [Using NPM (via API)](/install/npm.md)
 - Objects

package/docs/install/npm.md

@@ -13,8 +13,4 @@ import { Story, Passage } from 'extwee';
 const example = new Story( 'Example' );
 // Add a new passage.
 example.addPassage(new Passage( 'Test', 'Some Text') );
-
-// Confirm size change.
-// (Should produce 1).
-console.log ( example.size() );
 ```

package/docs/install/npx.md

@@ -7,3 +7,73 @@ Extwee can be used via NPX (node package execution) without being added to a loc
 ```bash
 npx extwee -c -i <tweeFile> -s <storyFormat> -o <Twine2HTML>
 ```
+
+## Config File Usage
+
+When used via NPX, Extwee will also look for a local file, `extwee.config.json`.
+
+The configuration file supports some, but not all, possible actions using command-line arguments.
+
+### Defining `mode`
+
+The most important option is `mode`. This **MUST BE** either `compile` or `decompile`.
+
+```json
+{
+    "mode": "decompile"
+}
+```
+
+### Defining `input` and `output`
+
+To process files, the `input` and `output` properties **MUST BE** defined using either an absolute or relative path.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html"
+}
+```
+
+### Defining `story-format`
+
+If using the `"mode": "compile"` option, the `story-format` property **MUST BE** defined. This should be the name of a directory in the relative `./story-formats` directory.
+
+For example, if using Harlowe, the path would be `./story-formats/harlowe` and the key-value pair would be `"story-format": "harlowe"`.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format": "harlowe"
+}
+```
+
+#### Defining optional `story-format-version`
+
+The Story Format Archive retrieves story formats based on its version in a sub-directory structure:
+
+```file
+story-formats/
+├── harlowe/
+│   ├── 2.3.0/
+│       └── format.js
+│   ├── 2.4.0/
+│       └── format.js
+```
+
+This can be specified, such as `3.2.0`, or the default `latest`, can be used.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format": "harlowe",
+    "story-format-version": "3.2.0"
+}
+```
+
+If only the story format name is specified, and it can be found in the local `story-formats` directory, it will search for a corresponding `format.js` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -33,22 +33,22 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.27.2",
-    "@babel/core": "^7.27.1",
-    "@babel/preset-env": "^7.27.2",
+    "@babel/cli": "^7.28.0",
+    "@babel/core": "^7.28.0",
+    "@babel/preset-env": "^7.28.0",
     "@eslint/js": "^9.29.0",
-    "@inquirer/prompts": "^7.5.2",
+    "@inquirer/prompts": "^7.6.0",
     "@types/semver": "^7.7.0",
     "@types/uuid": "^10.0.0",
     "babel-loader": "^10.0.0",
     "clean-jsdoc-theme": "^4.3.0",
     "core-js": "^3.43.0",
     "eslint": "^9.29.0",
-    "eslint-plugin-jest": "^28.14.0",
+    "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-jsdoc": "^51.0.1",
-    "globals": "^16.2.0",
-    "jest": "^30.0.0",
-    "jest-environment-jsdom": "^30.0.0",
+    "globals": "^16.3.0",
+    "jest": "^30.0.4",
+    "jest-environment-jsdom": "^30.0.4",
     "regenerator-runtime": "^0.14.1",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.0",

package/src/Story.js

@@ -7,7 +7,7 @@ import { encode } from 'html-entities';
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.3.0';
+const creatorVersion = '2.3.1';
 
 /**
  * Story class.

package/types/src/Story.d.ts

@@ -251,5 +251,5 @@ export class Story {
     #private;
 }
 export const creatorName: "extwee";
-export const creatorVersion: "2.3.0";
+export const creatorVersion: "2.3.1";
 import Passage from './Passage.js';

package/docs/install/binaries.md

@@ -1,9 +0,0 @@
-# Binaries
-
-Either by downloading the `extwee` (or `extwee.exe`) files from the [Releases listing](https://github.com/videlais/extwee/releases) or from the `build` folder, Extwee can be used as a stand-alone command-line program. (Currently, only builds for MacOS and Windows are included.)
-
-## CLI Example
-
-```bash
-extwee.exe -c -i <tweeFile> -s <storyFormat> -o <Twine2HTML>
-```