Extension:Sternograph

Adds the &lt;sterno> tag to allow easy formatting of plays and interviews, or any other kind of spoken word transcript.

Introduction
Currently on MediaWiki, if one wishes to provide an in-text quote one uses the &lt;blockquote> tag or a template. This is fine for short quotes, but on sites such as WikiMedia or Wikia we don't have such simple quotes. In some cases, we have transcripts of whole scenes with multiple speakers: situations that do not lend themselves well to blockquotes and templates. Currently, one must include a manual of style to demonstrate exactly how to format these transcripts.

The drawbacks to this approach are: Stephen: That's with a P-H. Steven: That's with a V. Am I the same person?
 * Multiple specifications. Changing the formatting for one transcript does not guarantee the change is reflected in all other transcripts.  It's also possible that one speaker's cue is different: for example:
 * Inconsistency. Editors have better things to do than making sure all of the transcripts follow the manual of style.
 * Inconvenience. Repeatedly applying formatting every other line is tedious, even in wiki format.

This is where the Sternograph extension comes in. It provides a new tag, within which one can use wiki-style markup to format the speech, unspoken directions, and even a short context paragraph to come immediately underneath the quote. Formatting of the speakers' names and directions are automatically applied from a CSS file.

Usage
Unless otherwise noted, the Sternograph completely ignores whitespace. This means you can place the delimeters on different lines without affecting the appearance of the sternograph.

(All samples are from The Merchant of Venice Act IV Scene i)

Lines
The simplest usage of the sternograph is to include the speaker's name, an = (equals sign) character to separate the speaker from the line, and the ^ (caret) character to separate different speakers. As in this example:

The Sternograph first looks for all the carets and separates them into different sections. If the section contains an equals sign, that is considered a spoken line; otherwise, the section is considered a stage direction. Stage directions are formatted to appear differently from a spoken line.

In a spoken line, everything that occurs before the equal sign is considered to be the name of the speaker; everything that occurs after the equal sign is considered to be what is actually spoken. The name of the speaker is (automatically) formatted differently from the rest of the line.

Only the first equal sign after the caret is intercepted by the Sternograph: all subsequent equals signs are interpreted as normal wiki-text. This means a template in the speaker block that uses equals signs will not work correctly; you can work around this using a Speakers section.

Directions
Stage directions are text that appear in the Sternograph but are not actually spoken. They may appear on their own (a block direction), or as part of a spoken line (an in-line direction). This sample demonstrates both types of directions:

An in-line direction is enclosed within the _ (underscore) character. If no closing underscore is present, then everything until the next caret is interpreted as an in-line direction.

Context
A Sternograph's context is a short paragraph that comes after the spoken line, which can include any text you like.

The context block always comes after the spoken lines, and is indicated by placing 2 carets (^^) in succession.

Speakers
The Speaker Block allows you to declare the name of the speaker once, and use a short-hand speaker ID in the spoken lines so that you don't have to re-type the name perfectly every time. The Speaker Block always precedes the spoken lines, and is separated from the lines by 3 carets in succession (^^^).

Each line of the Speaker Block consists of a unique ID for the speaker, followed by an equals sign, followed by the full text of the speaker. The speaker ID cannot consist of the newline character (which is used to separate individual speakers in the Speaker Block) or the equals sign (which is used to terminate the speaker ID). The full text of the speaker's name may be any character except a newline. You may include wiki formatting in the speaker's full name if you like.

The Sternograph will still strip any leading/trailing whitespace from the speaker's name. If there are duplicate speaker IDs in the Speaker Block, there is no guarantee which one will be used by the Sternograph.

You can also use the speaker's unique ID within angle brackets (&lt; and &gt;) in a spoken line or any type of stage direction, and the Sternograph will substitute the ID with the speaker's declared identifier. If you try to use a speaker ID that hasn't been declared in the speaker block, the Sternograph will not attempt to format it and will return what has been literally typed.

Installation

 * 1) Download the files from SVN or download a snapshot. Choose the version that matches your version of MediaWiki.
 * 2) Create a directory   in your   directory.
 * 3) Extract the files to this   directory.
 * 4) Add   to the bottom of LocalSettings.php.
 * 5) Copy the contents of Sternograph.css into your Common.css file.
 * 6) Installation can now be verified through Special:Version of your wiki.

Customising Your Sternograph
Because the formatting of a Sternograph is controlled via CSS, things such as font face and colour are controlled as any other CSS class on MediaWiki. Check the comments in the Sternograph.css to see which classes to change for a specific effect.

In all of the Sternograph examples above, you will notice the extension automatically applies a : (colon and non-breaking space) to the end of the speaker's name; and that in-line directions are automatically wrapped in [ and ] (square brackets). If these automatic additions are not appropriate for your language (or you just want to be different) you can change them by modifying the Sternograph.i18n.php file. The various -pre keys place text immediately before the item being modified and the -post keys append text immediately after the item being modified.

Version 1.1

 * Internationalisation keys corrected to current standard. (Thanks to Raymond and Platonides for keeping them in-line.)

Version 1.0

 * Added to MediaWiki's SVN repository.
 * Changed the delimeters to use ^ and _ to help with internationalisation.

Version 0.0

 * The internationalisation file is there, but the only language is English.