0. NELLIE

Nellie formats a plain text (utf-8) screenplay as a PDF document or an EPUB
ebook.

0.1. CHARACTER SET

Nellie uses an Open Source Courier-style font for PDFs. As a consequence,
Nellie supports the character set ranges that the fonts support. These
ranges support European languages that use alphabets derived from the Latin
alphabet only.


1. MARKUP

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.

Non-ASCII characters can be entered as ASCII backslash escape sequences:

\' followed by an upper or lowercase vowel inserts the utf-8 character
sequence for that vowel with an acute accent.

\` inserts grave-accented vowels.

\^ inserts circumflex-accented vowels.

\: inserts diaresis/trema/umlaut-accented vowels and upper and lowercase Ys.

\~ inserts only upper and lowercase Ns with tildes.

\, inserts only upper and lowercase Cs with cedillas.

\u followed by a decimal number inserts a Unicode character by code point.
If the code point is immediately followed by digits that are part of the
document text, those digits must be represented by \u escapes, or the
digits will be interpreted as part of the code point.

1.1. SCENE HEADINGS

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 emboldens scene headings unless the -b option appears on the command
line.

Nellie converts scene headings to upper case.

Nellie numbers scenes when the "Add Scene Numbers" setting is enabled.

1.2. SHOT HEADINGS

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 emboldens shot headings unless the -t option appears on the comman
line.

Nellie numbers and letters shots when the "Add Scene Numbers" setting 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.

1.3. ACTION PARAGRAPHS

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.

1.4. DIALOGUE BLOCKS

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.

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.
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.

1.5. TRANSITIONS

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.

1.6. NOTES

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.]]

Note paragraphs that begin with a hyphen followed by a space receive a
hanging indent.

To insert editorial content that is not removed by the formatter, insert
the content inside single bracket pairs: [Note].

1.7. ACT HEADINGS

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.

Nellie centers act headings and renders them in boldface unless the -o
option is present on the command line. Setting this option also prevents
Nellie from emboldening End Headings and titles on title pages.

1.8. END HEADINGS

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.

Nellie centers end headings and renders them in boldface.

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.


2. EMPHASIS

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.


3. TITLE PAGES

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 or insert the Unicode
escape sequence for a space character: \u32.

Author:
 By
 \u32
 Carnaby Fimblethwicke
 \u32
 and
 \u32
 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. That would defeat the purpose of watermarks.


4. EBOOKS

The 'Copyright' and 'Language' title block data are only used when Nellie
generates ebooks.

If you save 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

If you want to upload your ebooks to an ebook vendor such as Apple Books
you must include cover images. Use the -i command line option with the -e
option.  Consult the nellie manual page for details (man nellie).

The first image is the external cover. This must be a high resolution
image. A good size for this image is 2560 pixels in height by 1600 pixels
in width.

The second image is the internal cover. This image must be less than 4
megapixels in size. Note that this limit is expresed in pixels and not
bytes. A good size for this image is 1600 pixels in height by 1000 pixels
in width.


5. EXAMPLE

An example screenplay fragment follows.


Title: THE SILVER SALT CELLAR
Draft Date:
 $D
 $W
Author:
 By
 \u32
 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.

[If you turn on scene numbers, you will observe that scenes are numbered
and shots are lettered. You can control the emboldening of act, scene, and
shot headings in the app's settings.]

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.

>END of THE SILVER SALT CELLAR<
