Extension:Sternograph

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
Sternograph
Release status: unmaintained
Implementation Tag
Description Format spoken exchanges
Author(s) Smoke3723talk
Latest version 1.1 (2011-10-30)
MediaWiki 1.17+
PHP 5
Database changes No
License GPLv2
Download Template:WikimediaDownload/svn
CHANGELOG
Tags
<sterno>
Hooks used
ParserFirstCallInit
Translate the Sternograph extension if it is available at translatewiki.net
Check usage and version matrix.

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

Introduction[edit]

Currently on MediaWiki, if one wishes to provide an in-text quote one uses the <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:

  • 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:

Stephen: That's with a P-H.
Steven: That's with a V. Am I the same person?

  • 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[edit]

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[edit]

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:

<sterno>
Duke=What, is Antonio here?^
Antonio=Ready, so please your Grace.^
Duke=I am sorry for thee: thou art come to answer<br/>A stony adversary, an inhuman wretch
</sterno>

Duke: What, is Antonio here?
Antonio: Ready, so please your Grace.
Duke: I am sorry for thee: thou art come to answer
A stony adversary, an inhuman wretch

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[edit]

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:

<sterno>
Enter NERISSA, dressed like a lawyer's clerk.
^
Duke=Came you from Padua, from Bellario?^
Nerissa=From both, my lord.  Bellario greets your Grace.
_Presents a letter_^
</sterno>

Enter NERISSA, dressed like a lawyer's clerk.
Duke: Came you from Padua, from Bellario?
Nerissa: From both, my lord. Bellario greets your Grace. [Presents a letter]

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[edit]

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.

<sterno>
Portia=The quality of mercy is not strain'd,<br/>It droppeth as the gentle rain from heaven
^^
[http://www.bartleby.com/70/1941.html The Merchant of Venice]
Act IV Scene i lines 180-182
</sterno>

Portia: The quality of mercy is not strain'd,
It droppeth as the gentle rain from heaven

The Merchant of Venice Act IV Scene i lines 180-182

Speakers[edit]

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 (^^^).

<sterno>
Por=Portia
Ant=Antonio
^^^
Por=Of a strange nature is the suit you follow;<br/>
Yet in such rule that the Venetian law<br/>
Cannot impugn you as you do proceed.<br/>
_To <Ant>_You stand within his danger, do you not?^
Ant=Ay, so he says.^
Por=Do you confess the bond?^
Ant=I do.
</sterno>

Portia: Of a strange nature is the suit you follow;
Yet in such rule that the Venetian law
Cannot impugn you as you do proceed.
[To Antonio] You stand within his danger, do you not?
Antonio: Ay, so he says.
Portia: Do you confess the bond?
Antonio: I do.

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 (< and >) 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[edit]

  1. Download the files from SVN or download a snapshot. Choose the version that matches your version of MediaWiki.
  2. Create a directory Sternograph in your $IP/extensions directory.
  3. Extract the files to this $IP/extensions/Sternograph directory.
  4. Add
    require_once( "$IP/extensions/Sternograph/Sternograph.php" );
    
    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[edit]

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.

Internationalisation KeyModifier
sternograph-speaker-prePrepends text before the name of every speaker in a Speaker Name; this is empty by default.
sternograph-speaker-postAppends text after the name of every speaker in a Speaker Name; this is a colon and space by default.
sternograph-block-prePrepends text before every block direction; this is empty by default.
sternograph-block-postAppends text after every block direction; this is empty by default.
sternograph-inline-prePrepends text before every in-line direction; this is a square bracket by default.
sternograph-inline-postAppends text after every in-line direction; this is a square bracket by default.
sternograph-context-prePrepends text before the context section; this is a dash by default.
sternograph-context-postAppends text after the context section; this is empty by default.

Release Notes[edit]

Version 1.1[edit]

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

Version 1.0[edit]

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

Version 0.0[edit]

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