DOCSEARCHbyAlgolia
Submit Docs

afterwriting

repository·master·Indexed 43 days ago

https://github.com/ifrost/afterwriting-labs

A post-processing toolkit for Fountain-formatted screenplays, providing PDF conversion, metadata extraction, and statistical analysis. It includes a Node.js CLI for automated workflows, support for .fdx imports, and a system for custom font integration via the fonts-converter.js tool.

Tokens
4K
Snippets
14
Records
18
Agent score
55%

What's inside afterwriting

  1. Overview of afterwriting post-processing tools

    master

    afterwriting is a suite of post-processing tools designed for Fountain screenplays. It provides capabilities for converting screenplay formats, extracting metadata, and performing statistical analysis on script content.

    Core Capabilities:

    • Format Conversion: Convert Fountain format to PDF.
    • Information Extraction: Extract basic screenplay info such as number of pages, action/dialogue time, and locations.
    • Statistics: Analyze location distribution, page balance, dialogue density, and more.
    • Experimental Features: Access advanced metrics like script pulse and primary/secondary character identification.

    Additional Features:

    • Cloud Sync: Loading and syncing with Google Drive or Dropbox (available in the online version).
    • Importing: Support for importing .fdx (FinalDraft) files.
    • Editing: A basic editor featuring auto-complete functionality.

  2. Use Snippets for text replacement in Fountain scripts

    master

    Snippets allow you to define reusable text blocks in your configuration file. These are injected into your Fountain script using the $ prefix.

    Defining Snippets

    Snippets can be simple key-value pairs or nested hierarchies. Hierarchies are flattened using dot notation (e.g., bond.name).

    Example Config:

    {
	"snippets": {
		"protagonist": "$bond.last",
		"antagonist": "Dr. Julius No",
		"bond": {
			"first": "James",
			"last": "Bond",
			"name": "$bond.first $bond.last"
		}
	}
}

    Injecting Snippets

    Use the following syntax in your .fountain file:

    • $snippet: Injected as defined.
    • $SNIPPET: Injected as uppercase.
    • $Snippet: Injected as capitalized.

    Example Script Usage:

    INT. $location - DAY

$protagonist enters the room.

$BOND.LAST
My name is $bond.name.
    {
	"snippets": {
		"bond": {
			"first": "James",
			"last": "Bond",
			"name": "$bond.first $bond.last"
		}
	}
}

  3. Track technical debt using Debt Markers

    master

    The project uses a specific TODO convention to track and manage technical debt. When debt is identified, a TODO note must be added to the relevant file, function, or code fragment, and it must include one or more Debt Markers (the + character) within the description.

    Debt Marker Rules:

    • Mandatory Markers: Every TODO note related to technical debt must have at least one Debt Marker.
    • Debt Limit: Debt for a specific code fragment cannot exceed 5 markers (+++++). Once a fragment reaches 5 markers, no further modifications are allowed until the debt is resolved (the TODO is fixed).
    • Debt Escalation: If debt is increased for a specific code fragment, the debt for the containing function and the containing file also increases.
    • Debt Resolution: Debt is "paid" by fixing the TODO note. If code is modified but the debt is not resolved, the debt must be increased by adding another Debt Marker.
    • Multi-line TODOs: If a TODO spans multiple lines, Debt Markers must be added to the same line (typically the first line) to ensure they are easily parsable.
    /**
 * TODO: Improve performance from O(n^2) to O(n). (+++)
 */
function foo() {
   // ...
}

// For multi-line TODOs, place markers on the same line:
// TODO: (++) Move method to presentation controller
// and add unit tests.
foo: function() {
    ...
}

  4. Use custom fonts in Afterwriting

    master

    You can use custom fonts by providing a JavaScript file that contains the PDF font definitions via the --fonts parameter.

    1. Generate the Font JS file

    Use the afterwriting-fonts utility to convert .ttf files into a compatible .js file. You can provide all styles or just the regular style.

    Full styles:

    afterwriting-fonts --regular MyFontRegular.ttf --italic MyFontItalic.ttf --bold MyFontBold.ttf --bolditalic MyFontBoldItalic.ttf --output my-font.js

    Regular style only:

    afterwriting-fonts -r ./RegularFont.ttf -o my-font.js

    Note: If running from source, use node tools/fonts-converter instead of the global command.

    2. Pass the font file to the CLI

    Use the --fonts flag to point to the generated file:

    node awc.js --source screenplay.fountain --pdf --fonts ./my-font.js

    Recommendation: Use monospaced fonts. Rendering quality may vary based on character height and width differences.

  5. Override configuration using CLI attributes

    master

    You can provide settings or override values from a loaded config file using the --setting NAME=VALUE attribute.

    node awc.js --source screenplay.fountain --pdf --config config.json --setting print_title_page=false --setting scenes_numbers=both

  6. Use the Afterwriting CLI to generate PDFs

    master

    Use the awc.js script (or the afterwriting command if installed globally) to convert .fountain files to .pdf.

    Basic Conversion

    To convert a source file to a PDF with the same name (changing only the extension):

    node awc.js --source screenplay.fountain --pdf

    To specify a custom output filename:

    node awc.js --source my_draft.fountain --pdf screenplay.pdf

    Overwriting existing files

    By default, the CLI prompts for confirmation if the output PDF already exists. To skip the prompt and force an overwrite, use the --overwrite flag:

    node awc.js --source screenplay.fountain --pdf --overwrite

  7. Install the Afterwriting CLI

    master

    The Afterwriting CLI is a command line tool used to generate PDFs from Fountain scripts using Node.js.

    Prerequisites

    • Node.js must be installed on your system.

    Installation via npm

    Install the package globally using npm:

    npm install afterwriting -g

    Installation from source

    1. Download the latest release from the GitHub releases page.
    2. Extract the files.
    3. Run the following commands in your terminal:
    cd afterwriting-labs
