Extension:ScreenPlay

The MediaWiki ScreenPlay Extension (ScreenPlay) is a text-formatting add-on which allows screenwriters and hobbyists the ability to use MediaWiki as a screenwriting tool.

Synopsis
An example is described

A Darkened Room

BOB sits in front of a computer screen.


 * bob
 * Hello friends, I'm so glad you could join us. We're gonna make a happy little program today.


 * voice
 * (offstage)
 * Oh goodie!

the end

Will produce the following type of formatting:

Note how word case has been adjusted in certain cases.

Description
ScreenPlay supports three new editing hooks to add style codes that visually re-format certain wiki syntax (specifically, those used for definition lists, or "dl's") into proper screenplay format. The extension also adds a new "Special" page, which produces PDF output for a hard copy. PDF output provides additional notation, including page and scene numbering and dialogue continuation notes.

Though ScreenPlay is not a replacement for a full-featured ScreenWriting software package, it offers a number of advantages for screenwriters:


 * 1) It's free (most decent screenwriting software is expensive).
 * 2) You have the advantages of a wiki (including built-in version control, distributed access, multiple user edits, etc...)
 * 3) You can export as a PDF document which can be printed.
 * 4) Using wiki-links, you have a built-in reference system for notes, character drafts, images, etc...
 * 5) It's easily extendable.

Usage
Installing ScreenPlay is as easy as installing any other MediaWiki extension. Create a subdirectory named 'screenplay' in the 'extensions/' directory of your MediaWiki installation. Then download and extract the php source file (there's only one) and copy it into the 'extensions/screenplay/' directory. Add an appropriate include to your LocalSettings.php file. For example:

# require_once("$IP/extensions/screenplay/ScreenPlay-0.5.php"); #
 * 1) This section is for ScreenPlay tags

Once installed, it is a simple matter to use ScreenPlay. Create a new wiki page, and begin by putting a ' ' tag on the first line as directed below. When rendered, this page will now contain screenplay formatting. To add a scene, use the ' ' tag as directed below. Stage directions are entered as normal paragraphs, and dialogue is written using "dl" syntax, (the ';' and ':' characters). The "dl" method is used because by simply changing the style attributes associated with them, the "dt" and "dd" html elements become the perfect tool for formatting dialogue (due to their already logically correct structure). Beyond that, you can use any built-in wiki formatting you desire. Be warned, however, that the PDF engine does not yet support additional formatting codes. PDF output may not look as you expect it.

Hooks
For correct PDF processing, all hooks should start and end on the same line.

Title
The 'screenplay' hook is used to activate the extension. The value of 'title' is used in the construction of a title page by the PDF engine. See below. This tag should appear near the top of your document, ideally as the first line. It can also be included through a template (though doing so removes the title page from a generated PDF), but again... keep it near the top.

The tag actually inserts a code block into the output HTML which changes the default style attributes of the definition lists used to create dialogue. In addition, a block is also inserted. It is this which adds a new entry to the top tab list for viewing the document as a PDF.

Location
This hook is used to add a scene heading to your screenplay. A standard scene heading usually looks somthing like this:

INT. - Big Momma's House   DAY

Where we identify if it is interior or exterior, where the location is, and the time of day. The 'scene' hook allows you to do that easily.

Transition Type
The transition hook is used at the end of a scene to add... well... a transition note. "CUT TO," "FADE TO," "THE END," whatever...

Title Pages
ScreenPlay will add a title page to a generated PDF file if there is anything between the &lt;screenplay&gt; hooks. A simple text string will result in a plain title page with a "by" line that reflects the login ID of the individiual that authored the wiki page.

For a more proper title page, you can enter a simple XML snippit instead. Available XML title page tags are:


 * &lt;title&gt;
 * &lt;author&gt;
 * &lt;address&gt;
 * &lt;phone&gt;

Tags are used one for each line of output (though only the first &lt;title&gt; is used) in place of using new-lines. The following example demonstrates a two-line address:

Sample Screen Play CJ Niemira 123 Anywhere St Albuquerque NM 01234 555-765-4321

Note that when used in this way, the &lt;screenplay&gt; hook does not have to start and end on the same line.

Special Pages
One new "Special" page is added to your wiki if PDF support is available.  Special:ScreenPlayPDF  is created, and automatically linked to the top of any ScreenPlay page. When referenced, this page uses the built-in PDF library provided by PHP to convert your document to a savable PDF file.

PDF output uses PHP's built-in PDF API. If your copy of PHP is not compiled with PDF support, you can still write and view your screenplay in MediaWiki, but the PDF output function will not work. Adding PDF functionality to PHP is beyond the scope of this document.

The default configuration allows for on-disk caching of created PDF files by document edition number. That means once you create a PDF document, the cache remains in use either until deleted or the source document (the wiki page) is changed. You can create a PDF of any previous edition of a document by finding it in history and clicking "view pdf" (provided, of course, that the edition in question supported ScreenPlay).

Instructions for adjusting the default configuration are found in the ScreenPlay source file. You should make all changes in your LocalSettings.php file. Some of the settings you can change include:


 * PDF creation cache control
 * Paper size and all print margins
 * Font face and size

= Compatibility =

ScreenPlay was writen written and tested with a standard MediaWiki 1.5 installation under PHP 5.0.5. As usual, YMMV. Please report your success/failures:

= Version and ChangeLog =

The Latest version is 0.5

To Do List

 * Support for wiki markup (bold, italic, etc...)
 * Support for includes
 * Needs a better way of dealing with configurations
 * Pre-configured paper/font formats would be nice

0.5

 * Adjusted use of PDFlib to be compatable with PHP 5.0+ (thus, for use MediaWiki 1.7+)

0.4

 * Feature add: title page generator added to PDF engine
 * Bug fix: default character width was wrong

0.3

 * Proper documentaion was added
 * Feature add: caching PDF documents
 * Feature add: oldid recognition
 * Feature add: scenes numbered in PDF
 * Feature add: PDF API detection

0.2

 * PDF transformer is now internal, and written in PHP
 * Feature add: tags
 * Feature add: "view pdf" tab at the top of article

0.1

 * Initial version

= Author =

The ScreenPlay extension was written by CJ Niemira .

= Source =

ScreenPlay is licensed under the GNU GPL.

It is available from its home at: http://siege.org/pub/mwspe/ Or through its Subversion repository (requires a password) at: https://www.siege.org/svn/oss/wikiExtensions/trunk/ScreenPlay.php