lichendust/meander

📝 A powerful, portable utility for production screenplays and manuscripts

📝 Meander

Meander is a tiny, single-binary, portable utility for the production writing markup language Fountain.

Meander has a focus on beautiful formatting on the page, as well as being available and fully functional on as large a number of platforms as possible — most of the highly-regarded industry standard tools are prohibitively expensive simply by virtue of only being available on Apple devices.

Instead, Meander lets you write wherever you like, on whatever platform you like, with any plain-text editor you like. Or, like some of us, on a bunch of them at once. You can install it anywhere, run it anywhere and take it anywhere, by design. It's licensed under the GPL 3.0, to ensure it remains available and modifiable.

Building on top of Fountain, Meander can create all sorts of production documents, including —

• Screenplays
• Stageplays
• Novel Manuscripts

Meander also extends the core syntax with simple, clever and worthwhile features to make it more powerful.

You can download Meander from itch.io under a 'pay what you want' model, which includes free.

In spite of this quite scary table of contents, Meander is extremely simple to use. There's just a lot to cover!

Contents

• Usage
• Basic Commands
  • Render
  • Merge
  • Gender
  • Data
  • Convert
• Render Flags
  • Scenes
  • Formats
  • Paper Sizes
  • Hidden Syntaxes
• Syntax Extensions
  • Text Styling
  • Modifiers
    • Includes
    • Headers / Footers
  • Counters
  • Title Page
• Compilation
• Editor Support
• Future Plans
• Attribution

Usage

Meander is very simple to use. Render your first screenplay with —

meander myfilm.fountain

The output, in this case myfilm.pdf will be placed alongside the original.

You can then get really adventurous by naming the PDF file yourself —

meander myfilm.fountain "My Magnum Opus.pdf"

Basic Commands

The base Meander commands, which should always be the first argument, are —

• render
• merge
• gender
• data
• convert

There's also the usual self-explanatory stuff —

• help
• version

Meander's help command is extremely powerful and provides detailed information about every command, flag and setting available within Meander, as well as useful resources like a built-in cheat-sheet for Fountain —

meander help fountain

Render

meander render

The default, implied option. Creates a PDF of your input file. See Render Flags for the myriad additional options.

Merge

meander merge source.fountain [output.fountain]

Meander supports a multi-file workflow. Merging collapses your multi-file screenplay into a single text file. The render command does this automatically, but merging allows you to output the combined plain-text as needed.

You'll need to use the include syntax in your screenplay to insert another file —

include: scenes/some_file.fountain

Included paths are always relative to the file in which they're written.

Gender

Meander comes with the ability to analyse the genders of your characters, giving you a detailed print-out of how they break down across the whole screenplay and whose voices are heard the most.

Calling —

meander gender some_film.fountain

— will output a terminal-friendly version of the stats for that file (and its included files, if applicable).

The information backing this analysis comes from a custom boneyard comment¹ in the root file of your screenplay.

/*
    [gender.male]
    Ashby | Ashby Santoso | Captain Santoso
    Jenks

    [gender.female]
    Rosemary
    Sissix
    Kizzy

    [gender.<custom>]
    Dr. Chef

    [gender.ignore]
    Market Stall Owner
*/

Characters will be assigned the gender from the heading they reside under. Any word can used to define a gender: this means you can represent non-binary and queer characters, as well as non-humans in science fiction. Oh and non-English writers aren't stuck with their reports saying 'Male' and 'Female'.

The only reserved word is ignore. Characters assigned to ignore will be left out of consideration in the breakdown, useful for single-appearance characters or special cases like 'the crowd' shouting back at a main player that probably shouldn't count toward any totals.

Any characters found in the screenplay but not in the gender table will be reported as 'unknown' and classified in the statistics under that additional group.

Characters can also have multiple names — Ashby and his occasional full name Ashby Santoso, for example. By writing each name in with a pipe separating them (see the table example above), all instances of the character's appearances under different names will be combined and handled as if they are one. The report will use the first name provided as the name.

Only include the actual gender data in the boneyard, with at least one [gender.x] header as the first non-whitespace text inside. Whitespace, indentation and letter casings are not considered: the way the name is written in the table is how it will appear in the output.

You can put the gender table anywhere, so if you want to shove it way down at the end, Meander doesn't mind. If you supply more than one table (such as across multiple included files), those new characters will be combined.

For instance, you could create a stub file that includes and therefore outputs the statistics for a whole season of episodes.

Existing characters are not changed to prevent confusion: always define a character in a single location. This was changed in v0.2.4, because the pros actually outweighed the cons of this.