npm install
node awc.js --help

  8. Run unit tests via Grunt or Browser

    master

    You can run unit tests using the Grunt CLI or directly in a web browser.

    Using Grunt (Console): Run the following command to execute unit tests in your terminal:

    grant utest

    Using the Browser: To run tests in a browser environment (useful for visual debugging or adding new files):

    1. Run grunt utest to ensure new files are tracked.
    2. Start the development server with npm start.
    3. Navigate to the test runner HTML file at file://path/to/project/test/runner.html.

  9. How to add a new font

    master

    To add a new font to the project, follow these three steps:

    1. Prepare Font Files: Copy your font files (in .ttf or .otf format) into the afterwriting-labs/js/fonts/source/ directory inside a new folder (e.g., FolderWithMyFonts).
    2. Generate JS Font File: Use the fonts-converter.js tool to convert the binary font files into a JavaScript module. Navigate to the afterwriting-labs/js/fonts directory and run the converter command with the appropriate flags for regular, bold, italic, and bold-italic variants.
    3. Register Font: Add the newly generated .js font file to the configuration in afterwriting-labs/js/fonts/fonts-loader.js.
    # 1. Move files to source
# (Manual step: move ttf/otf to afterwriting-labs/js/fonts/source/FolderWithMyFonts)

# 2. Generate JS file
cd afterwriting-labs/js/fonts
node ../../tools/fonts-converter.js -r source/FolderWithMyFonts/MyFont-Regular.ttf -b source/FolderWithMyFonts/MyFont-Bold.ttf -i source/FolderWithMyFonts/MyFont-Italic.ttf -x source/FolderWithMyFonts/MyFont-Bold-Italic.ttf -o my-font.js

# 3. Add to afterwriting-labs/js/fonts/fonts-loader.js

  10. Apply a hotfix to a previous version

    master

    If you need to fix a bug in an older version (e.g., fixing 1.4.0 when master is at 2.0.0), follow these steps:

    1. Modify CI Configuration: Update .travis.yml to allow deployment scripts to run on all branches by setting on: all_branches: true.
    2. Create a Hotfix Branch: Create a branch following the pattern hotfix/X.Y (where X.Y is the major.minor version), for example: hotfix/1.4.
    3. Implement the Fix: Create a feature branch for the fix and merge it into your hotfix/X.Y branch via a Pull Request.
    4. Trigger Release: Merge the Pull Request (or commit directly to the hotfix branch) using the [patch] tag in the commit message to increment the version and publish.

  11. Release a new version to NPM or gh-pages

    master

    Releases are managed by adding specific flags to your commit messages when merging a Pull Request. These flags trigger automated version increments and publishing.

    NPM Release Flags

    • [patch]: Increments the patch version (e.g., 1.1.1 -> 1.1.2) and publishes to NPM.
    • [minor]: Increments the minor version (e.g., 1.1.1 -> 1.2.0) and publishes to NPM.
    • [major]: Increments the major version (e.g., 1.1.1 -> 2.0.0) and publishes to NPM.

    Deployment Flags

    • [gh-pages]: Deploys the project to GitHub Pages.

    Releasing the current master version

    To release the current state of master, create an empty commit containing the desired tags.

    # Example: Release a patch version and deploy to gh-pages
git commit --allow-empty -m "Release [patch] [gh-pages]"

  12. Access afterwriting (Online, Offline, or CLI)

    master

    You can use afterwriting in three different ways depending on your workflow:

    1. Online Version: Use the web-based editor and tools at http://afterwriting.com.
    2. Offline Version: Download and extract the offline package from https://afterwriting.com/afterwriting.zip.
    3. CLI for Node.js: Use the command-line interface for automated workflows. Refer to docs/clients.md for specific installation and usage instructions.