A tool for working with files in the Fountain screenplay format.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
mountain
test
.gitignore
LICENSE
MANIFEST.in
README.md
run.py
setup.py

README.md

Mountain

Mountain makes it easy to split a single (Fountain-formatted) screenplay across multiple physical files, regardless of the screenwriting (or text editing) software that you're writing with.

See the accompanying blog post for more details on the specific motivations that led to this tool's creation, and why multi-file screenplays may be beneficial to your screenwriting workflow.

Introduction

Fountain is a plain-text markup language for screenwriting.

Fountain is awesome, but it can be somewhat cumbersome to use in practice because most Fountain apps assume that the entire screenplay is housed in a single file.

If you're storing your screenplay in multiple files (say, a file per scene or sequence), then you're likely fighting an uphill battle against your screenwriting software.

This isn't Fountain's fault — it's just a markup language, and file organization is a higher-level concern.

That being said, we can change the equation by building tooling. (See Exhibit A and Exhibit B for examples unrelated to the concerns of file organization.)

Mountain makes it possible to arbitrarily organize the file layout of your screenplay. More specifically, it is a tool for intelligently splitting and combining files in the Fountain screenplay format.*

* Technically, there's not really anything in Mountain that's Fountain-specific, besides the usage of the notes syntax ([[ ]]) to specify "directives" (details below). That being said, Mountain was built specifically to make working with long Fountain documents more palatable.

Directives

Mountain makes use of two directives:

  • include:
  • reference: (and its companion, /reference)

A directive is metadata that is encoded inside of a Fountain note. (Fountain does not currently have first-class support for metadata.)

include: enables a Fountain document to reference another Fountain document.

reference: ... /reference is used to wrap a document that has been inline include:'d.

(Examples are available in the tutorial, below.)

Installation

git clone https://github.com/mjrusso/mountain.git
cd mountain
python setup.py install

After installation, the mountain binary will be available in your $PATH.

Note that Python >= 2.7 is required to run this project.

Usage

The following command will print detailed usage information:

mountain --help

There are two main commands available — mountain join, and mountain split.

Tutorial

Create an outline file (or "manifest"). We'll call the file manifest.fountain, but it can be named whatever you like.

manifest.fountain:

# ACT I

= Meet the **Hero**.

[[include: intro.fountain]]

# ACT II

# ACT III

## Finale

[[include: the-end.fountain]]

This file probably looks similar to how most Fountain screenplays start out, with the exception of the two notes that begin with include:.

Here, include: is a directive that points to another file that should be included in its place.

intro.fountain:

FADE IN:

the-end.fountain:

> FADE OUT.

>THE END<

To produce a single document from these disparate files, execute the following command:

mountain join manifest.fountain screenplay.fountain

This will result in the creation of screenplay.fountain.

screenplay.fountain:

# ACT I

= Meet the **Hero**.

[[reference: intro.fountain]]

FADE IN:

[[/reference]]

# ACT II

# ACT III

## Finale

[[reference: the-end.fountain]]

> FADE OUT.

>THE END<

[[/reference]]

This new document is a combination of manifest.fountain and each of the files referenced in the manifest (intro.fountain, the-end.fountain). These referenced files are included in-line and wrapped in the reference: ... /reference directives.

Mountain works in both directions. To see this in action, edit the combined document (screenplay.fountain), so that it looks like this:

screenplay.fountain:

# ACT I

= Meet the **Hero**.

## The World

[[reference: intro.fountain]]

FADE IN:

A green, open field, stretching for miles in all directions.

[[/reference]]

# ACT II

# ACT III

## Finale

[[reference: the-end.fountain]]

> FADE OUT.

>THE END<

[[/reference]]

At this point, the combined document (screenplay.fountain) is the source of truth, as it has some text that is not in several of the documents that it references.

To update the other documents (i.e., the manifest and each of the files it references), execute the following command:

mountain split manifest.fountain screenplay.fountain

As with mountain join, the first argument is the path to the manifest file, and the second argument is the path to the combined document.

After running this command, manifest.fountain and intro.fountain will update to reflect the changes that were made to screenplay.fountain. (In particular, manifest.fountain will gain a new section header, and intro.fountain will gain a line of action description.) There won't be any visible changes to the-end.fountain, because we didn't make any changes to screenplay.fountain that would affect this file.

manifest.fountain:

# ACT I

= Meet the **Hero**.

## The World

[[include: intro.fountain]]

# ACT II

# ACT III

## Finale

[[include: the-end.fountain]]

intro.fountain:

FADE IN:

A green, open field, stretching for miles in all directions.

Because this works bi-directionally, you can continue to run the join and split commands in any sequence you wish (just remember to keep track of what document(s) are the "source of truth", or you may inadvertently lose some work — Mountain overwrites files). Keep in mind that in most workflows, you won't be frequently jumping back and forth between these two modes.

Additional Notes

  • Use a relative file path in an include: directive (relative to the directory that the manifest file is located in). For example, if you write [[include: a.fountain]], then a.fountain should be in the same folder as the manifest file.

  • Referenced files can be in different folders. For example, [[include: act iii/the-end.fountain]] is legal (the-end.fountain should be located within a folder called act iii, relative to manifest.fountain's directory).

  • Mountain works with any file extension, not just .fountain.

  • If a file that does not exist is referenced in an include: directive, and the mountain join command is executed, then the include: directive will remain in the resultant combined document. (It will not be converted to reference: ... \reference, and an error will not be thrown.)

  • Mountain does not support recursive includes (i.e., a file that is included via include: can't itself include another file via include:).

Development

Mountain can be run without installing it first (useful when developing) in one of the following two ways:

./run.py --help
python -m mountain --help

(Either of these commands must be run from the root of this project's directory.)

Tests

To execute the tests, run the following command:

python setup.py test

The tests use fixtures located at ./test/fixtures/.

Changelog

v0.3.0

  • Change directive syntax. #include is now include:, and #reference is now reference:. #2, #4

v0.2.1

  • Prevent crash when processing directives that expect arguments but do not include non-whitespace characters. #1

v0.2.0

  • Initial release.

Copyright

Copyright (c) 2014 Michael Russo. See LICENSE for details.