Adding section on story compilation

videlais · Dec 21, 2023 · 5f732c3 · 5f732c3
1 parent 803ab59
commit 5f732c3
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -11,24 +11,51 @@
 ## Table of Contents
 
 <ol>
-    <li>
-      <a href="#format-support">Format Support</a>
-    </li>
-    <li><a href="#usage">Node and Web API</a></li>
-    <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="#escaping- meta-characters">Escaping Meta-Characters</a></li>
-    <li><a href="#license">License</a></li>
   </ol>
+  <li><a href="#documentation">Documentation</a></li>
+  <li><a href="#command-line-usage">Command-Line 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 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.
+
+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.
+
+Playable formats are the following and require external story formats[^1] to enable play:
+
+- Twine 2 HTML
+- Twine 1 HTML
+
+More human-readable formats include:
+
+- Twee 3[^2]
+- Twine 2 JSON[^3]
+
+From 2009 to 2015, Twine 1 supported a now [historical format named TWS](https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md). This was a binary format used for archival purposes. Extwee can read this format but does not support creating it because no other tools, including current versions of Twine, accept it as valid input.
+
+Twine 2 supports exporting a collection of stories (known as a *library*) in the [Twine 2 Archive HTML format](https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md). Extwee can also read and write this format, creating either a collection of stories from the data or writing a collection of internal objects to a file.
+
+[^1]: Extwee does not include or publish story formats. These can be found in the [Story Format Archive (SFA)](https://github.com/videlais/story-formats-archive).
+
+[^2]: Twee exists in three versions. The first existed between 2006 to 2009 and was part of Twine 1. The move to Twine 2 in 2009 dropped support and the story compilation tools [Twee2](https://dan-q.github.io/twee2/) and [Tweego](https://www.motoslave.net/tweego/) adopted their own extensions and modifications. Beginning in 2017, work was done to unite the different projects. This resulted in [Twee 3](https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md) in March 2021.
+
+[^3]: In October 2023, JavaScript Object Notation (JSON) was added as a supported community format for story compilation tools. Extwee is the first tool to support this format.
 
 ## Format Support
 
-Extwee is a story compilation tool supporting multiple historical and current Twine-compatible formats.
+Extwee supports multiple historical and current Twine-compatible formats.
 
 | Format                                                                                                                           | Input | Output                                                                                                                                                                                |
 |----------------------------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -90,7 +117,7 @@ Compiles story, story formats, or other data into an archive or playable format.
 
 ## 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>
 
@@ -114,6 +141,8 @@ De-compile Twine 2 HTML into Twee 3:
 
 Enabling Twine 1 mode requires using the `-t1` or `--twine1` 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.
+
 `extwee -t1 -c -i <tweeFile> -o <Twine1HTML> -engine <engineJS> -name <storyFormatName> -codejs <CodeJS> -header <header>`
 
 ### De-compiling Twine 1 HTML into Twee 3

diff --git a/docs/README.md b/docs/README.md
@@ -8,6 +8,34 @@
 
 [![NPM Badge](https://nodei.co/npm/extwee.png?downloads=true)](https://www.npmjs.com/package/extwee)
 
+## 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 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.
+
+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.
+
+Playable formats are the following and require external story formats[^1] to enable play:
+
+- Twine 2 HTML
+- Twine 1 HTML
+
+More human-readable formats include:
+
+- Twee 3[^2]
+- Twine 2 JSON[^3]
+
+From 2009 to 2015, Twine 1 supported a now [historical format named TWS](https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md). This was a binary format used for archival purposes. Extwee can read this format but does not support creating it because no other tools, including current versions of Twine, accept it as valid input.
+
+Twine 2 supports exporting a collection of stories (known as a *library*) in the [Twine 2 Archive HTML format](https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md). Extwee can also read and write this format, creating either a collection of stories from the data or writing a collection of internal objects to a file.
+
+[^1]: Extwee does not include or publish story formats. These can be found in the [Story Format Archive (SFA)](https://github.com/videlais/story-formats-archive).
+
+[^2]: Twee exists in three versions. The first existed between 2006 to 2009 and was part of Twine 1. The move to Twine 2 in 2009 dropped support and the story compilation tools [Twee2](https://dan-q.github.io/twee2/) and [Tweego](https://www.motoslave.net/tweego/) adopted their own extensions and modifications. Beginning in 2017, work was done to unite the different projects. This resulted in [Twee 3](https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md) in March 2021.
+
+[^3]: In October 2023, JavaScript Object Notation (JSON) was added as a supported community format for story compilation tools. Extwee is the first tool to support this format.
+
 ## Format Support
 
 Extwee is a story compilation tool supporting multiple historical and current Twine-compatible formats.