add export / import support for Fountain files

[Reaper10]

add export / import support for Fountain files https://fountain.io/ https://fountain.io/syntax https://github.com/nyousefi/Fountain

[acrisci]

Since Fountain is for screenplays, there's a lot of specialized elements for things like scene transitions and character dialogue that aren't going to be defined in a normal document format. And in general, you can't interpret an arbitrary document as a screenplay. So I believe it is not possible to create a Fountain writer.

However these elements do have a fairly standard format representation on the page. For instance, dialogue is center aligned and transitions are right aligned. So a reader would be possible, although you would lose the intent of the formatting.

But the reader is really the most useful thing because the most common use case for this will be to format a screenplay written in Fountain to something printable for the actors.

I'm going to take a look at this and see if it's something I could possibly do.

[acrisci]

Now I don't think Fountain would be a good fit for pandoc. I recommend closing this as out of scope.

Fountain is not a normal document so its structure cannot be expressed in pandoc form. Conversion would be primarily concerned with presentation. For instance, pandoc has no way to express right-aligned blocks which would be necessary. But there are also some other really complicated presentational aspects of Fountain such as simultaneous dialogue which I think are almost certainly out of scope.

Right aligned blocks were stated to be out of scope in #4451

Pandoc tries to capture structure, not presentational things like this.

[alerque]

I'm not quite convinced. I do see the counter argument, but there are actually quite a few formats for which reasonable representations of intent could be produced, and even a few that could be round-tripped. It's a bit out of the edge I admit, but I'm not convinced it's completely out of scope. It's not a presentation format, it's a specialized take on a plain text format in the same way Markdown is a generalized take on a plain text format. Many of the formats already supported have specialized elements. The question is how many of them can be mapped in a way that would be reasonably useful?

[acrisci]

The question is how many of them can be mapped in a way that would be reasonably useful?

With presentation out of the picture, there is not a good mapping to the pandoc format. Some things map well. Scene headings are headings. Actions are paragraphs. But what is a scene transition if you can't say it's a "right aligned block" and what is dialogue if you can't say it's a "center aligned block"? Maybe that could be solved but then you have simultaneous dialogue which is roughly "a grid block of dialogue blocks" which means you'd have to take into consideration nested blocks which is not something a general document format supports.

For reference, see this image of what conversion would look like.

The alternative is to parse the screenplay and have elements for these things and then put those into the pandoc document format. That represents a pretty big scope increase and it's not at all clear how a markdown writer would handle something like a "scene transition" since there's not anything like that in the markdown spec. And other formats like html could only write that out in terms of presentation. No other document format I know has first class support for sceenplay elements.

[jgm]

Pandoc has Divs with attributes. A dialogue could go into a Div with the attribute class. Then it would be possible to format this as a centered block. A scene transition could be a specially marked Div. Simultaneous dialogue could be a specially marked Div containing two Divs. I see no reason to think that the pandoc AST couldn't capture the structure of a Fountain screenplay. Rendering is another issue; proper rendering might require a filter to interpret the special Divs for the target format, but that's entirely possible.

[rubenxyz]

Thank you @acrisci for lifting the technical challenges with simultaneous dialogue and other elements. In my experience, simultaneous dialogue is rarely used. The technical solutions needed for using pandoc and fountain is out of my depth. But I know that having pandoc come to the rescue for us screenwriters would be a true blessing. There is Afterwriting but it's a bit clunky with downloading the files, no offence to the developer. Would be so amazing to just have CLI app and thats it. If anybody with the skillset could take a look at this, at least this writer would be forever grateful.

[jgm]

Would the ability to write fountain or the ability to read it be more useful? Looks like there are a lot of apps available to process fountain: https://fountain.io/apps Just trying to get a better sense of why pandoc would be useful.

[rubenxyz]

Thank you for considering this feature, @jgm!

My guess is that 99.9% of use cases would be that you have your screenplay that you have written in plain text, using Fountain, but if you want to share it with a director or producer, you need to have it exported to the industry standard format and share it as a PDF.

There are many proprietary application that does this but they are bloaty and expensive. The closets things to a CLI-program for exporting fountain-screenplays is Afterwriting which both has an online-application and a CLI which uses node.js. But you have to download the files to the working directory and it can be a little bit clunky. Would be amazing if pandoc could handle this, perhaps with a handful of flags for some options.

I don't have any relevant skills make a fork myself and contribute but would be forever grateful to whoever would be interested in this.

[acrisci]

I think that the approach in this issue is a good one. I just started working on something else and forgot about this.

[jgm]

I don't think a fountain reader would be too hard to create. There'd be questions about what it should parse things to -- one could use Divs and Spans with classes, as described above, but then a lua filter would be needed to format appropriately in PDF/LaTeX.

[earthbound19]

wrap is a CLI tool that converts fountain format to pdf. Its parsing of fountain might inform any effort on this.

IMO dual dialogue in screenplays should not exist, and I would not support it if I wrote a converter.

Why it's a bad idea:

