Screenplay Markdown
Tuesday, August 9, 2011 at 11:55AM Or: How I Fought The Battle With Usability and Lost, But Received Actual Productivity as a Consolation Prize
Thanks in no small part to the wise ramblings of Merlin Mann, I’m hooked on the portability and flexibility of doing as much of my creative work as possible using simple text files stored on Dropbox. Documents I’m working on are always accessible to me wherever I go. I can even apply useful formatting to these plain text files, regardless of which writing software I’m using, with the relatively intuitive syntax of Markdown. Markdown is, in the words of its creator John Gruber:
…a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Apps like WriteUp on iOS and Byword on the Mac show me what my Markdown-formated text will look like in HTML. Here’s this very blog post in Byword — first the raw markdown text:
;)
And here’s the HTML preview:
;)
Because the files are plain text, there’s no way to mess up their contents or formatting by opening them in an incompatible app. The value of this has been made evident to me recently as I tried to live the Apple dream and bounce some work back and forth between Apple’s own Pages app on iOS and Mac. The file became bloated with unnecessary crap, formatting was removed, comments were deleted, and use of niceties such as curly quotes was inconsistent. I won’t even mention the hassles of manually emailing the document back and forth between devices, since Apple is actively solving that issue with iCloud. But iCloud won’t be so hot for Pages documents if the iPad version persists in stripping out critical formatting and features from documents created on the Mac.
Markdown solves all these issues by eschewing WYSIWYG and instead prioritizing something that, I’ve come to realize, might be far more valuable: keeping your hands moving on the keyboard.
The putzing-free fluidity with which I edit Markdown documents across devices has made me even more grumpy about the sorry state of mobile screenwriting. On iOS, I use two screenplay writing apps that support the industry-standard .FDX format: ScriptsPro and ScriptWrite. In all honesty, both have tremendous potential, and tremendous bugs. I’ve been skittish about using either for real work. Celtx Script, which I wrote about when it launched, is stable and lovely, but does not support FDX. Like Merlin (roughly) said in a recent episode of Back to Work, “I’m not going to row out to your island.”
Out of desperation for a mobile screenwriting solution that would be as fluid and flexible as my Markdown text work, I engaged in some procrasductivity the other night and began researching ways of writing a screenplay in plain text. After much fiddling, I finally remembered that Final Draft actually has a heuristic for guessing the implied screenplay formatting in a plain text file. If you feed it something like this:
;)
It will correctly import it as this:
So the ultimate mobile screenwriting solution may be, for the time being, your favorite among the many lovely Dropbox-based plaintext writing apps out there.
Are other screenwriters as dissatisfied with their workflow as I am? Is there a part of your workflow where you’d give up WYSIWYG and accurate pagination to just get words on the page in a way that freed you from a specific device, and specific software? Or do we expect that Final Draft, Inc.’s promised-but-delayed iPad app will be what we’ve been wanting? Or that one or more of the existing iPad apps will become awesome?
Screenwriting is challenging enough that I often catch myself “fiddling” (in the Merlin Mann definition: spending more time putzing with the tools than doing the work) with ways of making it more visual and intuitive. And now here I am fiddling with a way of making it less visual for the sake of more portability.
Maybe I should just shut up and write. Which is exactly what I did after I got this all figured out. I put all the toys away and wrote a six-page treatment for a feature I want to make.
I wrote it in Markdown. And yesterday, as I was out walking my dog, I got an idea for a small tweak. I sat down on a bench in the sun, pulled out my phone, and made the adjustment while it was still fresh in my mind.
Awesome.
Stu
Apparently I’m either not crazy, or not the only crazy person out there. Turns out others have experimented with tools to enable plaintext screenwriting.
- Via @dansturm: screenbundle for TextMate
- Via @erichocean: eleanor
- Via @vilcans: screenplain
All seem to behave like Final Draft in interpreting plain text into a screenplay format. Which is nice, but it’s a one-way street. I’m thinking there might be a place for a plaintext screenplay format with markdown-like syntax, and a WYSIWYG desktop app that works with that format as easily as FDX.
The syntax would be necessary for special cases, such as forcing a Scene Heading element even when the first characters are not INT or EXT, simultaneous dialog, title pages, and centered text for the all-important “THE END.” Markdown syntax would be used for **bold** and *italics,* but being screenwriters, we need _underlining_ too, and the ability to _**combine**_ them.
This way we could have the niceties of a dedicated desktop WYSIWYG app combined with the edit-anywhere flexibility of plaintext.
Reader Comments (63)
This is a great project. I think plain text is great even on the desktop, since some programs like Word take forty five minutes to start up on a less powerful machine. I would like to suggest not to use key words like INT. or EXT. for formatting, because they are different in different languages (German in my case). That could make the applications unnecessarily big and complex.
Mobile keyboards make it hard to access special characters, so maybe bbold and iitalic would be easy to read an simpler to enter. Double spaces seem great because they're so natural to write, but I think the app should make them subtly visible when in editing mode, since they might be hard to find.
Just some thoughts. I'm really looking forward to using spmd. The extension could be .spmd.txt so that every text editor can open the files.
Regards,
George
Hi George,
A developer pointed out to me that other languages might not use the INT. and EXT. conventions, and I did some research on that. I've seen English, Spanish, Portuguese, and French scripts that all use them. So I'm including it in the spec, but you will of course have the option to double-space any line to force it to a Scene Heading.
But given the popularity of INT. and EXT., I don't want to make double-spacing the only way to create a Scene Heading.
I think your suggestion of subtly showing the spaces is great.
This is a fabulous proposal Stu and I agree with almost all your syntax suggestions.
The big missing element for me is script navigation. I write with the buggy and frustrating 'Movie Outline' purely because it has a navigation panel that allows headings that are NOT the slugline (which are often are repeated and meaningless after a few weeks away from your script.
I would suggest that you have a Heading or Navigation line syntax that could be utilised by the desktop app to create a navigation pane - it would be invisible when printing or formatting the script. Something along the lines of what HTML does would be useful and could even he hierarchical ie/ maybe something like "<N1 ACT 1" for a level one navigation heading and "<N2 Bob Jumps the Shark" for a second level navigation heading. These 'Navigation Pane' lines start with "<N" and then a digit followed by text would be ignored except for ,optionally, creating a navigation pane. The writer could of course choose to use one level or two, three of four depending on whatever writing paradigm floats their boat. They could also default to Slugline navigation if no navigation headings are entered.
That makes total sense, actually you can use INT. and EXT. in German too, I must have been thinking DAY, NIGHT.
Keep the procrasductivity coming!
Based on some feedback from Grant, above, and Kent in his blog post, I've begun a section on notes, synposes, and sections — let me know what you guys think.
I'm working on a parser implementation, so naturally, I bump into parts of the spec that can be clarified and improved. Here's one:
"We look for common transitions such as CUT TO: and BACK TO:, but we also assume a transition if a line ends in a colon and is followed by a slugline." This means that you are free to have action or dialogue after a CUT TO, but not after a nonstandard transition like VOMIT-INDUCING DISSOLVE TO. This is inconsistent. Either all transitions have to be followed by a slug, or we must allow nonstandard ones to be followed by anything.
Suggestion: Use the doublespace escape again! Assume any line ending with colon is a transition. Skip the list of common transitions. To make an action paragraph out of a line ending in colon, add two trailing spaces. Also require at least one blank line before and after a transition.
Interesting suggestion. In speccing things out, I assumed a few things. One is that any parser would look for sluglines first. The other is that folks wouldn't mind if certain industry-standard "rules" were enforced. One of those rules ia that the only thing that can follow a transition is a slugline.
I often end action paragraphs with colons and I have see other writers doing this as well. Even with the extra condition of all-caps, I'd be worried about too many false-positives.
If SPMD were to require that a slugline always follows a transition, how would that change your suggestion?
Then the rule would be "any line ending in a colon, followed by a slug, is a transition." It may still be a good idea to allow doublespace to mark something as action instead just in case someone wants to end an action paragraph with a colon. What about requiring a transition to be upper case? (There is no such requirement in the spec now AFAIK.)
I think that's the best option — all caps + ends in colon = transition, unless followed by a double space. I'll amend the doc.
UPDATE: Done, check it out and let me know what you think.
BTW Martin, if it helps your testing, I have a longer sample SPMD file here:
The Hurt Locker Sample.spmd
Should match the first few pages of the PDF available here:
http://www.mypdfscripts.com/
I like the changes, but I'm thinking about the "all caps" rule. It's a bit inconsistent since a slugline doesn't have to be in caps. If we remove the "all caps" rule, there will be false positives only for single-line paragraphs that end with a colon and are followed by a scene heading. Is there a use for such a thing?
INT. BEDROOM - NIGHT
CHARLES peers through his bedroom window. He can make out a dark (wolflike?) shadow moving across the roof of the building across the street.
Charles switches off the light to see better.
He sees:
EXT. ROOFTOP - NIGHT
The WOLFMAN, half man, half woman, runs across the adobe tiles.
Perhaps not a good example, but you'd not want "he sees" to be a transition here. Question is whether anyone would ever write something like this?
I'm not sure what I'm arguing for here. Perhaps the transition rules are good as they are.
Thanks for the longer script by the way. I'm afraid it will take some time to get the index card stuff working. I'm focusing on the actual script text first.
A few constructs I found that I wonder whether they really are/should be valid:
THOMPSON (headset)If he brings that electricity back here, I'm going to put a bullet in his tail.
The "(headset)" part makes that line not all caps, and not regarded as a character name. We could of course make an exception for things within parenthesis.
There's a similar one that more clearly is wrong:
SANBORN Jesus. (into walkie) I think he
figured out we were EOD. You're good, Blaster One.
Hey Martin,
Regarding action lines with colons before slugs — yes, I see these all the time, exactly like your example.
Truth is, I see little use of transitions these days. They might be a bit stodgy, but maybe more significantly, there's always a push to drop page count, and stripping transitions out is a really easy way to do that.
Good catches on the HURT LOCKER example — those were mistakes I made when creating the doc. Fixed now.
Although do note that the "figured we were EOD" line does have the paren embedded rather than on its own line. The writer does that occasionally in this script.
Any paren on the same line as a Character element, such as:
DARTH VADER (V. O.)...should always be in caps too, so the caps requirement stands for Character.
More errors fixed in the sample file just now if you want to re-download.