Data

The data command generates a JSON file containing the content of and data about a given Fountain file.

meander data [some_film.fountain] [data.json]

This is provided as a useful data exchange format. Rather than conversion to other screenplay tools, this is intended for use with non-screenplay software, such as furnishing production-tracking tools with screenplay metadata or dumping statistics into spreadsheets.

The resulting JSON blob is a dictionary containing four entries —

• meta — information about the version of Meander and the JSON format.
• title — a dictionary of the title page entries.
• characters — a list of all characters in the screenplay, their alternate names and gender from the gender analysis table, as well as the number of lines they actually speak.
• content — a syntactic breakdown list of the screenplay content, with each paragraph or dialogue entry, etc., tagged by its type.

Convert

Meander can convert .fdx files from Final Draft to Fountain.

meander convert input.fdx

You can override the output path with another argument, as with other commands.

Meander parses the XML structure and attempts to write out a decent approximation in Fountain. It also adds force-characters to text that it knows Fountain would not recognise as its Final Draft designation.

Because Final Draft has a Fountain importer, Meander does not export to .fdx.

This command is currently considered experimental. I have limited access to example .fdx files, especially those demonstrating complex features like page-locking.

Note that Meander's non-standard syntax extensions are a known issue for importing with Final Draft. If this is a requirement, you should limit your use of any non-standard syntax for the time being.

Please open an issue for any other import/export concerns. If there is sufficient need, Meander can easily support its own export mode to support more Final Draft features.

Render Flags

Almost everything in Meander has a default specification. For the following sections, the item marked with an asterisk* is the default, implied parameter. If that's the one you want, you don't need to specify it.

Scenes

In Fountain, scene numbering is traditionally handled by tacking #12# (for example) to the end of a scene heading to denote it as the twelfth.

However, Meander offers more options during rendering —

meander -s input
meander --scene input

• input uses the original input markers from the text.*
• remove removes all of them from the output.
• generate creates a new sequence starting from 1, which increments correctly across multiple files.

If you're not familiar with Fountain, if you choose to write in scene headings manually you're not limited to numbers; you can go mad with stuff like #1.3-A#.

Formats

Meander also offers different formatting options. Right now, it comes with —

• screenplay*
• stageplay
• manuscript
• graphicnovel
• document

These formats can be specified as part of the title page, in the form format: screenplay, but the command line flag will take priority.

meander -f screenplay
meander --format screenplay

Paper Sizes

Meander also supports different paper sizes —

• US Letter*
• US Legal
• A4

Again, the paper size may be included as part of the title page, in the same form paper: A4.

meander -p A4
meander --paper A4

Hidden Syntaxes

In some templates, certain syntaxes are hidden by default. Most of them are intended for use during the writing process for reminders, alternate versions, outlining, bookmarking, etc.

For the screenplay template, these include —

• # sections
• = synopses
• [[notes]]

