\input texinfo		@c -*- texinfo -*-
@c %**start of header
@setfilename fountain-mode.info
@settitle Fountain Mode
@c @documentencoding UTF-8
@c @documentlanguage en
@c %**end of header

@dircategory Emacs
@direntry
* Fountain Mode: (fountain-mode).	Write screenplays.
@end direntry

@c macros
@macro program
@w{Fountain Mode}
@end macro
@macro version
3.6
@end macro
@macro repository
https://github.com/rnkn/fountain-mode
@end macro
@macro theauthor
Paul W. Rankin
@end macro
@macro authoremail
@email{hello@@paulwrankin.com}
@end macro
@macro tbc
Sorry, this node is not yet written. You can help by submitting a patch!
@end macro

@copying
Copyright @copyright{} 2021--2023 Paul W. Rankin

The following people contributed to this documentation:@*
Paul W. Rankin, Kohl Sudduth
@end copying

@finalout
@titlepage
@title Fountain Mode
@subtitle @w{GNU Emacs} major mode for screenwriting in Fountain markup
@author Paul W. Rankin
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex

@node Top
@top Fountain Mode

@quotation n.b.
This manual is a work in progress with many parts still missing. Please
consult the help functions within Emacs for current documentation.
@end quotation

@program is a screenwriting (and playwriting) program for
@w{GNU Emacs} version 24.4 or later. The Fountain markup format is a
plain-text format designed to be easily readable and editable,
portable and future-proof, and to look as much like a script as
possible.

This is the @program Manual updated for version @version{}.

@ifhtml
Check out the
@uref{images/, screenshot gallery}.
@emph{Please send me your screenshots!}
@end ifhtml

The public @program repository is hosted on
@uref{@repository{}, GitHub}.

@end ifnottex

@menu
* Overview::			The pitch.
* Installation::		Getting started.
* Script Elements::		The constituent parts of Fountain.
* Outlining::			Organize your script in pieces.
* Navigation::			Fly through your script with ease.
* Syntax Highlighting::		Differentiate all the elements with colors.
* Element Aligning::		WYSIWYG visual indentation of script elements.
* Text Emphasis::		Bold, italic and underline.
* Do What I Mean::		Traditional TAB-style autocompletion.
* Autocompletion::		Completion of frequently used text.
* Scene Numbering::		Adding numbers to a script scenes.
* Pagination::			Counting a navigating script pages.
* Exporting::			Sharing your great writing!
* Contact::		        Help is never far away.
* Indexes::			What are you looking for?
@end menu

@node Overview
@unnumbered Overview

@program combines the simplicity of Fountain syntax with the
extensibility of Emacs. @program is a major mode for Emacs, which
is to say it is a program that runs inside Emacs --- the extensible,
customizable, free/libre text editor. It enables the writer to engage
with all aspects of realizing a screenplay --- story development,
outlining, drafting, and rewriting.

To quickly get up to speed with Fountain syntax, memorize the rules for
the six most used elements of the screenplay format: @ref{Scene Headings},
@ref{Action}, @ref{Characters}, @ref{Dialogue}, @ref{Parentheticals}, and
@ref{Transitions}.

Then learn how to outline a script. @xref{Section Headings}. This will
be familiar for anyone who has used Markdown, as the syntax is the
same. Sections allow you to easily show or hide and reorder large
parts of a script.

There are additional Fountain syntax elements to allow for
brainstorming, capturing ideas and omitting a part of the script
without deleting it. @xref{Synopses}, @ref{Notes}, and @ref{Comments}.
These elements are not usually included in the formatted output.

All of @program{}'s capabilities are accessible via the menu, and all
customization is performed via the @code{Fountain} option group.
@xref{(emacs) Customization Groups}.

@node Installation
@unnumbered Installation

