Nellie converts a plain text document marked-up as a screenplay into a formatted screenplay in Portable Document Format or in ePub ebook format.
An example source document lies at the end of this page.
If you want to support the maintenance of Nellie, buy me a tea or PayPal me.
When you use Nellie, you offload as much work as possible onto the software. You write the content of your documents, and in most cases, Nellie infers the types of your document’s paragraphs and formats them appropriately.
When you keep your documents in plain text format, they are future-proof. UTF-8 is a non-proprietary, universal standard for representing text. People will be able to read your documents a hundred years from now.
Source documents must be encoded as UTF-8. Documents must have the .txt filename suffix. Any line terminator sequence is acceptable. Paragraphs with single terminators and paragraphs with individually-terminated lines are both acceptable.
Nellie uses an Open Source Courier-style font for PDFs. As a consequence, the formatter supports the character ranges that the fonts support. These ranges support European languages that use alphabets derived from the Latin alphabet.
On Windows, Notepad edits plain text. Select the magnifying glass and search for notepad.
On MacOS, TextEdit edits plain text. Select the magnifying glass and search for textedit. When you create a new document in TextEdit, it will make the document a Rich Text Format document by default. To convert the document to plain text, select the Format menu and then select Make Plain Text.
On Unix variants Vi edits plain text.
In the bodies of screenplays, Nellie recognizes 8 types of paragraphs. Separate paragraphs from each other with blank lines.
To force a line break, insert a bar | character where you want the break to occur.
To indicate an elision at the front of a word, use a backtick ` instead of an apostrophe.
Users with English keyboards can insert UTF-8 sequences for accented characters with the following escape sequences:
\' (apostrophe) followed by a vowel inserts the vowel with an acute accent.
\` (backtick) followed by a vowel inserts the vowel with a grave accent.
\^ followed by a vowel inserts the vowel with a circumflex.
\, followed by an uppercase C or a lowercase c inserts the character with a cedilla.
\~ followed by an uppercase N or a lowercase n inserts the character with a tilde.
\: followed by a vowel or an uppercase Y or a lowercase y inserts the character with a dieresis.
\u followed by a decimal number inserts the Unicode character with the specified code point. If the code point is followed by digits that are part of the document text, those digits must be repesented by their own \u code points, or the digits will be interpreted as part of the code point.
To create a scene heading, start the heading with a dot.
.INT. DINER - MIDDLE OF THE NIGHT.
The leading dot of scene headings is not always necessary. The formatter recognizes paragraphs that start with INT or EXT as Scene Headings regardless of capitalization.
Nellie converts scene headings to upper case.
Nellie numbers scenes when the Scene Numbers option is enabled.
Shot headings are introduced with a colon.
:CLOSE UP - MACINTOSH'S FACE.
Shot headings are formatted similarly to scene headings, but shots are considered to be part of the current scene.
Nellie numbers and letters shots when the Scene Numbers option is enabled (eg. 2A for shot A of scene 2). You can have up to 52 shot headings in a scene before shot letters repeat. The first 26 shots are lettered in uppercase. The succeeding 26 are lettered in lowercase. If you have more than 52 shots, the lettering restarts with uppercase letters.
Action paragraphs are the default paragraph type.
Action paragraphs do not require explicit markup unless they are mistaken for other paragraph types. In those cases, add a ! to the start of the action paragraphs.
To start a dialogue block, place a character cue on a line by itself. If the character cue contains characters other than uppercase letters, digits, and spaces, the cue must start with @ to force its recognition. All characters after the initial @ (including other @s) appear literally in the cue.
@JOHN
(parenthetical)
Some dialogue. Some more.
Yet more.
A dialogue block ends at the next blank line.
If two or more dialogue blocks with the same cue are separated by action paragraphs, the formatter can add (CONT'D) to the cues subsequent to the first. This behavior is enabled with the Non-Pagebreak Dialogue CONT'D setting.
To create a parenthetical instruction, start a new line with an open parenthesis character. Terminate the parenthetical with a close parenthesis character and a hard return.
Unindented dialogue paragraphs do not require explicit markup unless they are mistaken for other paragraph types. In those cases, add a space to the start of the paragraphs.
To start a new indented paragraph, start a new line with &. Any amount of whitespace may follow the &. The whitespace is removed by the formatter.
To insert a blank line, start a new line with &, and place no other text on the line.To start an unindented paragraph after a blank line, start a new line with $.
JOHN
This is the first unindented paragraph.
& This is the second indented paragraph followed by a blank line.
&
$ This is the third unindented paragraph after the blank line. If the $
were missing from the start of this paragraph, it would be merged with the
line preceding it to create an indented paragraph.
To insert an italicized lyric line, start a new line with ~. Any amount of whitespace may follow the ~. The whitespace is removed by the formatter.
JOHN
Now I shall sing.
&
~ This is a lyric line.
~ This is another.
~ I am feeling fine.
~ Can you dig it brother?
&
$ Thank you for listening.
A character cue that starts with a - introduces a left-aligned block. A character cue that starts with a + introduces a right-aligned block. These blocks can be used to represent split-screen dialogue.
-LEFT CUE
(parenthetical)
This is a left-aligned dialogue block intended for use in split-screen
dialogue.
+RIGHT CUE
(parenthetical)
This is a right-aligned dialogue block intended for use in split-screen
dialogue.
Nellie does not support dual side-by-side dialogue blocks. To indicate that characters’ speech overlaps, use a slash to separate speakers and their speech. Compound cues must preceded by a @ to be recognized.
In the following example, John and Susie utter identical speech simultaneously:
@JOHN / SUSIE
(in unison)
You are impossible.
In the following example, John, James, and Susie's speech overlaps:
@JOHN / JAMES / SUSIE
(overlapping)
I regret ever knowing you.
You have diminished my quality
of life. / |
You’re both crazy. / |
You are a selfish bastard
with no concern for anyone but
yourself.
To create a scene transition, start the transition with >.
>FADE IN:
>CUT TO:
>DISSOLVE TO:
The initial > is not always necessary. If transitions contain characters other than uppercase letters, digits, spaces, and colons, or if the transitions do not end with TO:, the transitions must begin with > to force their recognition.
Nellie right justifies transitions.
Note paragraphs contain editorial content that is removed by the formatter. To be recognized, note paragraphs must begin with [[ and end with ]]. A note “paragraph” can contain multiple paragraphs of text.
[[This is a note paragraph.]]
[[This note contains more than one paragraph of text, but it is considered to be a single entity by the formatter.
This is the second internal paragraph of the note.]]
To insert editorial content that is not removed by the formatter, insert the content inside single bracket pairs: [Note].
To create the title of an act, insert the title between > and <.
>ACT 1<
Do not create a title longer than 60 characters. Characters in excess of this limit are not included in the PDF.
The standard screenplay format does not indicate the total number of pages in a screenplay. It is useful to explictly indicate the end of a screenplay so that readers know that no pages are missing.
To indicate the end of a screenplay, insert the end message between > and <.
>END<
Do not create an end heading longer than 60 characters. Characters in excess of this limit are not included in the PDF.
To be recognized, an end heading's content must begin with END. If the content does not begin with END, the message is interpreted as an act heading. The difference is that act headings are pushed to new pages during formatting.
Nellie provides no means for you to directly change the font. Boldface is too obstrusive outside of headings, and courier oblique is not oblique enough because it is a fixed-pitch font with little room for leaning. As a consequence, it is easy to fail to recognize oblique words embedded in a roman sentence. I have made the executive decision that all emphasis is accomplished with underlining.
Nellie underlines words that are bookended with underscores. Each word must be underlined separately.
_This_ _is_ _underlined_ _text._ _Underline_-_each_-_word_-_in_-_a_-hyphenate._
You may get away with underlining _a single-line passage of text_, but if your underlined passage is subsequently split across lines by the formatter, the underlining will be removed.
A title page with placeholder information is automatically added to your screenplays. Nellie does not format title pages by themselves. You must have at least one paragraph of screenplay for Nellie to produce PDF output.
To replace title page placeholder text, add the following lines to the beginning of your screenplays. Replace the values after the colons with your information.
Title: THE SILVER SALT CELLAR
Author: Carnaby Fimblethicke
Draft Date: February 2018
Contact: fimblethwicke@nowhere.net
To create multiline values, break the keyword line after the colon. Place the lines of your multiline value after the keyword line.
Each line of a multiline value must begin with a space. To indicate a blank line, insert a line containing only a space character.
Author:
By
Carnaby Fimblethwicke
and
His dog, Horatio
To make today's date the Draft Date, make its value $D.
Draft Date: $D
To insert the manuscript word count, use $W.
Draft Date: $W
To insert the page count, use $P.
Draft Date: $P
You can place anything you like in the value of Draft Date. If you use $D, it must appear by itself on a line.
If you use $W, it must appear at the start of a line. If $W appears on the line by itself, the formatter will follow the word count with WORDS. If you want different text, follow $W with the text that you want.
If you use $P, it must appear at the start of a line. If $P appears on the line by itself, the formatter will follow the word count with PAGES. If you want different text, follow $P with the text that you want.
Draft Date:
Revision 1.0
$W
$P
$D
Nellie support 3 optional title page block elements: Watermark, Copyright, and Language.
Copyright: 2018, Carnaby Fimblethwicke.
Language: en
Watermark:
COPYRIGHT (c) 2018,
Carnaby Fimblethwicke.
The 3 characters (C) occurring anywhere inside the Contact or Watermark information are replaced with the copyright symbol by the formatter.
If you specify watermark lines, they are added centered, rotated left to the background of every page. Watermarks are set in boldface at 90% transparency at 60 points.
Nellie's watermarks cannot be removed or edited by tools that modify PDF annotations.
Nellie’s ebooks do not contain cover images, which means that they cannot be uploaded to ebook retailers such as Apple Books.
The Copyright and Language title block data are only used when Nellie generates ebooks.
If you generate ePubs, add a Copyright line to your title page block. The value should be the year, a comma, and the name of the copyright owner. Nellie precedes your copyright data with the text Copyright and the c-in-circle copyright symbol.
Copyright: 2018, Carnaby Fimblethwicke.
If you generate ebooks and your screenplays are not written in English, you should add a Language line to your title page blocks. The value of the line must be a BCP 47 language tag. For example: en for English, fr for French, de for German, es for Spanish, it for Italian, or is for Icelandic. If your screenplay does not have a Language line, Fimblethwicke uses en by default.
Language: fr
An example screenplay fragment follows. A plain text version that you can save, modify, and upload to the formatter is here.
Title: THE SILVER SALT CELLAR
Draft Date:
$D
$W
Author:
By
[Replace this line with a single space character to insert a blank line.]
Carnaby Fimblethwicke
Contact:
Copyright (C) 2019,
The Imaginary Production Company.
fimblethwicke@nowhere.net
Watermark:
COPYRIGHT
(C) 2019,
THE IMAGINARY
PRODUCTION
COMPANY.
>ACT 1<
INT. DINER.
:MEDIUM SHOT.
Our HERO sits in a red booth and eats a cheeseburger.
CUT TO:
:CLOSE UP - HERO'S HEAD AND SHOULDERS.
He picks up a salt cellar and talks to it.
HERO
(affectionately)
You make lunch worth eating. Where can I find such magnificent food
enhancing magic as you?
(angrily)
I shall _steal_ you.
CUT TO:
:CLOSE UP - HERO'S JACKET.
Our HERO inserts the salt celler into his jacket pocket.
CUT TO:
EXT. DINER - DAY.
A man walks down the sidewalk, passing the diner's windows. We see our HERO inside talking to the salt cellar. The man observes our HERO pocket the salt cellar.
CUT TO:
INT. THIS IS A LONG SCENE HEADING THAT WRAPS ONTO MORE THAN ONE LINE.
_Lorem_ _ipsum_ _dolor_ _sit_ _amet_, consectetur adipiscing elit. Quis est enim, in quo sit cupiditas, quin recte cupidus dici possit? Estne, quaeso, inquam, sitienti in bibendo voluptas? Quasi ego id curem, quid ille aiat aut neget. Illi enim inter se dissentiunt. Ne amores quidem sanctos a sapiente alienos esse arbitrantur. Duo Reges: constructio interrete.
NEMO
Sed quid ages tandem, si utilitas ab amicitia, ut fit saepe, defecerit?
& Beatus sibi videtur esse moriens. Quid enim tanto opus est instrumento in
optimis artibus comparandis? Expressa vero in iis aetatibus, quae iam
confirmatae sunt.
& Ergo illi intellegunt quid Epicurus dicat, ego non intellego? De
hominibus dici non necesse est. Quae _si_ _potest_ _singula_ consolando
levare, universa quo modo sustinebit?
&
$ Parvi enim primo ortu sic iacent, tamquam omnino sine animo sint. Sit hoc
ultimum bonorum, quod nunc a me defenditur; Nec vero alia sunt quaerenda
contra Carneadeam illam sententiam. Qualem igitur hominem natura inchoavit?
DISSOLVE TO:
>ACT 2<
INT. SOMEWHERE ELSE.
Nellie pushes act headings to new pages.
-LEFT-ALIGNED
This is a left-aligned dialogue block intended for use in split-screen
dialogue.
+RIGHT-ALIGNED
This is a right-aligned dialogue block intended for use in split-screen
dialogue.
In the following example, John and Susie utter identical speech simultaneously.
@JOHN / SUSIE
(in unison)
You are impossible.
In the following example, John, James, and Susie’s speech overlaps.
@JOHN / JAMES / SUSIE
(overlapping)
I don’t know. / I don’t know. / You both know.
In the following example, the lines have been broken after the slashes for clarity.
@JOHN / JAMES / SUSIE
(overlapping)
I regret ever knowing you.
You have diminished my quality
of life. / |
You're both crazy. / |
You are a selfish bastard
with no concern for anyone but
yourself.
>END of THE SILVER SALT CELLAR<