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

NAME
     nellie - Screenplay Formatter for FreeBSD and Mac OS X

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

DESCRIPTION
     Nellie converts a text document marked up as a screenplay with Tree
     Structure Markup Language into a formatted screenplay expressed as a
     Portable Document Format document.

     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 Enlish text only.  Nellie strips bytes from its input
     with their high order bits set.  Nellie's PDFs use the Courier font that
     your PDF viewer supplies.  The built-in font assumes character data is
     encoded in the Adobe standard encoding, which is a subset of ISO-8859-1.
     Only those characters present in your PDF viewer's version of the font
     will render.  In practice, only the glyphs for ASCII can be relied upon
     to be present.  Stripping bytes with their high order bits set
     effectively removes non-ASCII characters including UTF-8 multibyte
     characters.

     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.

     -v    causes 'v' headings to start on a new page.

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

     -x    causes nellie to produce Fountain output from TSML input.

     -c    causes nellie to produce TSML output from Fountain input.  Nellie's
           fountain support is described in the section titled FOUNTAIN.

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

     [y[
     [m[
       [t[ TITLE 1;;TITLE 2 ]]
       [a[ Author 1; Author 2 ]]
       [c[ Contact 1; Contact 2 ]]
       [r[ Revision 1; Revision 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? ]]
     ]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.

          [t[Title;;Subtitle]]

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

          'a'  specifies the authors.

          'c'  specifies contact information.

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

          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.

     '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 a 'v' heading to
          a new page if space for fewer than 6 lines remains on the page.
          This is to leave enough room for an act heading, a blank line, a
          scene heading, a blank line, and 2 action lines.  To force the
          content of 'v' elements to appear at the top of new pages, include
          the -v option on the command line.

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

          Nellie pushes an 's' heading to a new page if space for fewer than 4
          lines remains on the page.  This is to leave enough room for a scene
          heading, a blank line, and 2 action lines.  If the scene heading
          spans multiple lines after wrapping, nellie increases the required
          space accordingly.

     'a'  provides the content of an action paragraph.

     'c'  provides the content of a character cue that introduces dialogue.
          Nellie pushes a 'c' heading to a new page if space for fewer than 4
          lines remains on the page and the succeeding 'p' and 'd' paragraphs
          cannot fit into that space with the heading.  This is to leave room
          for the cue heading, 2 lines of dialogue or parenthetical, and
          possibly a (MORE) line.

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

     '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 provides no means to change the font.  You cannot embolden text or
     format it in italics.  Boldface is intrusive outside of headings, and
     Courier Oblique is not oblique enough to attract the eye.  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 because Fountain describes a
     screenplay mostly by textual formatting.  Explicit markup is seldom
     required.  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 restricted subset of Fountain:

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

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

     3.   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, and "Contact" is converted into a 'c' element.

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

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

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

     7.   Nellie does not recognize ! to force action paragraphs.

     8.   If your action or dialogue paragraphs begin with 'INT.' or 'EXT.'
          regardless of capitalization, '.', '>', '(', or '@', add a space
          character to the start of the paragraphs.  Nellie normalizes
          whitespace when it processes TSML.

     9.   Nellie does not recognize blank lines in dialogue.  Lines following
          a blank line are formatted into action paragraphs.  To indicate a
          pause, use a parenthetical.

     10.  Scene headings, transitions, character cues, and parentheticals must
          appear complete on single input lines.

     11.  All asterisks are removed from the source text.

     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.

     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

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

                               Sat May 12, 2018