nellie(1)               FreeBSD General Commands Manual              nellie(1)

NAME
     nellie - Screenplay Formatter for FreeBSD and Mac OS X

SYNOPSIS
     nellie [-n] [-s] [-x | -c | -e | -t] [<infile> [<outfile>]]

DESCRIPTION
     Nellie converts a text document marked up as a screenplay with Fountain
     or with Tree Structure Markup Language into a formatted screenplay
     expressed as a PDF or an ePub.

     Nellie reads from stdin or from a single file specified on the command
     line and writes to stdout or to another file specified on the command
     line.  To specify an output file without an input file, specify an input
     file of '-'.  If the input document is malformed, nellie exits without
     explanation.

     Nellie supports a restricted subset of UTF-8 in input text.  The
     printable characters of the Basic Latin range (ASCII) and the Latin
     Supplement range (Latin 1) are recognized.  This is sufficient to support
     Western European languages.  UTF-8 sequences representing typographical
     single and double quotes and em-dashes are converted into their
     typewriter equivalents.  Nellie strips out other bytes with their high
     order bits set.

     Nellie embeds a subsetted version of the Open Source Courier Prime
     typeface into PDFs.  To comply with the typeface's license (OFL in the
     source distribution), the modified typeface is named Courier Prime Basic.

     Nellie produces output for US Letter size paper (8.5in x 11in).  There is
     no mechanism to change the paper size.

   OPTIONS
     -n    turns on scene numbering.

     -d    specifies a list of scenes to include in the output.  By default
           all scenes are included.  If present on the command line , -d must
           be followed by a list of scene numbers or scene number ranges
           separated by commas:

           nellie -d 2-10,23,30,53-55 <infile> <outfile>

           The first number of a range must be less than or equal to the
           second number.  Items in the list do not have to be in document
           order. The specified scenes are always output in document order. If
           you specify scenes more than once explicitly or in overlapping
           ranges, the duplicate scenes are ignored.

     -s    causes nellie to embed Courier Prime Basic Sans into PDF output
           instead of Courier Prime Basic.

     -e    causes nellie to convert TSML input into an ebook hierarchy rooted
           in the current directory or in the directory specified by the
           second command line argument.  See the section titled EPUB for more
           information.

     -t    causes nellie to produce plain text output from TSML input.

     -x    causes nellie to produce Fountain output from TSML input. This is
           proper Fountain not the modified Fountain subset understood by
           Nellie.

     -c    causes nellie to produce TSML output from Nellie's modified
           Fountain subset input.  Nellie's Fountain support is described in
           the section titled FOUNTAIN.  When -c is present on the command
           line, the -d option is ignored.

   TSML
     TSML is a generic markup language described in tsml(5).  TSML is designed
     to be machine-friendly rather than human-friendly.  Nellie uses a simple
     TMSL scheme to classify paragraphs by type and to define document
     metadata.

     A example TSML screenplay follows.

     [y[
     [m[
       [t[ TITLE 1;;TITLE 2 ]]
       [a[ Author 1; Author 2 ]]
       [c[ Contact 1; Contact 2 ]]
       [r[ Revision 1; Revision 2 ]]
       [w[ Watermark1; Watermark 2 ]]
     ]m]
     [v[ ACT 1 ]]
     [s[ INT. DINER. ]]
     [a[ Our hero eats a cheeseburger. ]]
     [a[ A man nearby talks to a salt cellar. ]]
     [c[ MAN ]]
     [p[ (with affection) ]]
     [d[ You make lunch worth eating.  Where can I find such magnificent food
     enhancing magic as you? ]]
     [i[ This is an indented dialogue paragraph. ]]
     ]y]

   ELEMENTS
     All elements have names of a single letter.  The toplevel element is
     named 'y'.  It contains one or more instances of the following child
     elements.

     'm'  Nellie extracts from the children of the 'm' element the data to use
          in the screenplay's title page and in the PDF Info dictionary.  To
          specify that the text in these elements be formatted into multiple
          lines, separate the data for each line from the others with a
          semicolon.  To insert a blank line between lines, insert 2
          contiguous semicolons.  To insert a semicolon into the data, insert
          a tilde '~' instead. It will be replaced with a semicolon by the
          formatter.

          [t[Title;;Subtitle]]

          't'  specifies the title of the screenplay.  Titles are formatted in
               boldface.

          'a'  specifies the authors.

          'c'  specifies contact information.  All occurrences of the 3
               characters "(C)" are replaced with the copyright symbol.

          'r'  specifies revision information.  To insert the current date,
               make one of the revision lines $D by itself.  To insert the
               manuscript word count, make one of the revision lines $W by
               itself.

          'w'  specifies watermark text to be added underneath the text on
               each page.  All occurrences of the 3 characters "(C)" are
               replaced with the copyright symbol.  The specified lines are
               centered and rendered at 60 points with 90% opacity. The
               watermark is not a PDF annotation and cannot be removed or
               edited by tools that operate on annotations.

          'l'  specifies the language of the input document as a BCP 47
               country code.  Nellie only accesses this element when
               generating ebooks. The value defaults to 'en' (English).

          'y'  specifies a copyright message to be added to the title pages of
               epubs. It should contain the year, a comma, and the name of the
               copyright owner. You can include an email address or web URL
               after another comma, but beware that all text is formatted onto
               a single line. Nellie will precede the copyright information
               with the text ' Copyright' and the c-in-circle copyright
               symbol. If the 'y' element is missing from the metadata, no
               copyright message is added to epubs.

          The 'm' element should only appear once in a document.  If you
          provide multiple instances, each instance's data supersedes the data
          in preceding instances.  The 5 child elements should only appear
          once each inside 'm'.  If you provide multiple instances, the data
          in each instance supersedes data the data in preceding instances.
          If you do not provide the 't', 'a', 'c', or 'r' elements,
          placeholder data is used. Watermarks are optional.

     'v'  provides the content of a centered, boldface heading line separated
          from the rest of the screenplay with a blank line before and after
          the centered line.  The 'v' element is intended for use in creating
          act headings, but you can place any content that you like in these
          elements.

          If the content of a 'v' element wraps onto multiple lines, nellie
          discards all lines after the first.  Nellie pushes 'v' headings to
          new pages.

     'e'  provides the content of a centered, boldface heading separated from
          the rest of the screenplay with a blank line before and after the
          centered line, but 'e' elements are not widow-controlled.  The 'e'
          element is intended for use in creating 'The End' markers at the end
          of screenplays.  End markers are useful because screenplays do not
          describe the page total in title pages or page headers.

          If the content of an 'e' element wraps onto multiple lines, nellie
          discards all lines after the first.

     's'  provides the content of a scene heading.  Nellie formats Scene
          headings in boldface.  To add scene numbers, include the -n option
          on the command line.

     'a'  provides the content of an action paragraph.

     'c'  provides the content of a character cue that introduces dialogue.

     'p'  provides the content of a parenthetical direction for dialogue.  You
          must provide the parentheses characters in the content.
          Parentheticals cannot appear inside other elements.  To place a
          parenthetical inside a paragraph of dialog, break up the dialogue
          into 2 paragraphs:

          [c[JAMES]]
          [p[(to Calvin)]]
          [d[I don't know if I trust you.]]
          [p[(to himself)]]
          [d[I know I don't.]]

     'd'  provides the content of a dialogue paragraph.  Elements with only
          whitespace data are ignored.

     'i'  provides the content of an indented dialogue paragraph.  Insert one
          or more whitespace characters in the data to create a blank line in
          dialog blocks.

     'l'  provides the content of a lyric line. The line is rendered in
          italic. If the line is long enough to be wrapped by the formatter,
          the paragraph formed has a hanging indent.

     't'  provides the content of a transition directive.

   CONTENT
     Nellie discards data outside of terminal elements.  You can place
     comments in between terminal elements.

     Inside of terminal elements, nellie normalizes whitespace by converting
     all whitespace characters into space characters, collapsing multiple
     contiguous spaces into single spaces, and removing leading and trailing
     spaces.

     Nellie underlines words bookended with underscores.  If you want to
     underline a section of text, you must _underline_ _each_ _word_
     _individually_.  You cannot underline metadata for the title page.

     Nellie automatically renders Act, End, and Scene headings in bold and
     lyric lines in italics. Nellie provides no means for you to change the
     font.  To emphasize words, underline them.

     To insert [, ], or \ into element content, escape each with a backslash:

     [a[He looks up. \[At what?\]]]

   FOUNTAIN
     Fountain is a markup language specialized for describing screenplays.
     Fountain is more human-friendly than TSML.  It is convenient for humans
     to write Fountain and let Nellie convert the Fountain to TSML.

     Fountain is described at https://fountain.io.

     Nellie understands a modified subset of Fountain:

     1.   Nellie does not recognize dual dialogue, boneyard text, synopses, or
          outlines.

     2.   Nellie recognizes and removes Fountain notes that comprise entire
          paragraphs.  To be recognized as notes, paragraphs must start with
          '[[' and end with ']]'.  Multiple paragraphs of text may be embedded
          in a single note "paragraph":

          [[Multi-paragraph note.

          Second paragraph of note.]]

     3.   Nellie does not respect explicit line breaks in any paragraph type.
          All contiguous lines are wrapped into ragged-right paragraphs.

     4.   Nellie converts a Fountain title page block into an 'm' element.

          Draft Date:  is converted into an 'r' metadata element.

          Title:
                        is converted into a 't' element.

          Author:      is converted into an 'a' element

          Contact:     is converted into a 'c' element

          Watermark:
                        is converted into a 'w' element.

          Copyright:   is converted into a 'y' element.

          Language:    is converted into an 'l' element.

     5.   If scene headings do not start with INT. or EXT., they must start
          with '.' to force their recognition.  Nellie converts any lowercase
          letters to uppercase.  Scene numbers are removed.  Nellie generates
          scene numbers when the -n option is present on the command line.

     6.   If character cues contain characters other than uppercase letters,
          digits, and spaces, the cues must start with '@' to force their
          recognition.

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

     8.   To force the recognition of action paragraphs that resemble other
          paragraph types, add a '!' to the start of the action paragraphs.

     9.   To force the dialogue of dialogue paragraphs that resemble other
          paragraph types, add a space character to the start of the dialogue
          paragraphs.

     10.  To indent a new paragraph in a dialog block, start a new line in the
          block with '&'.  Leave the line empty after the '&' to insert a
          blank line.  To insert an unindented paragraph after a blank line,
          start a new line with '$'.

     11.  To insert an italic line of lyric text into a dialogue block, start
          a new line in the block with '~'.

     12.  Centered lines are converted to 'v' elements unless the text of the
          lines begins with "END", in which case the lines are converted to
          'e' elements.

     13.  Act, End, and Scene headings, transitions, character cues, and
          parentheticals must appear complete on single input lines.  After
          wrapping, Scene headings, character cues, and parentheticals are
          limited to 10 output lines.  Act and End headings and Transitions
          are limited to 1 line.  Excess lines are discarded.

     The process of producing a PDF file from a Fountain file can be automated
     with a Makefile:

     all: view

     .PHONY: view
     view: screenplay.pdf
        open -a Preview.app screenplay.pdf

     screenplay.pdf: screenplay.tsml
        nellie screenplay.tsml screenplay.pdf

     screenplay.tsml: screenplay.fountain
        nellie -c screenplay.fountain screenplay.tsml

   EPUB
     After nellie has generated an EPUB directory hierarchy, you must zip it
     up to form an EPUB document:

     cd ebook
     zip -X ../screenplay.epub mimetype
     zip -r ../screenplay.epub META-INF OEBPS
     cd ..
     rm -r ebook

     The process of converting a Foutain file into TSML and then into an ebook
     can be automated with a Makefile:

     all: screenplay.epub

     screenplay.epub: screenplay.tsml
        nellie -e screenplay.tsml
        cd ebook && zip -X ../screenplay.epub mimetype && zip -r ../screenplay.epub META-INF OEBPS
        rm -r ebook

     screenplay.tsml: screenplay.txt
        nellie -c screenplay.txt screenplay.tsml

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                               Fri Apr 05, 2019