mirror of
https://github.com/tmedwards/tweego.git
synced 2025-07-05 06:00:26 -04:00
Initial Bitbucket→GitHub migration commit, based on release v2.0.0.
This commit is contained in:
Thomas M. Edwards
commit
57e1aa52ff
36 changed files with 5026 additions and 0 deletions
52
docs/core/faq-and-tips.md
Normal file
52
docs/core/faq-and-tips.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
<!-- ***********************************************************************************************
|
||||
FAQ & Tips
|
||||
************************************************************************************************ -->
|
||||
<h1 id="faq-and-tips">FAQ & Tips</h1>
|
||||
|
||||
This is a collection of tips, from how to avoid pitfalls to best practices.
|
||||
|
||||
Suggestions for new entries may be submitted by [creating a new issue](https://bitbucket.org/tmedwards/tweego/issues?status=new&status=open) at Tweego's [code repository](https://bitbucket.org/tmedwards/tweego/). **NOTE:** Acceptance of submissions ***is not*** guaranteed.
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Avoid processing files
|
||||
**************************************************************************** -->
|
||||
<span id="faq-and-tips-avoid-processing-files"></span>
|
||||
## Avoid processing files
|
||||
|
||||
The way to avoid having Tweego process files is to not pass it the files in the first place—i.e. keep the files in question separate from the files you want Tweego to compile.
|
||||
|
||||
Using image files as an example, I would generally recommend a directory structure something like:
|
||||
|
||||
```
|
||||
project_directory/
|
||||
images/
|
||||
src/
|
||||
```
|
||||
|
||||
Where `src` is the directory you pass to Tweego, which only contains files you want it to compile—and possibly files that it will not process, like notes and whatnot. For example, while within the project directory the command:
|
||||
|
||||
```
|
||||
tweego -o project.html src
|
||||
```
|
||||
|
||||
Will only compile the files in `src`, leaving the image files in `images` alone.
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Convert Twee2 files to Twee v3
|
||||
**************************************************************************** -->
|
||||
<span id="faq-and-tips-convert-twee2-files-to-tweev3"></span>
|
||||
## Convert Twee2 files to Twee v3
|
||||
|
||||
You may convert a Twee2 notation file to a Twee v3 notation file like so:
|
||||
|
||||
```
|
||||
tweego -d -o twee_v3_file.twee twee2_file.tw2
|
||||
```
|
||||
|
||||
Or, if the Twee2 notation file has a standard Twee file extension, like so:
|
||||
|
||||
```
|
||||
tweego --twee2-compat -d -o twee_v3_file.twee twee2_file.twee
|
||||
```
|
||||
114
docs/core/getting-started.md
Normal file
114
docs/core/getting-started.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Getting Started
|
||||
************************************************************************************************ -->
|
||||
<h1 id="getting-started">Getting Started</h1>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Overview
|
||||
**************************************************************************** -->
|
||||
<span id="getting-started-overview"></span>
|
||||
## Overview
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
In practice, most settings will be handled either by story configuration or via the command line, so the only configuration step that's absolutely necessary to begin using Tweego is to enable it to find your story formats.
|
||||
</p>
|
||||
|
||||
Tweego may be configured in a variety of ways—by environment variable, story configuration, and command line options.
|
||||
|
||||
The various methods for specifying configuration settings cascade in the following order:
|
||||
|
||||
1. Program defaults.
|
||||
2. Environment variables.
|
||||
3. Story configuration. See the [`StoryData` passage](#special-passages-storydata) for more information.
|
||||
4. Command line. See [Usage](#usage) for more information.
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Program Defaults
|
||||
**************************************************************************** -->
|
||||
<span id="getting-started-program-defaults"></span>
|
||||
## Program Defaults
|
||||
|
||||
<dl>
|
||||
<dt>Input charset</dt>
|
||||
<dd>
|
||||
<p>The default character set is <code>utf-8</code>, failing over to <code>windows-1252</code> if the input files are not in UTF-8.</p>
|
||||
<p class="tip" role="note"><b>Tip:</b> It is <strong><em>strongly recommended</em></strong> that you use UTF-8 for all of your text files.</p>
|
||||
</dd>
|
||||
<dt>Story format</dt>
|
||||
<dd>The default story format (by ID) is <code>sugarcube-2</code>.</dd>
|
||||
<dt>Output file</dt>
|
||||
<dd>The default output file is <code>-</code>, which is shorthand for <a href="https://en.wikipedia.org/wiki/Standard_streams" target="_blank"><i>standard output</i></a>.</dd>
|
||||
<dt>Starting passage</dt>
|
||||
<dd>The default starting passage name is <code>Start</code>.</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Environment Variables
|
||||
**************************************************************************** -->
|
||||
<span id="getting-started-environment-variables"></span>
|
||||
## Environment Variables
|
||||
|
||||
<dl>
|
||||
<dt id="getting-started-environment-variables-tweego-path"><var>TWEEGO_PATH</var></dt>
|
||||
<dd>
|
||||
<p>Path(s) to search for story formats. The value should be a list of directories to search for story formats. You may specify one directory or several. The format is exactly the same as any other <em>path type</em> environment variable for your operating system.</p>
|
||||
<p class="tip" role="note"><b>Tip:</b> Setting <var>TWEEGO_PATH</var> is only necessary if you intend to place your story formats outside of the directories normally searched by Tweego. See <a href="#getting-started-story-formats-search-directories">Search Directories</a> for more information.</p>
|
||||
<p role="note"><b>Note:</b> To separate multiple directories within <em>path</em> variables, Unix-like operating systems use the colon, while Windows uses the semi-colon. Only relevant if you intend to specify multiple directories.</p>
|
||||
<p><strong>Unix-y examples</strong></p>
|
||||
<p>If you wanted Tweego to search <code>/usr/local/storyformats</code>, then you'd set <code>TWEEGO_PATH</code> to:</p>
|
||||
<pre><code>/usr/local/storyformats</code></pre>
|
||||
<p>If you wanted Tweego to search <code>/storyformats</code> and <code>/usr/local/storyformats</code>, then you'd set <code>TWEEGO_PATH</code> to:</p>
|
||||
<pre><code>/storyformats:/usr/local/storyformats</code></pre>
|
||||
<p><strong>Windows examples</strong></p>
|
||||
<p>If you wanted Tweego to search <code>C:\\storyformats</code>, then you'd set <code>TWEEGO_PATH</code> to:</p>
|
||||
<pre><code>C:\storyformats</code></pre>
|
||||
<p>If you wanted Tweego to search <code>C:\storyformats</code> and <code>D:\storyformats</code>, then you'd set <code>TWEEGO_PATH</code> to:</p>
|
||||
<pre><code>C:\storyformats;D:\storyformats</code></pre>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Story Formats
|
||||
**************************************************************************** -->
|
||||
<span id="getting-started-story-formats"></span>
|
||||
## Story Formats
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
Throughout this document the terms <code>story format</code> and <code>format</code> are virtually always used to encompass both story and proofing formats.
|
||||
</p>
|
||||
|
||||
Tweego should be compatible with *all* story formats—i.e., those written for Twine 2, Twine 1 ≥v1.4.0, and Twine 1 ≤v1.3.5.
|
||||
|
||||
Installing a story format can be as simple as moving its directory into one of the directories Tweego searches for story formats—see [Search Directories](#getting-started-story-formats-search-directories) for more information. Each installed story format, which includes separate versions of the same story format, should have its own <em>unique</em> directory within your story formats directory—i.e., if you have both SugarCube v2 and v1 installed, then they should each have their own separate directory; e.g., `sugarcube-2` and `sugarcube-1`. Do not create additional sub-directories, combine directories, or rename a story format's files.
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
To ensure a story format has been installed correctly, use the list-formats command line option (<kbd>--list-formats</kbd>) to see if Tweego lists it as an available format.
|
||||
</p>
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
Twine 2 story formats are, ostensibly, encoded as JSON-P. Unfortunately, some story formats deviate from proper JSON encoding and are thus broken. Tweego uses a strict JSON decoder and cannot decode such broken story formats for use. Should you receive a story format decoding error, all reports should go to the format's developer.
|
||||
</p>
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="getting-started-story-formats-search-directories"></span>
|
||||
### Search Directories
|
||||
|
||||
When Tweego is run, it finds story formats to use by searching the following directories: *(in order)*
|
||||
|
||||
1. The directories <kbd>storyformats</kbd> and <kbd>.storyformats</kbd> within its <em>program directory</em>—i.e., the directory where Tweego's binary file is located.
|
||||
2. The directories <kbd>storyformats</kbd> and <kbd>.storyformats</kbd> within the <em>user's home directory</em>—i.e., either the value of the <var>HOME</var> environment variable or the operating system specified home directory.
|
||||
3. The directories <kbd>storyformats</kbd> and <kbd>.storyformats</kbd> within the <em>current working directory</em>—i.e., the directory that you are executing Tweego from.
|
||||
4. The directories specified via the <var>TWEEGO_PATH</var> environment variable. See <a href="#getting-started-environment-variables">Environment Variables</a> for more information.
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
For legacy compatibility, the following directories are also checked during steps #1–3: <kbd>story-formats</kbd>, <kbd>storyFormats</kbd>, and <kbd>targets</kbd>. You are encouraged to use one of the directory names listed above instead.
|
||||
</p>
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
A story format's directory name is used as its <strong><em>unique</em></strong> ID within the story format list. As a consequence, if multiple story formats, from different search paths, have the same directory name, then only the last one found will be registered.
|
||||
</p>
|
||||
109
docs/core/special-passages-and-tags.md
Normal file
109
docs/core/special-passages-and-tags.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Special Passages & Tags
|
||||
************************************************************************************************ -->
|
||||
<h1 id="special">Special Passages & Tags</h1>
|
||||
|
||||
Passages and tags that have special meaning to Tweego.
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
This is <em>not</em> a exhaustive list of all special passages and tags that may have meaning to story formats—or other compilers. See the documentation of the specific story format—or compiler—for their list of special passages and tags.
|
||||
</p>
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
The names of all special passages and tags listed herein are case sensitive, thus must be spelled <em>exactly</em> as shown.
|
||||
</p>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Special Passages
|
||||
**************************************************************************** -->
|
||||
<span id="special-passages"></span>
|
||||
## Special Passages
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="special-passages-start"></span>
|
||||
### `Start`
|
||||
|
||||
The `Start` passage will, by default, be used as the starting passage—i.e. the first normal passage displayed to the player. That behavior may be overridden via either the <var>start</var> property from the [`StoryData` passage](#special-passages-storydata) or the start command line option (<kbd>-s NAME</kbd>, <kbd>--start=NAME</kbd>).
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
It is <strong><em>strongly recommended</em></strong> that you simply use the default starting name, <code>Start</code>, when beginning new projects.
|
||||
</p>
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="special-passages-storydata"></span>
|
||||
### `StoryData`
|
||||
|
||||
The `StoryData` passage may be used to specify basic project settings. Its contents must consist of a JSON chunk, which is, generally, pretty-printed—i.e., line-broken and indented.
|
||||
|
||||
The core properties used with all story formats include:
|
||||
|
||||
- <var>ifid</var>: (string) Required. The project's Interactive Fiction IDentifier (IFID), which is a unique code used to identify your project—similar to the ISBN code assigned to a book. If the project does not already have an IFID, you may omit the property and Tweego will automatically generate one for you with instructions on how to copy it into the chunk.
|
||||
- <var>start</var>: (string) Optional. The name of the starting passage. If omitted, defaults to the [`Start` passage](#special-passages-start).
|
||||
|
||||
The properties used only with Twine 2-style story formats include:
|
||||
|
||||
- <var>format</var>: (string) Optional. The name of the story format to compile against—e.g., `SugarCube`, `Harlowe`, `Chapbook`, `Snowman`.
|
||||
- <var>format-version</var>: (string) Optional. The version of the story format to compile against—e.g., `2.29.0`. From the installed story formats matching the name specified in <var>format</var>, Tweego will attempt to use the greatest version that matches the specified major version—i.e., if <var>format-version</var> is `2.0.0` and you have the versions `1.0.0`, `2.0.0`, `2.5.0`, and `3.0.0` installed, Tweego will choose `2.5.0`.
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
The above is <em>not</em> an exhaustive list of all Twine 2-style story format properties. There are others available that are only useful when actually interoperating with Twine 2—e.g, <var>tag-colors</var> and <var>zoom</var>. See the <a href="https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md" target="_blank">twee-3-specification.md</a> for more information.
|
||||
</p>
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
To compile against a specific version of a story format, use the format command line option (<kbd>-f NAME</kbd>, <kbd>--format=NAME</kbd>) to specify the version by its ID. If you don't know the ID, use the list-formats command line option (<kbd>--list-formats</kbd>) to find it.
|
||||
</p>
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
JSON chunks are not JavaScript object literals, though they look much alike. Property names must always be double quoted and you should not include a trailing comma after the last property.
|
||||
</p>
|
||||
|
||||
#### Example
|
||||
|
||||
```
|
||||
:: StoryData
|
||||
{
|
||||
"ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
|
||||
"format": "SugarCube",
|
||||
"format-version": "2.29.0",
|
||||
"start": "My Starting Passage"
|
||||
}
|
||||
```
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="special-passages-storytitle"></span>
|
||||
### `StoryTitle`
|
||||
|
||||
The contents of the `StoryTitle` passage will be used as the name/title of the story.
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Special Tags
|
||||
**************************************************************************** -->
|
||||
<span id="special-tags"></span>
|
||||
## Special Tags
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="special-tags-script"></span>
|
||||
### `script`
|
||||
|
||||
The `script` tag denotes that the passage's contents are JavaScript code.
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
In general, Tweego makes creating script passages unnecessary as it will automatically bundle any JavaScript source files (<code>.js</code>) it encounters into your project.
|
||||
</p>
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="special-tags-stylesheet"></span>
|
||||
### `stylesheet`
|
||||
|
||||
The `stylesheet` tag denotes that the passage's contents are CSS rules.
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
In general, Tweego makes creating stylesheet passages unnecessary as it will automatically bundle any CSS source files (<code>.css</code>) it encounters into your project.
|
||||
</p>
|
||||
149
docs/core/twee-notation.md
Normal file
149
docs/core/twee-notation.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Twee Notation
|
||||
************************************************************************************************ -->
|
||||
<h1 id="twee-notation">Twee Notation</h1>
|
||||
|
||||
In Twee and Twine, stories are arranged into units called passages. Each passage has a name, optional attributes, and content.
|
||||
|
||||
There are two official Twee notations, Twee v3 and Twee v1, and an unofficial Twee2 notation.
|
||||
|
||||
* Twee v3 is the current official notation—see the <a href="https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md" target="_blank">twee-3-specification.md</a> for more information.
|
||||
* Twee v1 is the classic/legacy official notation, which is a compatible subset of Twee v3.
|
||||
* The unofficial Twee2 notation is primarily generated and used by the Twee2 compiler, which is largely abandonware.
|
||||
|
||||
By default, Tweego supports compiling from both of the official Twee notations and decompiling to Twee v3. Compiling from the unofficial Twee2 notation is also supported via a compatibility mode, but is not enabled by default. To load files with the Twee2 compatibility mode enabled, either the files must have a Twee2 extension (`.tw2`, `.twee2`) or its command line option (<kbd>--twee2-compat</kbd>) must be used.
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
It is <strong><em>strongly recommended</em></strong> that you do not enable Twee2 compatibility mode unless you absolutely need it.
|
||||
</p>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Twee v3 Notation
|
||||
**************************************************************************** -->
|
||||
<span id="twee-notation-tweev3"></span>
|
||||
## Twee v3 Notation
|
||||
|
||||
In the Twee v3 notation, passages consist of a passage declaration and a following content section.
|
||||
|
||||
A passage declaration must be a single line and is composed of the following components *(in order)*:
|
||||
|
||||
1. A required start token that must begin the line. It is composed of a double colon (`::`).
|
||||
2. A required passage name.
|
||||
3. An optional tags block that must directly follow the passage name. It is composed of a left square bracket (`[`), a space separated list of tags, and a right square bracket (`]`).
|
||||
4. An optional metadata block that must directly follow either the tag block or, if the tag block is omitted, the passage name. It is composed of an inline JSON chunk containing the optional properties `position` and `size`.
|
||||
|
||||
The passage content section begins with the very next line and continues until the next passage declaration.
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
For the sake of readability, it is recommended that each component within the passage declaration after the start token be preceded by one or more spaces and that, at least, one blank line is added between passages.
|
||||
</p>
|
||||
|
||||
<p role="note"><b>Note:</b>
|
||||
You will likely never need to create metadata blocks yourself. When compiling, any missing metadata will be automatically generated for the compiled file. When decompiling, they'll be automatically pulled from the compiled file.
|
||||
</p>
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="twee-notation-tweev3-passage-and-tag-name-escaping"></span>
|
||||
### Passage And Tag Name Escaping
|
||||
|
||||
To prevent ambiguity during parsing, passage and tag names that include the optional tag or metadata block delimiters (`[`, `]`, `{`, `}`) must escape them. The escapement mechanism is to prefix the escaped characters with a backslash (`\`). Further, to avoid ambiguity with the escape character itself, non-escape backslashes must also be escaped via the same mechanism—e.g., `foo\bar` should be escaped as `foo\\bar`.
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
It is <strong><em>strongly recommended</em></strong> that you simply avoid needing to escape characters by not using the optional tag or metadata block delimiters within passage and tag names.
|
||||
</p>
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
For different reasons, it is also <strong><em>strongly recommended</em></strong> that you avoid the use of the link markup separator delimiters (<code>|</code>, <code>-></code>, <code><-</code>) within passage and tag names.
|
||||
</p>
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="twee-notation-tweev3-example"></span>
|
||||
### Example
|
||||
|
||||
#### Without any passage metadata
|
||||
|
||||
Exactly the same as Twee v1, save for the [Passage And Tag Name Escaping](#twee-notation-tweev3-passage-and-tag-name-escaping) rules.
|
||||
|
||||
```
|
||||
:: A passage with no tags
|
||||
Content of the "A passage with no tags" passage.
|
||||
|
||||
|
||||
:: A tagged passage with three tags [alfa bravo charlie]
|
||||
Content of the "A tagged passage with three tags" passage.
|
||||
The three tags are: alfa, bravo, charlie.
|
||||
```
|
||||
|
||||
#### With some passage metadata
|
||||
|
||||
Mostly likely to come from decompiling Twine 2 or Twine 1 compiled HTML files.
|
||||
|
||||
```
|
||||
:: A passage with no tags {"position"="860,401"}
|
||||
Content of the "A passage with no tags" passage.
|
||||
|
||||
|
||||
:: A tagged passage with three tags [alfa bravo charlie] {"position"="860,530"}
|
||||
Content of the "A tagged passage with three tags" passage.
|
||||
The three tags are: alfa, bravo, charlie.
|
||||
```
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Twee v1 Notation
|
||||
**************************************************************************** -->
|
||||
<span id="twee-notation-tweev1"></span>
|
||||
## Twee v1 Notation
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
Except in instances where you plan to interoperate with Twine 1, it is <strong><em>strongly recommended</em></strong> that you do not create new files using the Twee v1 notation. You should prefer the <a href="#twee-notation-tweev3">Twee v3 notation</a> instead.
|
||||
</p>
|
||||
|
||||
Twee v1 notation is a subset of Twee v3 that lacks support for both the optional metadata block within passage declarations and passage and tag name escaping.
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="twee-notation-tweev1-example"></span>
|
||||
### Example
|
||||
|
||||
```
|
||||
:: A passage with no tags
|
||||
Content of the "A passage with no tags" passage.
|
||||
|
||||
|
||||
:: A tagged passage with three tags [alfa bravo charlie]
|
||||
Content of the "A tagged passage with three tags" passage.
|
||||
The three tags are: alfa, bravo, charlie.
|
||||
```
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Twee2 Notation
|
||||
**************************************************************************** -->
|
||||
<span id="twee-notation-twee2"></span>
|
||||
## Twee2 Notation
|
||||
|
||||
<p class="warning" role="note"><b>Warning:</b>
|
||||
It is <strong><em>strongly recommended</em></strong> that you do not create new files using the unofficial Twee2 notation. You should prefer the <a href="#twee-notation-tweev3">Twee v3 notation</a> instead.
|
||||
</p>
|
||||
|
||||
The unofficial Twee2 notation is mostly identical to the Twee v1 notation, save that the passage declaration may also include an optional position block that must directly follow either the tag block or, if the tag block is omitted, the passage name.
|
||||
|
||||
|
||||
<!-- *********************************************************************** -->
|
||||
|
||||
<span id="twee-notation-tweev1-example"></span>
|
||||
### Example
|
||||
|
||||
```
|
||||
:: A passage with no tags <860,401>
|
||||
Content of the "A passage with no tags" passage.
|
||||
|
||||
|
||||
:: A tagged passage with three tags [alfa bravo charlie] <860,530>
|
||||
Content of the "A tagged passage with three tags" passage.
|
||||
The three tags are: alfa, bravo, charlie.
|
||||
```
|
||||
164
docs/core/usage.md
Normal file
164
docs/core/usage.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Usage
|
||||
************************************************************************************************ -->
|
||||
<h1 id="usage">Usage</h1>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Overview
|
||||
**************************************************************************** -->
|
||||
<span id="usage-overview"></span>
|
||||
## Overview
|
||||
|
||||
<p class="tip" role="note"><b>Tip:</b>
|
||||
At any time you may pass the help option (<kbd>-h</kbd>, <kbd>--help</kbd>) to Tweego to show its built-in help.
|
||||
</p>
|
||||
|
||||
Basic command line usage is as follows:
|
||||
|
||||
```
|
||||
tweego [options] sources…
|
||||
```
|
||||
|
||||
Where <code>[options]</code> are mostly optional configuration flags—see [Options](#usage-options)—and <code>sources</code> are the input sources which may consist of supported files and/or directories to recursively search for such files. Many types of files are supported as input sources—see [File & Directory Handling](#usage-file-and-directory-handling) for more information.
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Options
|
||||
**************************************************************************** -->
|
||||
<span id="usage-options"></span>
|
||||
## Options
|
||||
|
||||
<dl>
|
||||
<dt><kbd>-a</kbd>, <kbd>--archive-twine2</kbd></dt><dd>Output Twine 2 archive, instead of compiled HTML.</dd>
|
||||
<dt><kbd>--archive-twine1</kbd></dt><dd>Output Twine 1 archive, instead of compiled HTML.</dd>
|
||||
<dt><kbd>-c SET</kbd>, <kbd>--charset=SET</kbd></dt>
|
||||
<dd>
|
||||
<p>Name of the input character set (default: <code>"utf-8"</code>, fallback: <code>"windows-1252"</code>). Necessary only if the input files are not in either UTF-8 or the fallback character set.</p>
|
||||
<p class="tip" role="note"><b>Tip:</b> It is <strong><em>strongly recommended</em></strong> that you use UTF-8 for all of your text files.</p>
|
||||
</dd>
|
||||
<dt><kbd>-d</kbd>, <kbd>--decompile-twee3</kbd></dt><dd>Output Twee 3 source code, instead of compiled HTML. See <a href="#twee-notation-tweev3">Twee v3 Notation</a> for more information.</dd>
|
||||
<dt><kbd>--decompile-twee1</kbd></dt>
|
||||
<dd>
|
||||
<p>Output Twee 1 source code, instead of compiled HTML. See <a href="#twee-notation-tweev1">Twee v1 Notation</a> for more information.</p>
|
||||
<p role="note"><b>Note:</b> Except in instances where you plan to interoperate with Twine 1, it is <strong><em>strongly recommended</em></strong> that you decompile to Twee v3 notation rather than Twee v1.</p>
|
||||
</dd>
|
||||
<dt><kbd>-f NAME</kbd>, <kbd>--format=NAME</kbd></dt><dd>ID of the story format (default: <code>"sugarcube-2"</code>).</dd>
|
||||
<dt><kbd>-h</kbd>, <kbd>--help</kbd></dt><dd>Print the built-in help, then exit.</dd>
|
||||
<dt><kbd>--head=FILE</kbd></dt><dd>Name of the file whose contents will be appended as-is to the <head> element of the compiled HTML.</dd>
|
||||
<dt><kbd>--list-charsets</kbd></dt><dd>List the supported input character sets, then exit.</dd>
|
||||
<dt><kbd>--list-formats</kbd></dt><dd>List the available story formats, then exit.</dd>
|
||||
<dt><kbd>--log-files</kbd></dt>
|
||||
<dd>
|
||||
<p>Log the processed input files.</p>
|
||||
<p role="note"><b>Note:</b> Unsupported when watch mode (<kbd>-w</kbd>, <kbd>--watch</kbd>) is enabled.</p>
|
||||
</dd>
|
||||
<dt><kbd>-l</kbd>, <kbd>--log-stats</kbd></dt>
|
||||
<dd>
|
||||
<p>Log various story statistics. Primarily, passage and word counts.</p>
|
||||
<p role="note"><b>Note:</b> Unsupported when watch mode (<kbd>-w</kbd>, <kbd>--watch</kbd>) is enabled.</p>
|
||||
</dd>
|
||||
<dt><kbd>-m SRC</kbd>, <kbd>--module=SRC</kbd></dt><dd>Module sources (repeatable); may consist of supported files and/or directories to recursively search for such files. Each file will be wrapped within the appropriate markup and bundled into the <head> element of the compiled HTML. Supported files: <code>.css</code>, <code>.js</code>, <code>.otf</code>, <code>.ttf</code>, <code>.woff</code>, <code>.woff2</code>.</dd>
|
||||
<dt><kbd>-o FILE</kbd>, <kbd>--output=FILE</kbd></dt><dd>Name of the output file (default: <kbd>-</kbd>; i.e., <a href="https://en.wikipedia.org/wiki/Standard_streams" target="_blank"><i>standard output</i></a>).</dd>
|
||||
<dt><kbd>-s NAME</kbd>, <kbd>--start=NAME</kbd></dt><dd>Name of the starting passage (default: the passage set by the story data, elsewise <code>"Start"</code>).</dd>
|
||||
<dt><kbd>-t</kbd>, <kbd>--test</kbd></dt><dd>Compile in test mode; only for story formats in the Twine 2 style.</dd>
|
||||
<dt><kbd>--twee2-compat</kbd></dt><dd>Enable Twee2 source compatibility mode; files with the <code>.tw2</code> or <code>.twee2</code> extensions automatically have compatibility mode enabled.</dd>
|
||||
<dt><kbd>-v</kbd>, <kbd>--version</kbd></dt><dd>Print version information, then exit.</dd>
|
||||
<dt><kbd>-w</kbd>, <kbd>--watch</kbd></dt><dd>Start watch mode; watch input sources for changes, rebuilding the output as necessary.</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
Basic Examples
|
||||
**************************************************************************** -->
|
||||
<span id="usage-basic-examples"></span>
|
||||
## Basic Examples
|
||||
|
||||
Compile <kbd>example_1.twee</kbd> as <kbd>example_1.html</kbd> with the default story format:
|
||||
|
||||
```
|
||||
tweego -o example_1.html example_1.twee
|
||||
```
|
||||
|
||||
Compile all files in <kbd>example_directory_2</kbd> as <kbd>example_2.html</kbd> with the default story format:
|
||||
|
||||
```
|
||||
tweego -o example_2.html example_directory_2
|
||||
```
|
||||
|
||||
Compile <kbd>example_3.twee</kbd> as <kbd>example_3.html</kbd> with the story format <kbd>snowman</kbd>:
|
||||
|
||||
```
|
||||
tweego -f snowman -o example_3.html example_3.twee
|
||||
```
|
||||
|
||||
Compile all files in <kbd>example_directory_4</kbd> as <kbd>example_4.html</kbd> with the default story format while also bundling all files in <kbd>modules_directory_4</kbd> into the <head> element of the compiled HTML:
|
||||
|
||||
```
|
||||
tweego -o example_4.html -m modules_directory_4 example_directory_4
|
||||
```
|
||||
|
||||
Decompile <kbd>example_5.html</kbd> as <kbd>example_5.twee</kbd>:
|
||||
|
||||
```
|
||||
tweego -d -o example5.twee example5.html
|
||||
```
|
||||
|
||||
|
||||
<!-- ***************************************************************************
|
||||
File & Directory Handling
|
||||
**************************************************************************** -->
|
||||
<span id="usage-file-and-directory-handling"></span>
|
||||
## File & Directory Handling
|
||||
|
||||
Tweego allows you to specify an arbitrary number of files and directories on the command line for processing. In addition to those manually specified, it will recursively search all directories encountered looking for additional files and directories to process. Generally, this means that you only have to specify the base source directory of your project and Tweego will find all of its files automatically.
|
||||
|
||||
### Supported File Extensions
|
||||
|
||||
Tweego only processes files with the following extensions:
|
||||
|
||||
<dl>
|
||||
<dt><code>.tw</code>, <code>.twee</code></dt>
|
||||
<dd>
|
||||
<p>Twee notation source files to process for passages.</p>
|
||||
<p role="note"><b>Note:</b> If any of these files are in the unofficial Twee2 notation, you must manually enable the Twee2 compatibility mode via its command line option (<kbd>--twee2-compat</kbd>).</p>
|
||||
</dd>
|
||||
<dt><code>.tw2</code>, <code>.twee2</code></dt>
|
||||
<dd>Unofficial Twee2 notation source files to process for passages. Twee2 compatibility mode is automatically enabled for files with these extensions.</dd>
|
||||
<dt><code>.htm</code>, <code>.html</code></dt>
|
||||
<dd>HTML source files to process for passages, either compiled files or story archives.</dd>
|
||||
<dt><code>.css</code></dt>
|
||||
<dd>CSS source files to bundle.</dd>
|
||||
<dt><code>.js</code></dt>
|
||||
<dd>JavaScript source files to bundle.</dd>
|
||||
<dt><code>.otf</code>, <code>.ttf</code>, <code>.woff</code>, <code>.woff2</code></dt>
|
||||
<dd>Font files to bundle, as <code>@font-face</code> style rules. The generated name of the font family will be the font's base filename sans its extension—e.g., the family name for <code>chinacat.tff</code> will be <code>chinacat</code>.</dd>
|
||||
<dt><code>.gif</code>, <code>.jpeg</code>, <code>.jpg</code>, <code>.png</code>, <code>.svg</code>, <code>.tif</code>, <code>.tiff</code>, <code>.webp</code></dt>
|
||||
<dd>
|
||||
<p>Image files to bundle, as image passages. The generated name of the image passage will be the base filename sans its extension—e.g., the passage name for <code>rainboom.jpg</code> will be <code>rainboom</code>.</p>
|
||||
<p role="note"><b>Note:</b>
|
||||
As of this writing, image passages are only natively supported by SugarCube (all versions) and the Twine 1 ≥v1.4 vanilla story formats.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><code>.aac</code>, <code>.flac</code>, <code>.m4a</code>, <code>.mp3</code>, <code>.oga</code>, <code>.ogg</code>, <code>.opus</code>, <code>.wav</code>, <code>.wave</code>, <code>.weba</code></dt>
|
||||
<dd>
|
||||
<p>Audio files to bundle, as audio passages. The generated name of the audio passage will be the base filename sans its extension—e.g., the passage name for <code>swamped.mp3</code> will be <code>swamped</code>.</p>
|
||||
<p role="note"><b>Note:</b>
|
||||
As of this writing, audio passages are only natively supported by SugarCube ≥v2.24.0.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><code>.mp4</code>, <code>.ogv</code>, <code>.webm</code></dt>
|
||||
<dd>
|
||||
<p>Video files to bundle, as video passages. The generated name of the video passage will be the base filename sans its extension—e.g., the passage name for <code>cutscene.mp4</code> will be <code>cutscene</code>.</p>
|
||||
<p role="note"><b>Note:</b>
|
||||
As of this writing, video passages are only natively supported by SugarCube ≥v2.24.0.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><code>.vtt</code></dt>
|
||||
<dd>
|
||||
<p>Text track files to bundle, as text track passages. The generated name of the text track passage will be the base filename sans its extension—e.g., the passage name for <code>captions.vtt</code> will be <code>captions</code>.</p>
|
||||
<p role="note"><b>Note:</b>
|
||||
As of this writing, text track passages are only natively supported by SugarCube ≥v2.24.0.
|
||||
</p>
|
||||
</dd>
|
||||
</dl>
|
||||
8
docs/introduction.md
Normal file
8
docs/introduction.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Introduction
|
||||
************************************************************************************************ -->
|
||||
<h1 id="introduction">Introduction</h1>
|
||||
|
||||
This documentation is a reference for [Tweego](http://www.motoslave.net/tweego/), a free (gratis and libre) command line compiler for [Twine/Twee](http://twinery.org/) story formats, written in [Go](http://golang.org/).
|
||||
|
||||
If you believe that you've found a bug in Tweego or simply wish to make a suggestion, you may do so by [creating a new issue](https://bitbucket.org/tmedwards/tweego/issues?status=new&status=open) at its [code repository](https://bitbucket.org/tmedwards/tweego/).
|
||||
48
docs/table-of-contents.md
Normal file
48
docs/table-of-contents.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
<!-- ***********************************************************************************************
|
||||
Table of Contents
|
||||
************************************************************************************************ -->
|
||||
<nav role="navigation">
|
||||
<header role="banner">
|
||||
<h1>Tweego Documentation</h1>
|
||||
<div><tt>{{.VERSION}}</tt> (<time datetime="{{.ISO_DATE}}">{{.DATE}}</time>)</div>
|
||||
</header>
|
||||
|
||||
## [Introduction](#introduction)
|
||||
|
||||
## [Getting Started](#getting-started)
|
||||
|
||||
* [Overview](#getting-started-overview)
|
||||
* [Program Defaults](#getting-started-program-defaults)
|
||||
* [Environment Variables](#getting-started-environment-variables)
|
||||
* [Story Formats](#getting-started-story-formats)
|
||||
|
||||
## [Usage](#usage)
|
||||
|
||||
* [Overview](#usage-overview)
|
||||
* [Options](#usage-options)
|
||||
* [Basic Examples](#usage-basic-examples)
|
||||
* [File & Directory Handling](#usage-file-and-directory-handling)
|
||||
|
||||
## [Twee Notation](#twee-notation)
|
||||
|
||||
* [Twee v3](#twee-notation-tweev3)
|
||||
* [Twee v1](#twee-notation-tweev1)
|
||||
* [Twee2](#twee-notation-twee2)
|
||||
|
||||
## [Special Passages & Tags](#special)
|
||||
|
||||
* [Special Passages](#special-passages)
|
||||
* [`Start`](#special-passages-start)
|
||||
* [`StoryData`](#special-passages-storydata)
|
||||
* [`StoryTitle`](#special-passages-storytitle)
|
||||
* [Special Tags](#special-tags)
|
||||
* [`script`](#special-tags-script)
|
||||
* [`stylesheet`](#special-tags-stylesheet)
|
||||
|
||||
## [FAQ & Tips](#faq-and-tips)
|
||||
|
||||
* [Avoid processing files](#faq-and-tips-how-to-avoid-processing-files)
|
||||
* [Convert Twee2 files to Twee v3](#faq-and-tips-how-to-convert-twee2-files-to-tweev3)
|
||||
|
||||
<div> </div>
|
||||
</nav>
|
||||
Loading…
Add table
Add a link
Reference in a new issue