(For the manuscript, document and graphic novel templates, Sections are used for chapters, headings and page/panel markings respectively, which means they're enabled by default.)

During the creative process, printing a draft to take away and read and mull over is incredibly valuable — and so are your notes.

Running Meander with the relevant flags —

meander --notes --synopses --sections

— will ensure they remain printed.

Syntax Extensions

Text Styling

The core Fountain spec includes —

• *italics*
• **bold**
• ***bold italics***
• _underlines_

Meander also includes —

• ~~strikethroughs~~
• +highlights+

Modifiers

Includes

You've already seen includes above, but just to re-iterate: you can import another Fountain file into the current one using the following line —

include: some_file.fountain

The path is always relative to the file in which the include is written.

Headers / Footers

header: Some Header
footer: Some Footer

Headers and footers add their contents to the top and bottom of all subsequent pages starting from the page on which their declaration would appear.

You can also specify left, right or centre alignment by using pipe characters —

header: left | right
header: left | centre | right

footer: left only
footer: | centre only |
footer: | right only

In fact, the default header for every Meander document is defined like so —

header: | #PAGE.

(See also Counters below.)

They can also be stopped by leaving them empty —

header:

You can set a header anywhere in the text, but it will only take effect on the following page: set a new header before a manual page-break then.

Headers and footers are also valid title page elements in Meander, so if you're just setting a single one for the entire document, you should do it this way — it's useful for maintaining compatibility with other Fountain tools.

Counters

Sometimes, you might want a numerical counter for tracking values across a screenplay, independently of say, the scene numbers or the page count.

Meander's syntax for this is a pound sign # followed by a keyword of your choice. This word should be made of only letters and underscores and is written in ALL CAPS by convention —

There are #COUNTER apples in the box.

You can also start or reset any counter to an arbitrary value —

#COUNTER:10

You can also employ alphabetical counters, by initialising them with a letter —

#COUNTER:A

Note: you cannot change a counter's type after it has begun.

There are also a small number of built-in counters that are available to use. None of these counters may be modified or reset —

• #PAGE the current page number.
• #SCENE the current scene number (only available when using generative scene numbers).
• #WORDCOUNT the total word count of the document.

Title Page

Fountain's title page consists of the following items —

• title
• credit
• author
• source
• notes
• draft date
• copyright
• revision
• contact
• info

Meander adds the following items —

• paper
• format
• header
• footer
• more tag
• cont tag

More and cont tags are used to override the default (more) and (CONT'D) text used when dialogue is broken across a page boundary. You should specify them inclusive of brackets —

more tag: (more)
cont tag: (CONT'D)

Note that in Meander, title page elements are case insensitive and whitespace agnostic: more tag: is the same as MORETAG:. This may not be true in every Fountain tool.

Compilation

Building Meander is super easy. Install Go — check the go.mod file for the most up-to-date information on versions, then clone this repository and run:

go build -ldflags "-s -w" -trimpath ./source

This command will build the smallest possible binary. With that, you're done. There should be a shiny executable in your repository, all ready to run.

Great care has been taken to minimise the use of libraries in Meander for future-proofedness and maintainability. We currently only rely on —

• gopdf — source, which is how Meander writes its PDF files.
• isatty — source, which is just used to detect whether we can use colours in terminal outputs.

All current versions of dependencies are vendored into this repository to defend against unexpected deletion. Each of these packages are redistributed under their original licenses as defined in each vendor subdirectory.

If you're building for an esoteric platform, like Plan9, Dragonfly, odd BSD flavours or even Android, you are strongly advised to compile Meander yourself. Only you know the specifics of your hardware or choice of emulator.

Go can compile for all of these targets and more, and you can verify the list of compatible systems and architectures with —

go tool dist list

Editor Support

While there are several generic packages available for screenwriting with Fountain available for most text editors, I have built first-party support for Meander, its syntax and a number of extra tools into a Sublime Text package.

Meander for Sublime Text should also be treated as a reference implementation for other packages and further text editor support.

Future Plans

I plan to add starred revisions, page-locking and expanded language support to Meander.

Most editorial changes of this variety require more syntactic changes to Fountain itself. Most other tools get around this by moving the goalposts and putting your documents in some arbitrary binary format, which will never happen with Meander, because it violates the entire purpose of Fountain in the first place.

Please check the Ideas tag for my current proposals to this effect and give any suggestions or feedback you may have.

Attribution

The include feature was originally from the tiny Python utility Mountain, where it used the note syntax [[include]].

Footnotes

1. 'Magic comments' are generally to be avoided, but this was intentionally designed to play nicely with other Fountain tools while ensuring the gender table can still travel with the screenplay, instead of being fed in by a separate file. ↩

meander's Issues

Syntax idea: starred revisions

Every other Fountain editor that supports starred revisions does so by switching the container format to some arbitrary binary or zipping the text file alongside some other blobs of diff data.

Meander won't ever do that. No binaries, only plain text. The zip is somewhat acceptable, but once you've opened the Pandora's box of adding extended syntax... you may as well just continue. Looking at you, John August.

I've experimented with starred revisions to a surprising degree of success by having Meander simply read Git and Mercurial diffs as a switching mode in the parser. I based the target historical versions on tags rather than commits, so that tags could be moved around to provide the writer's preferred historical commit (in case they thought to add something new to the pink revision and now needed to bump it).

As a simplification, the working copy (whatever was on disk at that moment) was always compared to a historical target. You couldn't compare two arbitrary historical points unless you checked the newer one out and compared it to the older.

The issue was that in semi-rare cases, Git would take it upon itself to do it's job very very efficiently, which is storing the diff in the smallest possible form. This meant that some changes were not localised to the site of the writer's actual changes and would result in a big stripe of green or red in the diff — now half the page is starred unnecessarily.

The other issue with this is that asking the average non-technical writer to interface with Meander is already a bit of a stretch, let alone asking them to also deal with Git. The hurried writer making amendments in their trailer on a break is hardly going to want to deal with Git's utterly maddening CLI interface to move a tag around.

---

Instead, it seems like it might be a better idea to provide a tag in syntax that writers can use to mark changed paragraphs. If they want to version their screenplay, they can do so with whatever tools they like externally. As mentioned before, working copy is always the canonical one in this paradigm.

Anyway, here's a pseudo-syntactic example of what this might look like:

        DANIEL @pink
    (rage consuming him)
_I DRINK YOUR MILKSHAKE!_

The writer can then export the screenplay with the -r pink flag and all items tagged as pink will be marked with stars.

It could also be combined with the page-locking feature, where pages with headers featuring these tags would be considered the only pages in the output: a -r pink build would then create a PDF with only those pages ready for printing.

I want some feedback on this idea before I implement it natively, but it's otherwise a relatively easy addition to the project.

Command feature: page-locking

This is a feature that's regularly claimed to be difficult to implement in Fountain.

I envision this as follows:

Meander would have a new pre-processor command step which would expand all scene numbers, counters and other variable values, then reconstruct the screenplay post-pagination, enforcing split paragraphs and (more)/(cont'd) continuation. It would manually insert page breaks and declare new, static headers and footers for each of the "pages" it has now created in the text file.

The writer can then manually adjust the header sections, scene numbers and other values that now increment differently in a page-locked scenario. Writing between the page-breaks will extend that "page" with its new, enforced values.

Using a custom variant of the page-break syntax (perhaps five equals ===== instead of three), Meander will recognise these as being locked-page breaks and not increment values like page numbers when passing them. The writer can then modify the now hard-coded headers with a new counter, such as #PAGE-#SUBPAGE:A (3-A, 3-B, etc.) to increment any alphabetical sub-pages they're adding.

One of the main limitations of this right now is guaranteeing that everything will play ball and reconstruct perfectly again after being manually split. There's certainly zero guarantee of any proper rendering in any other Fountain tool, assuming you were only writing with core Fountain syntax, and there's no guarantee of internal consistency between versions of Meander if we tweaked a template later on, which is... annoying.

Feature request: Add margins parameter

Not every screenplay software, nor writer for that matter, uses the same page formatting. So it would be great to have parameters to override the margins when rendering to PDF. As an example, I am converting from FDX to Fountain and then to PDF. Compared to the original FDX, the margins are slightly off which results in an extra 6 pages.

Why are scene headings underlined though?

This is a pretty cool little doodad you got here. I may donate in the future, but one confusion I have is that: why does it underline scene headings like from (for example) the Big Fish one from https://www.fountain.io/syntax website.

BigFishy.pdf

I used your program to render the Big-Fish.fountain file to BigFishy.pdf, but I'm puzzled why the scene headings are underlined. Never seen any other converter or render program do that. So I'm more puzzled and confused if anything. Additionally, I want to comment on the fdx converter support, I didn't think this warranted a new issue thread, so I'll mention it here:

You can use writersolo.com to convert fountain files to fdx to see how the syntax changes in the xml markup. If I could make a suggestion, you could just have the converter completely omit stuff that would be only for final draft users only like page locking and stuff like that. Just ignore it and focus on the elements that would be practical for plain text editing like fountain in vim or emacs.

Command feature: archive mode

A flag for the merge command called --archive, which would expand and bake all syntax features into the text:

• includes
• scene numbers
• counters

It would also sanitise Meander of any other Meander-flavoured syntaxes, such as wrapping header: updates in note syntax to obfuscate them. It's essentially a command modifier that "un-Meanderises" any document, suitable for importing into Final Draft or simply archiving the file long-term at the end of a production.

Current limitation: the parser kinda sucks and is desctructive, so it makes writing this kind of feature require a lot of duplicated logic and code. A proper tokenising parser that can bi-directionally reconstruct all of the original text would enable this feature handily and fix a bunch of edge programming that's currently in other parts of Meander right now.

Errors when using render or data for fountain file converted from FDX

Using meander on Apple M2.

meander convert file.fdx - works fine and creates a .fountain file.

Then when running meander against the newly created .fountain file using either render or data option, gives the following error:

meander render file.fountain or..
meander data file.fountain

panic: runtime error: index out of range [3891] with length 3891

goroutine 1 [running]:
main.syntax_parser(0x140000940a0, 0x140000ebdc8, {0x14000154000, 0x1b813})
	github.com/qxoko/meander/source/parser.go:692 +0x21f8
main.command_render(0x140000940a0)
	github.com/qxoko/meander/source/command_render.go:57 +0x90
main.main()
	github.com/qxoko/meander/source/meander.go:35 +0x40

For reference, there are 3894 lines in the converted .fountain file.

If I add an extra line at the end with any character such as ".", then it works fine.