The latest stable release of @program is available as an Emacs
package via
@uref{https://stable.melpa.org/#/fountain-mode, MELPA-stable}.

In order to install packages via MELPA-stable, you'll first need to
add it to your package archives:

@example
M-x customize-option RET package-archives RET
@end example

Insert an entry named @code{melpa-stable} with the URL
@code{https://stable.melpa.org/packages/}

You can then find the latest stable version of @code{fountain-mode} in
the list returned by:

@example
M-x list-packages RET
@end example

If you like to live on the bleeding edge and prefer the latest but
perhaps unstable version, do the above using
@uref{https://melpa.org/#/fountain-mode, MELPA}.
Unless you are already familiar with debugging Elisp code, it is
strongly encouraged to use the stable version.

@menu
* Requirements::		Do you have what it takes?
* Advanced Installation::	For the pros.
@end menu

@node Requirements
@unnumberedsec Requirements

@program is compatible with Emacs version 24.4 and later.

For Emacs versions older than 26.1, there is a bug in the @code{outline}
library. This will be automatically patched provided
@code{fountain-patch-emacs-bugs} is non-nil and Emacs is installed with
its Elisp source files.

For Emacs versions older than 25.1, the @code{seq} library will need to
be installed; if you install using the Emacs package management system,
@code{seq} will be installed automatically.

@node Advanced Installation
@unnumberedsec Advanced Installation

Download the
@uref{https://github.com/rnkn/fountain-mode/releases/latest, latest release},
move this file into your @code{load-path} and add the following to your
@code{init.el} file:

@example
(require 'fountain-mode)
@end example

If you wish to contribute to or alter @program{}'s code, clone the
repository into your load-path and require as above:

@example
git clone @repository{}
@end example

@xref{(emacs) Lisp Libraries}.

@node Script Elements
@unnumbered Script Elements

The central idea of writing a script in Fountain is that you should be
able to just start writing --- as long as your text looks like a script,
you should get correctly formatted output.

@quotation n.b.
@program uses the @w{Fountain 1.1} syntax specification.
While some programs use custom additions to the specification, for the
greatest cross-compatibility, stick with the 1.1 spec.
@end quotation

@menu
* Metadata::			Key-value info at the top of your script.
* Section Headings::		Outline your script with @code{#}-prefixed headings.
* Scene Headings::		Lines beginning with @code{INT}, @code{EXT}, etc.
* Action::			Anything that's not another element.
* Characters::			Names are in ALL-CAPS.
* Dialogue::			Text following character elements.
* Parentheticals::		Text inside (parens) within dialogue.
* Transitions::			Uppercase lines ending in @code{TO:}.
* Notes::			Text within @code{[[} double brackets @code{]]}.
* Synopses::			Lines beginning with @code{=}.
* Center Text::			Put your titles @code{>} between these @code{<}.
* Comments::			C-style multi-line comments (aka ``Boneyard'').
@end menu

@node Metadata
@unnumberedsec Metadata

A Fountain script usually starts with some metadata stating the basic
information about the script. These are colon-separated key-value pairs
at the start of a file:

@example
key: value
@end example

Other Fountain-compatible programs may refer to this as ``title page''
info, but metadata can store information not related to or present on
the title page.

Calling @code{auto-insert} will guide you through adding the most common
Fountain metadata, prompting with likely defaults:

@itemize
@item
@code{title} is pretty obvious, and will default to base-name of the
current buffer.
@item
@code{credit} is not actually your name, but the type of credit given to
the @code{author}, e.g. @code{written by} or @code{screenplay by}.
@item
@code{author} is you or your writing team, and defaults to the value of
variable @code{user-full-name}.
@item
@code{format} will override the value of
@code{fountain-default-script-format} for the current script. Accepted
values are: @code{screenplay}, @code{teleplay}, @code{stageplay}.
@item
@code{date} defaults to the current date in your locale's ``preferred''
format.
@item
@code{source}, for if you're writing an adaptation.
@item
@code{contact} is useful if the writer wants readers to ever get in
touch to make the film/play!
@end itemize

All metadata keys can take either a single line of input following the
colon, or a newline followed multiple lines indented with whitespace:

@example
author:
	Mary Maryland
	and
	Alan Smithee
@end example

Metadata keys are case-insensitive, e.g. @samp{Title} is the same as
@samp{title}.

@node Section Headings
@unnumberedsec Section Headings

Section headings are lines beginning with @code{#} (number sign). There
are five levels of section headings, with additional @code{#} characters
demoting the outline level of a heading.

@example
# Top-Level Heading

## Sub-Heading

### Sub-Sub-Heading
@end example

@xref{Outlining}.

@node Scene Headings
@unnumberedsec Scene Headings

A scene begins with a scene heading.

Scene headings begin with a prefix, specified in
@code{fountain-scene-heading-prefix-list}, which defaults to:

@example
INT, EXT, EST, INT./EXT., INT/EXT, I/E
@end example

Each prefix may be followed by a dot and/or a space, so the following
are equivalent:

@example
INT HOUSE - DAY

INT. HOUSE - DAY
@end example

@defopt fountain-scene-heading-prefix-list
This options allows setting your own scene heading prefixes. These
entries are case-insensitive.
@end defopt

@defopt fountain-scene-heading-suffix-separator
This option allows setting the separator (a regular expression)
between the scene location and time of day. The default @samp{ --? }
allows either one or two dashes.
@end defopt

@xref{Scene Heading Completion}.

@node Action
@unnumberedsec Action

Action is the easiest Fountain element --- anything that isn't parsed as
another element is considered action.

Sometimes you may write some action that will be unintentionally parsed
as dialogue, for example:

@example
Jack examines his shopping list...

BLACK SHIRT
BLACK PANTS
EXPLOSIVES
MAP
@end example

Here @code{BLACK SHIRT} would be parsed as a character, who then shouts
``BLACK PANTS!...'' We don't want that. To prevent this, prefix the
first line with @code{!} (exclamation mark). This is known as a
``forced'' element.

@example
!BLACK SHIRT
BLACK PANTS
EXPLOSIVES
MAP
@end example

@node Characters
@unnumberedsec Characters

To write a character name to cue some dialogue, type the name in
uppercase (ALL-CAPS).

@example
JOLENE
@end example

The next line will be parsed as dialogue.

Sometimes you might want to include lowercase letters in a character
name. To force a line as a character name, prefix it with @code{@@} (at
sign).

@example
@@JOLENE McCLOGGS
@end example

Some Fountain tools may not parse a line as a character name if the
extension contains lowercase letters, requiring the @code{@@} prefix.

@example
@@JOLENE (cont'd)
@end example

If you are just writing the character's name within action, type the
character's name normally.

@example
Jolene
@end example

If you prefer to write character names within action in uppercase,
that's fine too. The following will still be parsed as action.

@example
JOLENE throws the chair at PHILIP.
@end example

@xref{Character Name Completion}.

@node Dialogue
@unnumberedsec Dialogue

Dialogue is any text following @ref{Characters}. Just enter a newline
and the next text entered will be parsed as dialogue.

@example
JOLENE
Have you seen trouble? I seem to have misplaced it.
@end example

@node Parentheticals
@unnumberedsec Parentheticals

Anytime the writer types a (parens) inside of a dialogue block, the text
auto-formats into the correct position.

@example
JOLENE
(concerned)
Have you seen trouble? I seem to have misplaced it.
@end example

@xref{Autocompletion}.

@node Transitions
@unnumberedsec Transitions

@tbc

@node Notes
@unnumberedsec Notes

@tbc

@node Synopses
@unnumberedsec Synopses

A synopsis is a handy way to detail what a scene or section is about. A
synopsis element is simply a line beginning with @code{=} (equals sign).

@example
INT. FISHING TRAWLER - DAY
= The men eat the shark they caught.
@end example

Synopses are not included by most export tools.

@node Center Text
@unnumberedsec Center Text

@tbc

@node Comments
@unnumberedsec Comments

Text that are in C-style comments, /* like this */, is not exported by
export tools. It's text that's ``in the boneyard''. Unlike other
Fountain syntax, these comments can span newlines and other
formatting; structurally, it's as if the text were removed.

This ``boneyard'' is for text that you're on the brink of removing, or
drafts that you aren't ready to ``uncomment'' and include yet, or just
anything else you want to ignore.

If you instead just want to annotate your screenplay, use @ref{Notes}
or @ref{Synopses}.

@node Outlining
@unnumbered Outlining
@kindex TAB
@kindex S-TAB

There are five levels of section headings. Scene headings count as the
sixth level headings.

Cycle an individual subtree visibility with @kbd{TAB}. Cycle global
outline visibility with @kbd{S-TAB} (shift-tab) or @kbd{C-u TAB}.

Acts, Sequences, Sections, and Scenes can be given meaningful titles,
giving the writer a bird's eye view of the story and structure at a
moments notice.

There are many ways to approach writing a screenplay. Here's one example
of how to use @program to Outline a script.

@example
# Act

= Synopsis of an Act. A short summary of all the crazy things that
happen for the next 30-60 pages.

[[ Act One Note. Useful for character motivation and obstacles. Ideas to
remember, etc.]]

## Sequence

= Synopsis of a Sequence.

[[ Sequence Notes. A sequence can be thought of as a series of several
scenes that make up their own mini-story. ]]

INT. SCENE - NIGHT

= Synopsis of a scene.

[[ Notes to remember for a scene, such as the following:
- Who wants what from whom?
- What are they willing to do get what they want?
- What happens if they don't get it? ]]
@end example

Experimenting with different structures can be accomplished by folding a
Section Heading and moving the section to the new desired location using
keyboard shortcuts.

Note: all text contained within the fold is carried to the new location.

Just as there are many ways to tell a story, there are many ways to
outline a script. Because @program uses plaintext, it does not
force the writer into a single way of working. Possible structures are
limited only by one's imagination.

@deffn Command fountain-insert-section-heading
Bound to @kbd{M-RET}, insert an empty section heading at the current
outline level.
@end deffn
@kindex M-RET

@deffn Command fountain-outline-to-indirect-buffer
If you want to focus on discrete sections of your script you can open
these in indirect buffers. Bound to @kbd{C-c C-x b}, this command
clones the current section or scene to indirect buffer.

@xref{(emacs) Indirect Buffers}
@end deffn

@defopt fountain-pop-up-indirect-windows
Set this to control how indirect buffer windows are opened. Sometimes
you might want to limit your focus to one sequence, other times you
might want to look at two scenes in windows side-by-side. Set this
option to spawn a new window.
@end defopt

@node Navigation
@unnumbered Navigation

@deffn Command fountain-outline-next
Bound to @kbd{C-M-n}, move to the next visible heading line. Also
@code{fountain-outline-previous}, bound to @kbd{C-M-p}.
@end deffn
@kindex C-M-n
@kindex C-M-p

@deffn Command fountain-outline-forward
Bound to @kbd{C-M-f}, move forward to the ARG'th subheading at same
level as this one. Also @code{fountain-outline-backward}, bound to
@kbd{C-M-b}.
@end deffn
@kindex C-M-f
@kindex C-M-b

@deffn Command fountain-outline-beginning
Bound to @kbd{C-M-a}, move to the beginning of the current subtree.
@end deffn
@kindex C-M-a

@deffn Command fountain-outline-up
Bound to @kbd{C-M-u}, move to the visible heading line of which the
present line is a subheading.
@end deffn
@kindex C-M-u

@deffn Command fountain-forward-character
Bound to @kbd{M-n}, goto Nth next character (or Nth previous is N is
negative). Also @code{fountain-backward-character}, bound to @kbd{M-p}.
@end deffn
@kindex M-n
@kindex M-p

@deffn Command fountain-forward-page
Bound to @kbd{C-x ]}, move to Nth next page (or Nth previous if N is
negative). Also @code{fountain-backward-page}, bound to @kbd{C-x [}.
@end deffn
@kindex C-x ]
@kindex C-x [

@deffn Command fountain-goto-scene
Bound to @kbd{M-g s}, move point to Nth scene in current buffer.
@end deffn
@kindex M-g s

@deffn Command fountain-goto-page
Bound to @kbd{M-g p}, move point to Nth page in current buffer.
@end deffn
@kindex M-g p

@node Syntax Highlighting
@unnumbered Syntax Highlighting

@tbc

@node Element Aligning
@unnumbered Element Aligning

@tbc

@node Text Emphasis
@unnumbered Text Emphasis

Text can be underlined, italic, bold, or a combination thereof.

Underlined text is surrounded by @code{_underscores_}.

Italic text is surrounded by @code{*single asterisks*}

Bold text is surrounded by @code{**double asterisks**}

For the writer pursists who want to work the way our ancestors did on
typewriters, stick to underlining.

@node Do What I Mean
@unnumbered Do What I Mean
@kindex TAB

Like many screenwriting programs, in @program pressing @kbd{TAB}
will do the most convenient thing based on context.

The most common use is triggering autocompletion. If the point is at a
blank line or the end of a non-blank line, pressing @kbd{TAB} will
call @code{completion-at-point}. @xref{Autocompletion}.

In @program{}, @kbd{TAB} is also used to control outline visibility. So
if point is at a scene or section heading, it will cycle visibility of
that scene of section between collapsed and expanded. To allow for
more control over outline cycling, if @kbd{TAB} is prefixed with
@code{ARG}, call @code{fountain-outline-cycle} and pass @code{ARG}.
@xref{Outlining}.

@kbd{TAB} also helps working with parentheticals. If the point is at a
blank line within dialogue, it will insert a parenthetical; if the
point is inside an empty parenthetical, it will delete it, or if
inside a non-empty parenthetical, move to a newline.

If the point is at or inside a note, @kbd{TAB} will cycle visibility
of that note between collapsed and expanded.

This all might seem complicated, but the idea is by covering all the
cases you don't have to think about it.

@deffn Command fountain-dwim
This is the command you'll use the most. Bound to @kbd{TAB}, it will
perform the most convenient action based on the current context.
@end deffn

@node Autocompletion
@unnumbered Autocompletion

One of the nice things about using a dedicated screenwriting program
is that it helps you type less of the things you need to type a
lot. @program provides autocompletion for scene headings and character
names.

@deffn Command fountain-completion-update
This command, bound to @kbd{C-c C-x a} will update the completion
candidates for current buffer.
@end deffn
@kindex C-c C-x a

@menu
* Scene Heading Completion::	Complete times and places.
* Character Name Completion::	For every time someone speaks.
@end menu

@node Scene Heading Completion
@unnumberedsec Scene Heading Completion
@kindex TAB

If the line has a partial scene heading, i.e. it begins with a prefix
from @code{fountain-scene-heading-prefix-list} like so:

@example
INT. |
@end example

@kbd{TAB} will offer completions of previously used locations.

If the cursor is at the time-of-day, like so:

@example
INT. SUBMARINE - |
@end example

@kbd{TAB} will offer completions from
@code{fountain-scene-heading-suffix-list}.

@node Character Name Completion
@unnumberedsec Character Name Completion
@kindex TAB

The most basic use of this is when pressing @kbd{TAB} on an empty line.
If there's an empty line above, this will offer to autocomplete a
character name. Character names are suggested in the order:

@enumerate
@item
the second-to-last previously speaking character within the current
scene, i.e. a character's conversational partner;
@item
the last speaking character within the current scene, i.e. a character
continuing speaking;
@item
the remaining characters in the script in order of frequency (default if
there are not yet speaking characters in the current scene).
@end enumerate

@kbd{TAB} will also offer character name completion if a line has a
partial character name.

When the cursor is after a character name and opening parenthesis,
@kbd{TAB} will offer completions from
@code{fountain-character-extension-list} plus
@code{fountain-continued-dialog-string}.

@example
MARY (|
@end example

When the cursor is at an empty line within dialogue, @kbd{TAB} will add
an empty parenthetical.

@example
MARY
|
I'm hungry.
@end example

Likewise, if the cursor is within an empty parenthetical, @kbd{TAB}
will remove the parenthetical.

@example
MARY
(|)
I'm hungry.
@end example

When the cursor is at the end of a non-empty parenthetical, either
inside or outside the closing parenthesis, @kbd{TAB} will move to the
beginning of the next line if the next line is non-empty, otherwise it
will insert a newline.

@example
MARY
(angry|)
I'm hungry.
@end example

When the cursor is at the end of a non-empty line of dialogue, and the
value of @code{fountain-dwim-insert-next-character} is non-nil,
@kbd{TAB} will insert an empty line and the second-to-last previously
speaking character.

@example
MARY
(angry)
I'm hungry.|
@end example

The cursor will be left at the end of the next character, allowing
successive presses of @kbd{TAB} to cycling through additional character
completion candidates.

@example
MARY
(angry)
I'm hungry.

JOHN|
@end example

@node Scene Numbering
@unnumbered Scene Numbering

@tbc

@node Pagination
@unnumbered Pagination

@tbc

@deffn Command fountain-count-pages
Bound to @kbd{C-c C-p}, return both the current page and the total
page count of the current buffer.
@end deffn
@kindex C-c C-p

@node Exporting
@unnumbered Exporting

Exporting a script in @program is handled by one or more external
command-line tools. Here are some recommended export tools:

@itemize
@item
@uref{https://github.com/ifrost/afterwriting-labs, Afterwriting}
@item
@uref{https://github.com/Wraparound/wrap, Wrap}
@item
@uref{https://github.com/vilcans/screenplain, Screenplain}
@item
@uref{https://github.com/olivertaylor/Textplay, Textplay}
@footnote{Requires @uref{https://www.princexml.com, PrinceXML} for PDF
export.}
@end itemize

By defining an ``export profile'', you can easily interface with an
external tool from within Emacs. A profile is essentially a shell
command, interpolated with a selection of values:

@itemize
@item
@code{%b} is the @code{buffer-file-name}
@item
@code{%B} is the @code{buffer-file-name} sans extension
@item
@code{%n} is the @code{user-full-name}
@item
@code{%t} is the title (@xref{Metadata}.)
@item
@code{%a} is the author (@xref{Metadata}.)
@item
@code{%F} is the current date in ISO format
@item
@code{%x} is the current date in your locale's ``preferred'' format
@end itemize

@deffn Command fountain-export-command
This command, bound to @kbd{C-c C-e}, will prompt for an export
profile. The first profile is considered default, so just hitting RET
is a quick way to export in your usual way.
@end deffn
@kindex C-c C-e

@deffn Command fountain-export-view
This command, bound to @kbd{C-c C-v}, attempts to open the last
exported file. This works by finding the other most recently modified
file in the current directory matching the current file base-name.
@end deffn
@kindex C-c C-v

@node Contact
@unnumbered Contact

If you run into any trouble using @program{}, or you have a feature
request, you can email the maintainer @theauthor directly at
@authoremail{}.

For bugs, please ensure you can reproduce with:

@example
$ emacs -Q -l fountain-mode.el
@end example

You can also try the @code{#emacs} IRC channel on
@uref{https://libera.chat, Libera.chat} where @program{}'s maintainer
uses the nickname @code{rnkn}, but please note that most other users
on the channel are unlikely to be screenwriters.

Known issues are tracked with @code{FIXME} comments in the source.

Financial reward is not a consideration in maintaining @program{}, but
if you would still like to support development, donations are
graciously accepted via @uref{https://github.com/sponsors/rnkn,
GitHub} or @uref{https://liberapay.com/rnkn/, Liberapay}.

@node Indexes
@unnumbered Indexes

@menu
* Key Index::
* Index of Commands::
* Index of User Options::
@end menu

@node Key Index
@unnumberedsec Key Index
@printindex ky

@node Index of Commands
@unnumberedsec Index of Commands
@printindex fn

@node Index of User Options
@unnumberedsec Index of User Options
@printindex vr

@bye
