Version 1.21.2

Vimballed, now with proper help file. Wiki file now opens full window (more common behavior), but with the sidebar still available as an option. New command brings you back to your screenplay. Hack added for properly exploiting Vimwiki search (if using Vimwiki in conjunction). More options for customizing indentation. Filename token deprecated, now optional.

1 files changed, 362 insertions, 0 deletions

diff --git a/doc/fountainwiki.txt b/doc/fountainwiki.txt
new file mode 100644
index 0000000..7a9d020
--- /dev/null
+++ b/doc/fountainwiki.txt
@@ -0,0 +1,362 @@
+*fountainwiki.txt*   for Vim version 7.3.   Last change: Feb 21 2012
+
+                                 FountainWiki
+                                 ''''''''''''
+
+Light wikification of Fountain screenplay files plus syntax & indentation.
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+Author: Carson Fire <carsonfire@gmail.com> 
+	http://twitter.com/carsonfire
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+CONTENTS                                *fountainwiki* *fountainwiki-contents* 
+
+ 1. FountainWiki introduction             : |fountainwiki-introduction|
+ 2. FountainWiki quick help               : |fountainwiki-quick-help|
+ 3. Fountain syntax                       : |fountain-syntax|
+    FountainWikiWords                     : |fountainwikiwords|
+ 4. FountainWiki and Vimwiki              : |fountainwiki-and-Vimwiki|
+ 5. FountainWiki options                  : |fountainwiki-options|
+ 6. Fountain indentation                  : |fountain-indentation|
+ 7. Fountain indentation options          : |fountain-indentation-options|
+ 8. FountainWiki commands                 : |fountainwiki-commands|
+
+==============================================================================
+1. FountainWiki introduction                       *fountainwiki-introduction* 
+==============================================================================
+The purpose of FountainWiki is to provide a note-taking facility that does not
+require any deviation from strict Fountain syntax.
+
+FountainWiki turns CHARACTER NAMES, ## Section headers and [[comments]] into
+WikiWords. Simply press 'enter', and a new file opens for keeping notes. These
+notes can be simple text files, or tap into other availabie file formats and
+systems.
+
+The indentation is not automatic as you type, but we include optional
+automatic indentation upon saving, or by hitting 'ctrl+enter'.
+
+==============================================================================
+2. FountainWiki quick help                           *fountainwiki-quick-help* 
+==============================================================================
+
+	     Auto indent              :w (save file)
+	     Manual indent            ctrl-enter
+	     ----------------------------------------------------
+	     Open/create reference    enter, on FountainWikiWords
+	     Close reference          enter, anywhere else
+	     FountainWikiWords        CHARACTER NAMES
+	                              ## Section headers
+	                              [[And notes]]
+	     Switch focus             <tab> (on either file)
+
+	     ---------------VIMWIKI (IF SELECTED)----------------
+             Must search from any note, not screenplay:
+             Search all notes         :VimwikiSearch pattern
+                                      :VWS patter
+             Reset wiki home          :ResetWiki
+
+	     ----------------VOOM (IF INSTALLED)-----------------
+	     Outline                  :Voom markdown
+	     Select section           <cr> (enter)
+	     Switch focus only        <tab>
+	     Move section up/down     <c-up/down> (ctrl-up/down)
+
+	     -------------------- NATIVE VIM---------------------
+	     Change entire character line to uppercase        gUU
+             Highlight all instances of CHARACTER      ?CHARACTER
+
+==============================================================================
+3. Fountain syntax and FountainWikiWords                     *fountain-syntax*
+==============================================================================
+A review of Fountain syntax basics. Fountain provides for plain text
+screenwriting:
+
+------------------------------------------------------------------------------
+Title:   Who's Minding Mindle?
+Author:  Frank X. Thwacksway
+
+### Mindle bucks up
+
+INT. CLASSROOM - DAY
+
+Students are doing what unruly students do: making noise, throwing trash,
+tormenting each other. Apparently there is no teacher in sight, but we haven't
+caught a glimpse of the teacher's desk, yet.
+
+CUT TO:
+
+Peter Mindle, the teacher. The students have obviously worn him down. He sits,
+mute, depressed, unhappily resigned to his fate as we hear and catch sight of
+the chaos still erupting around him. He is finally startled out of his funk by
+a voice that he seems to think is coming from the desk in front of him. [[Maybe
+it's coming from the apple?]]
+
+WORM
+(shouting)
+You there! You're not going to stand for this, are you?
+
+------------------------------------------------------------------------------
+This small segment contains a few, but not all Fountain elements.
+
+                                                           *fountainwikiwords*
+
+FountainWikiWords are sections of Fountain syntax that FountainWiki make
+clickable. Specifically, character names, section headers, and notes. True
+WikiWords -- conjoined capitalized words -- are not part of Fountain syntax,
+and are not made clickable through FountainWiki, since they should not exist
+in your screenplay. Simply press 'enter'.
+
+You do not have to click precisely on the character name or a note, but
+somewhere on the line. It's just the same if you hit the indentation before
+the character name, or any dialogue on the same line as a note. In either
+case, the entire name or note on that line becomes the reference.
+
+CHARACTER NAMES
+---------------
+Clickable character names appear in allcaps above dialogue. In the sample
+above, the only character who speaks is WORM; Peter Mindle must speak before
+he is clickable. Whether you call the character in the script PETER, MINDLE,
+or PETER MINDLE, that's entirely up to you; each variation will create a
+different file, so just be consistent!
+
+These character names can now be accessed from any point in the script they
+appear, and in any draft of the script in your screenplay directory. For this
+reason, you may want to separate different projects in different directories,
+otherwise, JACK the timid teacher in a comedy and JACK the tough cop in a
+gritty crime drama will lead to the same reference file.
+
+This may be seen as a weakness, but can also be a boon if working on many
+drafts of the same script, or writing a series based on a large cast of
+continuing characters.
+
+## Section headers and [[Notes]]
+--------------------------------
+Fountain allows ATX-headers, which should be familiar to you if you have used
+Markdown or other similar light markup syntax. These headers begin with
+hashmarks denoting the header level, and sometimes end with hashmarks.  Notes
+are always between double brackets.
+
+In our sample above, the one section header is "Mindle bucks up"; the one note
+is "Maybe it's coming from the apple?" Both of these can be used for reference
+files.
+
+NOTE Section headers may be used simply to designate things like 'Act Three'
+or 'Scene 12'. This will produce predictibly non-unique reference files, and
+may conflict with other scripts in the same directory. We want to avoid
+suggesting methods of differentiating and changing things, as our purpose is
+to provide you with a reference tool that does not intrude on your work. But
+be aware of these potential conflicts. 
+
+NOTE In the case of a line with multiple notes, the last note is chosen.
+
+NOTE You can use multi-line notes for reference files, but you must click on
+the first line, and only the first line of text will be used.
+
+NOTE Although Fountain syntax doesn't address notes in section headers,
+FountainWiki will simply internalize a note as part of the header. So
+something like '# Section [[Notes]] Header' would be read as 'Section Notes
+Header'. 
+
+Everything else
+---------------
+Click on any line that does not contain at least one designated
+FountainWikiWord, and nothing happens. If you use the sidebar option, the
+sidebar closes.
+
+==============================================================================
+4. FountainWiki and Vimwiki                             *fountain-and-vimwiki*
+==============================================================================
+FountainWikiWords create a hook into other file formats and systems that can be
+exploited in different ways. Consider these other formats and systems to be
+*hosts* for your reference files.
+
+Once you leave your Fountain screenplay, you gain the power of another system,
+but you are also technically at its mercy. Type :FountainWiki or :FW to return
+to your screenplay. Or type `<leader>fw`.
+
+We have provided an automatic hack for exploiting Vimwiki's search power, if
+you choose the 'wiki' filetype (see options). When you click from your
+screenplay into a wiki file, we reassign the primary Vimwiki directory to your
+screenplay directory. Then type ':VimwikiSearch pattern' or ':VWS patter' to
+search through all your screenplay notes. You will need to use ':WikiReset' if
+you want to go back to normal.
+
+==============================================================================
+5. FountainWiki options                                 *fountainwiki-options*
+==============================================================================
+To allow as much flexibility as possible, we make everything possible an
+option.
+
+This first one is awfully important, though. The way you keep notes relies on
+setting your filetype preference. When you click on a FountainWikiWord, this
+is the kind of file you will open, use, and save!
+
+	let g:FountainWiki_Card_Extension = 'txt'
+
+This is already set to 'txt' by default, because text files are ubiquitous.
+However, consider using a file type with more power: Markdown is a good
+choice, since Fountain is essentially a companion syntax. With Markdown, you
+get the same kind of headers, plus lists and more.
+
+However, the BEST choice would have to be Vimwiki or one of the other
+Vim-based wiki systems. Hook into the power of Vimwiki simply by setting that
+extension to 'wiki', and installing Vimwiki if you haven't already.
+
+Vimwiki - http://www.vim.org/scripts/script.php?script_id=2226
+
+There's always a catch: regardless what file type you choose now, you need to
+keep your notes together with your screenplay in the same directory. And if
+you decide to change filetypes in mid-stream, the fix is up to you. To keep
+your old notes, you would need to change the existing extensions, and do
+whatever you need to do to convert your text.
+
+Another decision you'll want to make early on is whether or not to allow
+uppercase letters in your filenames. Set to 0 to turn off lowercase-only
+filenames. Default setting is 1, lowercase-only.
+
+	let g:FountainWiki_Lowercase_Filename = 0
+
+Default behavior: a character named BILLY BOB creates a file named
+'billybob.txt'. Allow uppercase for 'BILLYBOB.txt'.
+
+Default behavior: section header '# Hero in Portland' becomes
+'heroinportland.txt'. Set to uppercase for 'HeroinPortland.txt'.
+
+Special characters are simply stripped out. 'BJÖRN' becomes 'bjrn.txt'.
+'PAVLOV'S DOG' becomes 'pavlovsdog.txt'.
+
+FountainWiki does not truncate strings, unless it finds a natural linebreak;
+too-long filenames can result, and will be treated by your system in whatever
+way your system treats too-long filenames. 
+
+	let g:FountainWiki_Filename_Token = '.fnx'
+
+This is a token that can be inserted so that the files can be distinguished
+from other files in the same directory. We have decided to set the default to
+''; it may even be considered deprecated, already.
+
+The rest of the options relate more to the writing environment, and can be
+changed any time without altering the files.
+
+	let g:FountainWiki_Card_Only = 1
+
+Default is '1'; this opens the wiki file fully, in place of your screenplay.
+Set to '0' for a sidebar instead.
+
+If you choose the sidebar, you can adjust its width and position:
+
+	let g:FountainWiki_Card_Width = 48
+	let g:FountainWiki_Card_Right = 1 " 0 for the left side, 1 for the right.
+
+FountainWiki closes other splits to keep things neat. Turn off this behavior
+by changing the following option to '0'. This can get messy!
+
+	let g:FountainWiki_Card_StayOpen = 1
+
+==============================================================================
+6. Fountain indentation                                 *Fountain-indentation*
+==============================================================================
+Indent Fountain files three different ways:
+
+	* Automatically, when saving the file.
+	* Hit 'enter' while in normal mode.
+	* Use the command :FountainWikiIndent
+
+Disable automatic indentation with the command:
+
+	:FountainWikiDisableAuto
+
+To turn it back on, type :FountainWikiEnableAuto		
+
+Our little demo script again, demonstrating the intended results:
+
+Dialogue is not indented, as there is no way to make it look screenplay-like
+without introducing line breaks. We find that line breaks can corrupt
+processing, so we recommend setting your text width to 0. Character names and
+parentheticals are tabbed, and we try to approximate the position of centered
+text and transitions.
+
+Since we are emulating the look of a screenplay, and there is no nesting
+involved, we set the tabstops fairly wide for Fountain buffers, but you can use
+spaces, instead. All of this can be adjusted in the options.
+
+NOTE We are experimenting with ways of protecting your title page block (the
+first lines up to the first blank line), but we haven't quite got it, yet.
+Uppercase-only lines in the title page block may become confused with
+CHARACTER NAMES.
+
+------------------------------------------------------------------------------
+Title:   Who's Minding Mindle?
+Author:  Frank X. Thwacksway
+
+### Mindle bucks up
+
+INT. CLASSROOM - DAY
+
+Students are doing what unruly students do: making noise, throwing trash,
+tormenting each other. Apparently there is no teacher in sight, but we haven't
+caught a glimpse of the teacher's desk, yet.
+
+                                                CUT TO:
+
+Peter Mindle, the teacher. The students have obviously worn him down. He sits,
+mute, depressed, unhappily resigned to his fate as we hear and catch sight of
+the chaos still erupting around him. He is finally startled out of his funk by
+a voice that he seems to think is coming from the desk in front of him. [[Maybe
+it's coming from the apple?]]
+
+                WORM
+        (shouting)
+You there! You're not going to stand for this, are you?
+
+------------------------------------------------------------------------------
+
+==============================================================================
+7. Fountain indentation options                 *fountain-indentation-options*
+==============================================================================
+To save time, when you see '0' and '1' listed as options, that's 'off' and
+'on', respectively.
+
+Turn off our auto indent scheme:
+
+	let g:FountainWiki_Auto_Indent = 0
+
+The width of tabs for Fountain file buffers.
+
+	let g:FountainWiki_Tabstop = '8'
+
+Use the following to tweak the number of tabs, or change to spaces:
+
+	let g:FountainWiki_Character_Indent = '\t\t'
+	let g:FountainWiki_Parenthetical_Indent = '\t'
+	let g:FountainWiki_Transition_Indent = '\t\t\t\t\t\t'
+	let g:FountainWiki_Centered_Indent = '\t\t\t\t'
+
+We recommend leaving textwidth '0' (off), but you can change it here. This
+should affect Fountain buffers only.
+
+	let g:FountainWiki_Textwidth = '0'
+
+==============================================================================
+8. FountainWiki commands                               *fountainwiki-commands*
+==============================================================================
+With any luck, you won't have to remember too many commands. Click 'enter' on a
+FountainWikiWord to open a wiki file. To return to your screenplay file, do one
+of the three:
+
+   :FountainWiki        :FW        <leader>fw
+
+This is the one command you might like to map to something you can type
+quickly, so you can bounce between your screenplay and reference files quickly.
+
+FountainWiki commands:
+
+:FountainWikiCards         Create wiki file from FountainWikiWord.
+:FountainWikiCursorJump    Tabs between files in sidebar mode.
+
+Fountain indentation commands:
+
+:FountainWikiIndent        Run indentation.
+:FountainWikiDisableAuto   Turn off auto indentation.
+:FountainWikiEnableAuto    Turn on auto indentation.
+
+vim:tw=78:ts=8:ft=help:norl: