archives/tweego

Fork 0

mirror of https://github.com/tmedwards/tweego.git synced 2025-07-05 06:00:26 -04:00

Thomas M. Edwards d08ed3a980 [Docs] Reworked intro and cleanup.

2020-03-03 02:30:40 -06:00

10 KiB

Raw Blame History

Usage

Overview

Tip: At any time you may pass the help option (-h, --help) to Tweego to show its built-in help.

Basic command line usage is as follows:

tweego [options] sources…

Where [options] are mostly optional configuration flags—see Options—and sources 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 Supported Files for more information.

Options

-a, --archive-twine2

Output Twine 2 archive, instead of compiled HTML.

--archive-twine1

Output Twine 1 archive, instead of compiled HTML.

-c SET, --charset=SET

Name of the input character set (default: "utf-8", fallback: "windows-1252"). Necessary only if the input files are not in either UTF-8 or the fallback character set.

Tip: It is strongly recommended that you use UTF-8 for all of your text files.

-d, --decompile-twee3

Output Twee 3 source code, instead of compiled HTML. See Twee v3 Notation for more information.

--decompile-twee1

Output Twee 1 source code, instead of compiled HTML. See Twee v1 Notation for more information.

Note: Except in instances where you plan to interoperate with Twine 1, it is strongly recommended that you decompile to Twee v3 notation rather than Twee v1.

-f NAME, --format=NAME

ID of the story format (default: "sugarcube-2").

-h, --help

Print the built-in help, then exit.

--head=FILE

Name of the file whose contents will be appended as-is to the <head> element of the compiled HTML.

--list-charsets

List the supported input character sets, then exit.

--list-formats

List the available story formats, then exit.

--log-files

Log the processed input files.

Note: Unsupported when watch mode (-w, --watch) is enabled.

-l, --log-stats

Log various story statistics. Primarily, passage and word counts.

Note: Unsupported when watch mode (-w, --watch) is enabled.

-m SRC, --module=SRC

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: .css, .js, .otf, .ttf, .woff, .woff2.

--no-trim

Do not trim whitespace surrounding passages—i.e., whitespace preceding and trailing the actual text of the passage. By default, such whitespace is removed when processing passages.

Note: It is recommended that you do not disable passage trimming.

-o FILE, --output=FILE

Name of the output file (default: -; i.e., standard output).

-s NAME, --start=NAME

Name of the starting passage (default: the passage set by the story data, elsewise "Start").

-t, --test

Compile in test mode; only for story formats in the Twine 2 style.

--twee2-compat

Enable Twee2 source compatibility mode; files with the .tw2 or .twee2 extensions automatically have compatibility mode enabled.

-v, --version

Print version information, then exit.

-w, --watch

Start watch mode; watch input sources for changes, rebuilding the output as necessary.

Supported Files

Tweego supports various types of files for use in projects. File types are recognized by filename extension, so all files must have an extension.

The following extensions are supported:

.tw, .twee

Twee notation source files to process for passages.

Note: If any of these files are in the unofficial Twee2 notation, you must manually enable the Twee2 compatibility mode via its command line option (--twee2-compat).

.tw2, .twee2

Unofficial Twee2 notation source files to process for passages. Twee2 compatibility mode is automatically enabled for files with these extensions.

.htm, .html

HTML source files to process for passages, either compiled files or story archives.

.css

CSS source files to bundle.

.js

JavaScript source files to bundle.

.otf, .ttf, .woff, .woff2

Font files to bundle, as @font-face 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 chinacat.tff will be chinacat.

.gif, .jpeg, .jpg, .png, .svg, .tif, .tiff, .webp

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 rainboom.jpg will be rainboom.

Note: As of this writing, image passages are only natively supported by SugarCube (all versions) and the Twine 1 ≥v1.4 vanilla story formats.

.aac, .flac, .m4a, .mp3, .oga, .ogg, .opus, .wav, .wave, .weba

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 swamped.mp3 will be swamped.

Note: As of this writing, audio passages are only natively supported by SugarCube ≥v2.24.0.

.mp4, .ogv, .webm

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 cutscene.mp4 will be cutscene.

Note: As of this writing, video passages are only natively supported by SugarCube ≥v2.24.0.

.vtt

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 captions.vtt will be captions.

Note: As of this writing, text track passages are only natively supported by SugarCube ≥v2.24.0.

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.

Basic Examples

Compile example_1.twee as example_1.html with the default story format:

tweego -o example_1.html example_1.twee

Compile all files in example_directory_2 as example_2.html with the default story format:

tweego -o example_2.html example_directory_2

Compile example_3.twee as example_3.html with the story format snowman:

tweego -f snowman -o example_3.html example_3.twee

Compile all files in example_directory_4 as example_4.html with the default story format while also bundling all files in modules_directory_4 into the <head> element of the compiled HTML:

tweego -o example_4.html -m modules_directory_4 example_directory_4

Decompile example_5.html as example_5.twee:

tweego -d -o example5.twee example5.html

10 KiB Raw Blame History