• It's a programming and layout nightmare to handle
• It only addresses the case for two characters, it doesn't address the case of many characters speaking at the same time. What do you do with three characters who speak at the same time: dual dialogue followed by action that mentions that a third character speaks at the same time? For four characters? Dual dialogue followed by action that says two other characters also speak at the same time followed by dual dialogue? Too complex. What you should do with three, four or more characters is what you should do with two: just mention in action that they all speak at the same time, then write it out for each of them under character slugs as usual. Or just write in action that they all say some things of some nature at the same time, and leave it to the actors to improvise.
• Characters speaking at the same time can be improvisational territory that doesn't need to be written verbatim and followed besides

[rubenxyz]

@earthbound19 Thanks! Looks cool, will check it out!

[AndreaMonzini]

Hello, i add some info that could be useful to use Fountain with Pandoc.

Would the ability to write fountain or the ability to read it be more useful?

@jgm personally i think that it would be very useful to read Fountain with Pandoc and be able to export it ( to HTML, EPUB, PDF, etc...)

I contributed to a Fountain Blender addon by @tin2tin https://github.com/tin2tin/Blender_Screenwriter

fountain2pdf by @Tagirijus https://github.com/Tagirijus/fountain2pdf Fountain to HTML https://github.com/Tagirijus/fountain2pdf/blob/master/fountain2pdf_2html.py Fountain to PDF https://github.com/Tagirijus/fountain2pdf/blob/master/fountain2pdf.py

screenplain by @vilcans https://github.com/vilcans/screenplain Fountain to HTML https://github.com/vilcans/screenplain/blob/master/screenplain/export/html.py Fountain to PDF https://github.com/vilcans/screenplain/blob/master/screenplain/export/pdf.py

The Courier Prime font optimized for screenplays with Open Font License (OFL) https://quoteunquoteapps.com/courierprime/index.php

thank you

[rubenxyz]

Great tips, @AndreaMonzini! Thanks! I just started this repo called awesome screenwriting tools. Want to be the first contributor? https://github.com/rubensz/awesome-screenwriting-tools

[AndreaMonzini]

Great list @rubensz ! I hope that Pandoc will be added to command line tools of course !

[paulrpotts]

Hello, came here via a Google search to see if pandoc supported Fountain... just came across Fountain today.

I'm not an actual screenwriter, just a blogger/newsletter writer, but I use Markdown & pandoc every week to produce HTML for a Tinyletter newsletter, and have been experimenting for a while with other output formats to eventually let me organize posts into books.

My primary interest would be reading Fountain, not writing it. I get that the distinction between semantic parts and layout is even worse than normal with this format - definitely not ideal, but I'd still like to see it working as I hope to get into screenplay formats, particularly for writing radio drama. So a nice way to generate an HTML fragment from a Fountain file using pandoc would be great for me. I don't care about the simultaneous dialogue thing - that seems ugly and not really required. Way back when I wrote short stories that played with typography and featured simultaneous narrations in parallel along the page, but for that I would likely turn to a real WYSIWYG page layout tool of some kind.

[tucnak]

I subscribe to everything @AndreaMonzini is saying. Being a screenwriter myself, I've come to appreciate simplicity of Fountain as a thing of its own more and more over the last couple days. "Dual dialog" style of writing is complete nonsence, and I don't think anyone in the industry does this. I mean, you can come up with whatever wicked form of script, but in the end the actors expect to read a certain thing which is more or less uniform w.r.t. the common script structure. I wish I was sufficiently proficient in Haskell to bring this home; that said, I don't see a single reason why pandoc wouldn't be able to support Fountain. Having successfully used it for Latex, Markdown and the numerous likes of it, I'd expect it to support Fountain as well, to whatever extent possible.

[mb21]

Since wrap is open source and already converts Fountain to HTML and PDF... (presumably with better support for some of the more advanced fountain features than we could ever implement in pandoc and its fairly generic document AST)... anything in particular people would want from pandoc? Is it just because you have pandoc already installed, or..?

[tucnak]

@mb21 I, for one, don't like certain aspects of Fountain and would rather generate AST from a slight dialect of it, suitable for different exotic scenarios, like AI inserts (generated text) and stuff like that. This would be trivial to do if pandoc implemented a Fountain writer.

[jgm]

Have you thought about creating a custom lua writer for fountain? https://pandoc.org/MANUAL.html#custom-writers

[jgm]

Pandoc now allows the use of custom readers, written in Lua. I have written a reader for Fountain -- it probably still needs a lot of work, but it's a start.

I'm attaching the script here, as well as a reference-doc designed to be used with it if you want to produce a docx from your fountain script. (For other formats, more customization would be needed -- CSS in the case of HTML, a Lua filter for LaTeX/PDF.)

To use it,

pandoc -f fountain.lua sample.fountain  -o sample.docx --reference-doc fountain-ref.docx

EDIT: improved versions:

fountain-ref.docx fountain.lua.txt (you'll need to rename this as fountain.lua)

[jgm]

I have now set up a little repository containing the custom reader and the necessary auxiliary files, plus instructions for converting Fountain files to HTML, EPUB, PDF, and Docx using pandoc. https://github.com/pandoc/pandoc-fountain

[iwelch]

fountain to pdf:

$ brew install wkhtmltopdf
Warning: wkhtmltopdf has been deprecated because it is discontinued upstream!