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)
Thank you for this. I made the markdown + dropbox switch a few months ago after listening to Merlin, being mostly confused, and finally seeing the light. It has been the best workflow change I've ever made.
No longer do I care when/where/what app I have available, I can write whenever the ideas are there to be written down. I can't believe that more people aren't shouting aloud how great this workflow can be.
I didn't know FD was able to interpret txt into scripts, but luckily I actually started writing my scripts in txt in basically that formatting already. Thanks again for the post.
Hmm, this has me thinking. At this point I've basically accepted that my iPad can't be used for scriptwriting/editing, which is sad as that's a big part of what I bought it for. Even the FDX Reader app proved slightly frustrating simply for viewing since I was working with people using Final Draft 7 which produces the older FDR files.
Switching to a plain text workflow could solve all of these problems. I write everything else in plain text. However, doing the formatting on an iOS keyboard is rather awkward at times. If there's one place where auto-formatting and autocompletion would be great, it's there, and yet there's no great tools available.
Perhaps the best solution is a standard plain text formatting for scripts. One that screenwriting apps can read and write to, but always leaving you a plain text file that can be viewed/edited with any text editor. Maybe we need an actual Markdown for scripts.
Yep Joey, that's exactly what I was thinking.
There is a screenwriting bundle for writing in text files, but it strays from Makrdown and uses some of it's own syntax (http://code.google.com/p/screenbundle/). Really writing the way Stu has illustrated above is the easiest way to work.
To get around some of the formatting difficulties I use textexpander to help me out.
typing 'eext' on my keyboard expands to:
EXT. (cursor) - (cursor)
(return)
(return)
When it expands, the cursor is sitting at the first (cursor) designation, then by hitting 'tab' it jumps to the second, and 'tab' again takes it all the way to the bottom.
Markdown + dropbox is great. If you add textexpander, it becomes so easy to use there's really no reason to ever go back.
Damn you Dan. I see fiddling in my future!
Do you guys love working in Markdown, or is it just a stopgap measure so you can have a scriptwriting workflow with all your screens?
Would it be a better solution if Final Draft had an app for iPhone, iPad, iMac and Web? Have you asked FD to do this? What about asking Celtx?
What would be the perfect solution for this problem?
Ha. Sorry. I'm only trying to help, I swear.
And I love writing in markdown. The only reason I would want FD installed on my system is to convert the file to a FD document to send to someone else with FD. There are tools to create PDFs directly from MultiMarkdown, so there's no reason to use FD or Celtx for that.
There's just no reason we should suffer the loss of auto-completion while writing in text files. I even have that snippet set to enable caps lock and disable at the end so I don't have to think about it.
I have mostly finished my fiddling with regards to markdown and writing since I had to translate Merlin's tips into PC compatible tools. Hopefully sharing will help you find your own quick and easy workflow.
cct - CUT TO:
ffi - FADE IN
ffo - FADE OUT
iint - INT. (cursor) - (cursor)
I'm sure there are more that might be useful, but those have worked for me so far.
Sometimes I'll even create a snippet that will create a full caps version of the character's name if i'm writing something long-ish with a lot of dialog, but that's more of a per-project thing.
Stu, I completely understand your frustration with Final Draft. I've never warmed up to it myself. The plain text method you describe is quite useful, but I kind of like the WYSIWYG way of working. Typing screenplays for me involves sitting down with a quality keyboard made for typing like a model M or DAS keyboard or something similar. All other options be they software keyboards, onscreen ones or laptop ones are all hindering my typing speed. They're useful but not for getting work done.
On the other hand - and I know it will sound like cursing to most people here - what's wrong with Word? I've been working in Word for years with a template set to industry standards and it's been perfect.
Similar to Dan I like to use Word's autocorrect function to get rid of tedious typing of worrysome words. So if I were to write a Sesame Street screenplay involving Snuffy the snuffleupagus, I'd add a 'sss' entry to my autocorrect thesaurus and use that everytime sss appeared on screen.
So why FD? Is it for the interoperability with planning software or is there another reason?
I've been working on a piece of software that lets you write a screenplay in plain text format and then formats it. It's called Screenplain. You just write your script in your favourite text editor, then Screenplain takes that file as input and creates a good looking PDF.
Thanks to your post here, I got around to publishing it, even though it is far from finished. To be honest, it's even a few hours of work away from even being useful. The PDF output looks awful, and there are no options to control the output. With a few hours more work, it will be usable. Have a look at the README to see how it works. (Feedback appreciated!)
I was writing this as you updated the post, but I'll post it anyway. We're basically saying the same thing. We/someone should do this, as it seems like it would really be useful for a lot of people and not a huge undertaking...
Things like Scrippets and Screenplain are cool, however what would be great is to start with that plain text formatting (which appears to be what Final Draft works with as well) as a base, and then define markup for more detailed control. Markup to delineate the difference between a scene description and a shot description for example. It would also be good to define markup for those things that are already understood so, for example, you don't HAVE to capitalize scene headers. There's only so much formatting in a screenplay, so it would be dramatically easier to do this than it would be for HTML or something else more complex.
Anyway, once you have your markup set, then you ideally want apps to support it. However you could get by with a simple app/script to convert back and forth between the plain text and FDX. Then you wouldn't be limited to how you can work with and share files.
If I understand your recent update correctly, what you want is a format that is editable using a plain text editor, but you're not ready to sacrifice WYSIWYG completely, so for your main work you'd want to use a WYSIWYG tool instead. That's a good idea. I'd like all software to work with file formats that are easily editable with a text editor. For screenplays it's feasible.
Lacking such software, using a text editor with a very simple markup is a good solution. Since screenplays in plain text already contain much semantic information, there is not much need for explicit markup. For example, you can tell a scene heading from a shot heading because it has two blank lines before it, etc. But for special cases, you'd need explicit markup. We just need to identify those special cases. Bold and underline are given, but there may be others.
Yep Martin, you nailed it. Great idea about denoting a Scene Heading with 2 leading carriage returns — you should make screenplain work that way, because sometimes I'll yell out a single line in all caps and I still want it to be an action element, e.g:
He runs for all he's worth and then...KABOOM!
The force of the blast knocks him flat.
Anyway, I'm going to poke around and see if there's any interest in this from some screenwriting software developers I know.
By the way, the first Magic Bullet Suite looks files were human-readable text.
I use Celtex and Final Draft 7 and I don't write unless I'm at my desktop mac. So I guess I'm just waiting for Final Draft for iPad.
A good idea. Right now I'm using limited HTML markup, which is awkward on a mobile keyboard. How should bold-italics be represented? Or a literal * or _?
Screenwriting is all about STORY STRUCTURE, STORY STRUCTURE, STORY STRUCTURE - go see Kal's excellent work at http://www.clickok.co.uk/index4.html ; no matter what software you use.
I've been thinking along the same lines. For me, a huge benefit of plain text is the ability to check my screenplay into Github.
Just a quick note to make sure folks reading this comment thread notice the Update above with, gasp, a link to a Screenplay Markdown sytnax proposal here, along with sample files.
Hi Stu, have you tried Adobe Story? They also offer an iPhone app, but I have not tested it yet.
Adobe Story is great! The iPhone app doesn't allow editing though — just reading and comments.
Fun thought exercise -- and a pretty simple implementation for a pretty cool idea. i especially like it because for whatever reason (an early Kubrick film being found) the concept of recoverable archiving has been on my mind a lot lately.
Anyhow -- what about using .syntax for the scene sluglines? The double-space seems like an odd syntax, and feels unintuitively special-case to me. Not a fan of white-space dependency either. Although EXT and INT etc are standards, a .syntax feels logical, though that may be the terminal user in me talking.
eg:
.EXT. AWESOMETOWN, USA
.SNIPER POV
Many screenplays actually have 2 blank lines before a slugline. It's often the only thing that distinguishes sluglines that don't start with INT or EXT. If you sat 100 screenwriters down in TextEdit and told them to write a screenplay, I bet about half of them would double-space before their sluglines.
I considered some kind of textual prefix for sluglines but if I can find a solution that works for writers and doesn't require one, that's what I'd prefer.
Re: the video,
Are you actually envisioning an app that auto formats the text as you type rather than the post processing like standard markdown? Or is that just a demonstration of the before and after states?
As a cross platform tool, I would imagine the majority of the writing would be done in the markdown syntax and later converted to pdf and fdx.
And personally, as a text editor nerd, I prefer leaving everything in the markdown syntax and using an application that supports syntax hi-lighting to let me know i've written my syntax correctly. (Also it's fun to write in pretty colors).
example: http://www.kungfugrippe.com/post/5843015394/way-to-far-from-the-metal
Hi Dan,
I’ve made some updates to the spec doc, including a section about the types of app support that I’d like to see. Here’s a bit:
What I mocked up is the second bullet — an app that is showing you a bit of a preview of what your formatting will look like as you edit the markup version. No actual formatting is taking place. The app is just lightly superimposing a preview of the end result.
This is how Byword works, and even our friend Merlin is a fan. This screenshot shows it well. Notice how the bolded text is previewed as bold, and the asterisks, as well as the brackets forming the link syntax, are dimmed. I love this hybrid approach.
But, the fourth bullet on my list is this one:
You might prefer bullet 1. I might prefer bullet 2. And many writers might not even consider SPMD until bullet 3 was available.
Does that make sense? What do you think?
That absolutely makes sense. Sorry, I missed the update to the proposal doc before sending that last comment.
The reason I'm likely hung up on bullet 1 (though I'd probably learn to love bullet 2) is that I spend a lot of time on a windows machine without access to many of the lovely writing apps we have on OSX.
It's great that you've laid out not only the SPMD format, but also implementations for software apps at various levels of sophistication (btw should we just go ahead and start using filename.spmd?).
I definitely spend more time thinking more about the plain syntax than the implementation since that's really the launching point for this idea, and likely my personal use case.
Basically I agree with everything you have proposed in the SPMD doc so far. I was considering suggesting adding a 'tab' before the Character and Dialog to make it a bit more distinct (and hopefully easier to read) in it's native format, but upon further thought, it's probably not necessary (especially if the app supports hi-lighting).
I'm trying to think of any other information that would be pertinent to the initial scope of this project, but I think you've covered it all in your proposal. Unless I'm missing something it seems all that's left is to create some conversion tools, start using them, and spreading the idea.
Great work as always.
Sorry, that should have said 'optional tab' so things are easy on iOS as well (even with the lovely tab support in Nebulous Notes).
Hey Dan, I think some users will want to use tabs to make a slightly more screenplay-looking raw file, I've written a bit about optional indenting.
Once again you're way ahead of me.
I think you've got this thing just about wrapped up. Now all that's left is a little bit of code and a lot of people joining the party.
Cool, glad you like where it's gotten to!
BTW, I like the idea of using the .spmd extension, as long as it doesn't limit compatibility with text apps expecting known file types.
I have at least one iOS text app that allows you to manually add file extensions to a list of supported file types though.
Agreed. I think most text editors (especially the ones that support markdown) will try to open a file regardless of extension, but *.spmd can be an option used in conjunction with *.txt
The main desktop editor I use (Sublime Text 2) lists *.mdown, *.markdown, *.markdn, and *.md all as markdown file formats. Despite that I still save my files as *.txt and just set the default syntax of *.txt files to markdown.
I might be inclined to start saving my markdown files as *.md and screenplays as *.spmd now that I have a use for them both. But, as you mentioned, only as long as that doesn't limit compatibility. I guess that's what testing is for.
Actually, here's what I'll do. I'll start saving my markdown documents as *.spmd right now to see which tools will and won't open them. I'll make a list of everything I use (or can find to try) and report back in this thread. Sound like a good idea?
I made a few notes about SPMD here.
This is only representative of the devices and apps I have available at the moment, but I'd say it's pretty encouraging as a start.
I'll update the list as I test other apps.
Thanks for looking into it Dan. On my phone, Droptext is the one that allows me to add .spmd as an editable file type. PlainText doesn't show the .spmd file. WriteUp shows it but won't let me edit it.
By the way, be sure to read Kent's blog post linked just above!
I tossed your apps on the list but I think the key is going to be in making the extension interchangeable with .txt like markdown. It offers flexibility and a sort of workaround for people want to try and work outside the limitations of their personally beloved text editors.
There are some very interesting things in Kent's blog worth discussing. First of which is probably the / being used for italics. I would hazard a guess that if we asked Gruber why he picked double and single asterisks and underscores for markdown he would say it had to do with their infrequent use in most writing. The / on the other hand seems like it gets a lot more actual use and might be more of a hassle than it's worth for syntax.
I personally wouldn't be upset if SPMD used something like **bold**, *italics*, and _underline_. Obviously the / is much more illustrative of the final format of the text, but I don't think it'd create a terrible amount of heartburn to require the writer to know the difference between single and dual asterisks.
Regardless of which way SPMD goes, I think the point about escaping syntax for practical use of the symbols being intrusive to the writer is essentially a non-issue for 2 reasons.
First, after writing for a while, hitting \ becomes just as much of a reflex as any keyboard shortcut. Sure you have to pay attention and understand the rules, but that's the point of syntax. And the best part about Markdown and SPMD is that the list of rules is very short.
The second reason I think it's a non-issue is the multiple use cases for SPMD Stu outlined when describing the application's implementation of the format. For the most part, any program like Final Draft could replace their proprietary file format with SPMD completely transparent to the user, who could go about their business using the WYSIWYG tools available in the app. And in time there will likely be WYSIWYG editors on the mobile platforms as well. But the idea remains that you don't HAVE to use them.
I don't think anyone is crazy enough to do it, but you can write Final Draft documents in a text editor. Believe it or not .FDX files parse into plain text. It's ugly as all hell, but it can be done. For example, a snippet of Stu's .FDX file looks like this in plain text:
We're really just talking about cleaning up the behind the scenes formatting so if one were so inclined, they could modify the file in plain text. What's more, since FDX files are built out of what essentially looks like HTML, I'm sure there's probably a way to do things like Notes and Scene Synopsis in plain text as well. You can bet it's going to be hideous to look at or write, but that's were we have a chance to make improvements.
I love Kent's suggestion of using various double brackets to denote things like notes. But if we were worried about using up all of our keyboard symbols we could use something as simple as starting a line with mNote: to denote a metadata note that would later be converted by the WYSIWYG, yet still remain readable in the plain text. MutliMarkdown actually has a predetermined set of metadata terms like this for header information of the final HTML file.
But frankly I think we're getting ahead of ourselves. Things like revisions and notes should likely be a second phase to this idea. Something left to the more sophisticated implementations of writing applications.
Like Markdown, SPMD in it's simplest form will allow others to build upon it (read: MultiMarkdown). We should expect and encourage people to customize and add things to their specific implementations of SPMD, so long as the underlying principal of easy to read, easy to convert plain text still held up.
I'm excited to see where this goes.
That was my original thought as well. Would ***this*** be bold-italics then?
And *this would be a **bold** word in a mostly italicized sentence?*
I'm torn between the intuitiveness of forward-slashes for italics and the possible conflicts that could arise from their slightly more common use in prose.
It does make the whole thing a little less intuitive, but I don't know if it would be a deal breaker. That's probably another reason Gruber made asterisks and underscores interchangeable, so we could make things _**bold-italic**_.
We could look for another symbol to use for italics that is easily accessible on standard and mobile keyboards, while being uncommon in typical writing, but it may be easier to just stick with the single and double asterisks.
It makes some sense of the face of it. At least in my mind the priority of emphasis would be italics, bold, bold-italics, in which case one, two, and three asterisks would be logical, but it may still be difficult to use from the writer's perspective.
One way it could become a little easier for the user is the addition of autocompletion in the application. In many text editors when you type ( it will automatically place the closing ) after your cursor and let you continue to type without worry of having to close the parenthetical. You simply hit the tab or arrow when you're done and keep typing the rest of the non-emphasized sentence. If the SPMD application auto added the second asterisk every time you added one, it would save the user from needing to remember how many leading asterisks they have to close to avoid a formatting error.
Obviously this then creates and issue if you intended to type a single asterisk, and based on it's use for unordered lists in markdown, you can see why they don't do this already. But if we're not using asterisks for lists in SPMD, there's no reason we couldn't implement the autocomplete with a simple backspace eliminating the second asterisk if your intent was to only type a single.
The problem with this is the additionally usability is added at the level of the application implementation rather than the syntax itself, but it may well be 6 of one, half dozen of another. If someone wants to write in an application that is so barebones it doesn't support any sort of understanding of the language, and in turn autocompletion of designated characters, the user of such an application would likely be the level of nerd that would remember when and where they need to close their asterisk syntax.
Me personally, I could live with *italics*, **bold**, and ***bold-italics***. But if you think that would be too difficult for the everyday user, I'd say look for another special character that is used infrequently in writing, but easy to access on most devices. An equals sign is easy to access, but would definitely look odd and be less than intuitive for something like bold or italics. Maybe a ^? But more or less the same issue.
I trust your judgment and intuition on this one.
Hey Dan,
I think I'm liking ***bold italic*** — and I've updated the doc to reflect this.
I've also changed the syntax for dual dialog. And I added a section on line breaks that I could really use a sanity check on if you have a moment.
This is a tough one. I'll try to be as succinct as possible, but this is one that really needs some discussion. You're trying to do essentially 2 different things with the same syntax (obviously for simplicity sake) but it may cause some issues.
In the first example...
...you're essentially using the {two spaces} to escape the assumed syntax of the line. This could be a great feature that could cover any number of odd, unforeseeable formatting challenges...but only if by escaping the line's assumed syntax, it always defaults to the same level. Action would seem to be the logical default since it's the more or less the highest level element of the script.
Since we already have the \ to escape syntax on the emphasized elements, it would seem that it may also be of use in this situation to maintain continuity. So you're correctly formatted line would look like:
Or, we could use double \\ as a method for escaping an entire line's assumed syntax, and leave the single \ for escaping at the character level, like so...
In the second example...
...you're using the same syntax used to escape the assumed syntax of a single line, to bridge 2 lines; or essentially remove both the line's assumed syntax, as well as it's impact on the lines that follow. This is the one that will probably cause some confusion for a couple reasons.
First, it's the opposite of how Markdown would solve this problem. Adding the 2 spaces to the empty line wouldn't do anything. Adding any single character to the blank line except a space would bridge all of the lines.
Second, if we're trying to be consistent with the first example, we're telling the system to escape the implied syntax of the blank line. Since the blank line is already assumed as breaking the dialog and returning to Action (the default state), it wouldn't make sense that the 2 spaces on the blank line would do anything.
This could easily be an SPMD specific special use case, but what happens when someone writes:
Does that mean that "Dealer gets a seven" becomes an action line? If yes, that would also make "Hit or stand sir?" an action line as well.
The problem is a question of order of operations. Which syntax has the ability to overrule what? Do the {two spaces} (or whatever escape symbol is used) override all the assumed syntax and revert to a default state (action)? Or would the escape in the middle of the dialog do nothing, since after escaping the syntax of the dialog, there is no preceding empty line to suggest action therefore causing the line to remain as dialog?
Getting around to the point...
I think you need one method for escaping the assumed syntax and reverting to a default (I suggest action). And you need another method for bridging lines.
Since you've changed dual dialog to be two vertical lines (bridging the dialog and telling the system to ignore the implied syntax), the logical character to use for bridging dialog for a single character would seem to be a single vertical line. Causing the user to do this:
I think that would solve the issue in a consistent manner...as long as the writer isn't using a sans-serif font.
To sum up, I think you need 2 things:
* a universal syntax escape that works at the line level (rather than just the character level)
* a consistent method for bridging lines, or forcing the system to ignore both the line's syntax and it's impact on subsequent lines.
Recommendations:
Universal escape:
Single \ to escape character syntax for emphasis
Dual \\ (placed at beginning or end of the line) to escape the entire line's assumed syntax.
Line bridging:
Single | for removing a line from the syntax calculation within a single character's dialog.
Dual || for removing the line and bridging characters for dual dialog.
One thing to note about this idea. It would seem like there is an inconsistency between how the single | and double || are working in that this...
...is equal to this...
...but this....
...is not necessarily equal to this...
...unless you want it to be.
Sorry this was so long. These two things are tricky since their basic functionality seems to be at odds with what's actually happening. Hope it all makes sense (and helps). If not, I'm happy to clarify.
Dan, thanks so much for all the thought and consideration you're putting into this, I really appreciate it.
I'm trying desperately not to clutter the visual appearance of the raw .spmd file. I'm pretty sure I understand everything you wrote above, but what I don't understand is, are you suggesting a change from what's in the spec doc now because you don't think what I proposed will work? Or because it isn't as generalized as it could be?
In Markdown, two trailing spaces forces a line break. I'm borrowing this convention where necessary and not requiring it where it's not. That's about as simply as I can state the idea behind what I proposed.
I don't look at the two spaces after "SCANNING THE AISLES..." as escaping the line back to Action, I look at it as "connecting" the line to the following line. This may be a purely semantic distinction though.
Using a line containing only two spaces to connect the above and below lines semantically is my own invention, and is most certainly up for review. But it strikes me as the most intuitive way to accomplish something that is quite unusual in practice, which is to insert blank lines in a dialog element.
My proposal seems to provide the necessary functionality, seems to scale the "degree of difficulty" apace with the unlikeliness of necessity, and achieves the goal of keeping things clean and looking as much like the resultant screenplay as possible.
So am I missing something?
BTW, I'm pretty sure that in this case:
...the rules assume that everything after "BRICK" is Brick's dialog. Which is good, because you might want to do this:
Regarding line breaks, I think the spec is inconsistent in a way that I see no reason for.
In Action: "We borrow the Markdown convention of two trailing spaces to force manual line breaks". Reading between the lines (no pun intended) I understand this means that line breaks in the text are ignored and the lines are joined just like in Markdown.
In Dialog: "Manual line breaks are allowed in dialog", i.e. line breaks are significant when within a dialog. The lines are not joined automatically.
I'm fine with both ways (though I'd prefer the Markdown way), but it should be consistent to avoid confusing writers (and implementers).
Martin, there's no need to read between the lines, because I explicitly stated this:
For the most part this will work fine. We only need the two-trailing-spaces trick to force an Action element when one of those lines looks like something else.
I can see how this was unclear and inconsistent in the spec though, so I've updated that section, as well as the Action and Dialog sections, to try to better show the desired behavior. Thanks for pointing that out!
I'd rather not see \ at the end of a line used for that purpose. The screenwriter/programmer overlap may be small, but to them ending a line with \ means to concatenate the next line to this one. I could get behind \ at the _start_ of a line to indicate that any next-element processing rules should be ignored and the type of the previous element be applied to this one.
Although I guess I'm the only who thinks forced linebreaks like that in the middle of dialogue are the devil's work.
So it's going to be *, **, and _? I'll use that for now in implementation. Those of us who leave *** breadcrumbs to search back for will have to evolve or perish.
As for readability and editability comparisons with Final Draft, Final Draft 8 uses XML for the .fdx format. Because XML is (sort of) human-readable, it's sometimes mistakenly thought of as human-editable. That's rarely true except in the simplest of cases. For one thing, most XML parsers are exceptionally strict and will fail on malformed XML. There's no tolerance for mismatched or dangling tags the way there is in browsers' handling of hand-rolled HTML. The other thing is that any reasonably complex format is probably going to contain a sizable amount of human-unfriendly interdependent data — a professional-grade screenplay format is going to have to handle page/scene locking and revisions and other indispensable functionality — and won't stand up to arbitrary manual manipulation. (This is, in a nutshell, why I have questions about SPMD being able to eventually fill the role of a final format for screenwriting instead of an interim/working format.)
(And Martin, I think the idea is that SPMD always respects explicitly typed linebreaks.)
Thanks for your comments Kent. I should mention that I completely agree that SPMD will probably only ever be an interim format. The way I like to look at it is that SPMD has everything you need for the creative, pre-production writing phase. When you move into production, you'll want to move to another app.
It's an odd consequence of undertaking something like this spec that you spend more time talking about the edge cases than the norms. I almost never see this, but I do occasionally, and I want to support it.
The passage in the spec that I think is confusing is this one with the following example:
And then there's a long beat.{two spaces}
Longer than is funny.{two spaces}
Long enough to be depressing.
In this case the two spaces would not be needed!
Yep, you are correct, and thanks to you pointing that out, I changed that part of the doc. You probably need to force a reload to see the change. Thanks again for noticing the inconsistency!
Hey Stu,
Re:
I think you're proposal is perfect in this regard. That last post was me attempting to break down the logic behind the use of the {two spaces} in all instances.
I definitely think the way you have proposed it will work, and work well. If you tell people 'this is how SPMD does this', I think people will have all the information they need to work in a clean and functional manner.
The problem that exists in my mind is around defining the tool and its logical usage. If someone asks you outright, "What does the {two spaces} command do?", in the current implementation, the answer is "It depends".
It depends on whether or not it's used at the end of a sentence or in a blank line. And when it's used at the end of a sentence, how does one describe that functionality? I attempted to define it as 'escaping the assumed syntax'. You described it above as 'connecting it to the line below'. I don't think it really matters which way you describe it, but that description needs to be clear and consistent.
And the same goes for the {two spaces} on the blank line. How does one define that functionality? If the answer is again '{two spaces} connects the current line to the line below', I'm a little less clear on what that means for the final product. I'm connecting a line of dialog to a blank line? My brain doesn't know what to make of that thought, so I suggested something that did make sense (to me).
Like I said above, I think the method you've outlined for using {two spaces}, both at the end of a senetence sentence and on a blank line will work well and keep the document clean. But from a logic standpoint, looking at the SPMD syntax as if it was a programming language (which is more or less what we're talking about), the {two spaces} function seems to have an inconsistency.
The reason I attempted to solve that problem, is so, as a user, I could at any time while writing a script ask myself "What happens if I put {two spaces} here?" ('here' being any random place) and be able to answer my own question without looking at the syntax guide.
As it stands right now, I know how to use {two spaces} to solve the 2 problems outlined in the proposal document, but I don't know how that function would act in any other instance. I was seeking to define the function at a more global level. That may or may not be needed. Perhaps the use of {two spaces} doesn't do anything unless it's used in one of the 2 examples you've outlined. But if someone were to find another place where the {two spaces} command would be helpful (that we haven't expressly defined in the proposal) and trying to use it in what they considered a consistent manner resulted in no functionality, then there would be some confusion.
Like I said at the top of the previous post, this one is tricky and could really use a good bit of discussion. Almost every function in the proposal can be defined with a simple, clear answer to the question "What does X function do?". It seems (to me) that the {two spaces} function has been defined in 2 use cases, and not with an overall definition of its function.
For most users, this will not be an issue and should not create any real issues technically. But if the higher level goal is to create a language for writing scripts that can be used by a writer to infer the correct use of each function in their own fringe use cases, I think the {two spaces} function presents an issue.
And just to circle back to my suggestions in the previous post, I think using the {two spaces} at the end of the line to avoid an assumed Character name is just as good or better than the odd \\ I proposed. And while I may not 'get' the reason for using it in the blank line, I can adapt to use it, and understand its use, in that instance.
I feel like I'm starting to turn into Siracusa. Hope this discussion helps rather than hinders. Sometimes discussing these sorts of details via the internet is not the terribly effective.
Oh, you're definitely right, Stu. I'd go so far as to say that pretty much everything that can be typed in a screenwriting application (like Fade In, or that other one) can and should be representable in SPMD.
That can so easily be true, if people aren't willing to put the effort in to be clear and collaborative — but you have done a great job of that. I'm grateful for your feedback.
When I first learned that Markdown used invisible double spaces to accomplish formatting, I thought it was odd. Then I got used to it. This was pretty easy, because it's consistent. So I take seriously your concern that we're using the spaces in two different ways.
I think you're right that basically what the trailing spaces are doing in the dialog example are invisibly indicating that the line that looks like a Character name is actually action. I'm cool with this. Seems like a handy thing to be able to do.
Blank lines in dialog are so rare that I'm not sure it's a huge problem to borrow the two-spaces for that use, but I am taking seriously your suggestion of bridging the gap with a single bar.
So, to be clear, I'm trying to decide between this:
And this:
Either way, if you screw up and forget, "Hit or stand sir?" just becomes an Action element, which is easy to see and correct in a WYSIWYG app.
All of this for the very rare and possibly satanic practice of putting white space in dialog for effect.
I'm glad to be able to help. I worry about over analyzing and halting progress, so feel free to make an executive decisions and stop us (or just me) when necessary. As with all v1.0 products, getting it out into the world will help us determine if the decisions made were the correct ones.
I just had one more thought. If you decide to use the vertical line rather than the spaces, and since the single vertical line has already tarnished the cleanliness of the formatting, rather than adding another tool to the SPMD syntax, would it be a good idea to use a backslash in the blank line?
i.e. this:
We've already established the backslash as a way to skip syntax, and it's not much uglier than placing a vertical line in the empty space. It's also probably a good idea to keep the number of new operators (that don't exist in markdown) to a minimum.