View source for Library:Style guide

Articles on [[Oddworld Library]] follow certain conventions in how they are edited. This <b>style guide</b> addresses some of the most common situations that may arise, but may be updated at any time. Advice in this guide can also be disussed using this article's talk page.

== Terminology ==
In this guide, and in other articles referring to the editing of Oddworld Library, the following terminology should be used carefully to avoid ambiguity. 

; mention
: Refers to any term being <em>used</em> in prose, tables and citations, as well as when the term is itself <em>mentioned</em> in the linguistic sense. For example, game titles are <strong>mentioned</strong> in an article.
; citation
: Refers exclusively to the use of academic-style references that use MediaWiki's <code>ref</code> and <code>references</code> markup. It does not refer to a work being mentioned in text, even though such mentions should be marked up with the <code>cite</code> element.
; reference
: Refers to the relationship between a term and its definition, or between an article and its topic, and not to academic-style references (which are ‘citations’).
; allusion
: Refers to the relationship between the content of a work and the content of another work. For example, when a character describes the events of a previous story, this is an allusion and not a reference as it's often called on other wikis.
; quotation
: Refers to any text that is copied or transcribed from another source, and is therefore not bound by the above terminology. Quotations should ideally be left unedited, but when used in context (in service of surrounding prose) should be edited for clarity and succinctness. Quotations also refer to samples of code and mentions of article titles.
; replication
: Refers to a kind of quotation that isn't used in the context of surrounding prose, and isn't edited for clarity or succictness, but is copied in full. The best current example of this are the tweets replicated in the [[Oddworld: The Lost Archives|Lost Archives]] table. Compare them with tweets as quoted within prose or citations.

A reminder that these terms as defined only apply when talking <em>about editing</em> the Library, and aren't intended to be definitions for use in regular articles or outside the Library.

== Typography ==
=== Apostrophes ===
In ordinary text, apostrophes should use the Unicode character <kbd>U+0027 Apostrophe</kbd>, which can be entered using a typical keyboard. This includes apostrophes that occur at the front of an abbreviation, such as '97 for the year 1997, and the game title <cite>New 'n' Tasty</cite>.

Oddworld Library previously advised that apostrophes should use the Unicode character <kbd>U+2019 Right Single Quotation Mark</kbd>, and so instances of this may be found when editing existing articles. Please correct these instances.

The justification for this change in policy is about the ease of editing articles. It therefore should be the job of Oddworld Library's font to correctly render apostrophes as curved marks identical to the closing quote mark, and not the job of editors to manually correct for old computing limitations.

Note that the Unicode character <kbd>U+0027 Apostrophe</kbd> should not be used for quotation marks, except in quotations of code or user-generated content.

=== Quotations ===
Inline quotations should be enclosed within single quoation marks <kbd>U+2018 Left Single Quotation Mark</kbd> and <kbd>U+2019 Right Single Quotation Mark</kbd> (‘ and ’). On Windows, these can be quickly entered using a keyboard by <kbd>holding the <kbd>Alt</kbd> key and pressing <kbd>0</kbd><kbd>1</kbd><kbd>4</kbd><kbd>5</kbd> and <kbd>0</kbd><kbd>1</kbd><kbd>4</kbd><kbd>6</kbd> respectively on the numerical pad</kbd>.

Only when an inline quotation exists <em>inside</em> another inline quotation should they be enclosed within double quotation marks <kbd>U+201C Left Double Quotation Mark</kbd> and <kbd>U+201D Right Double Quotation Mark</kbd> (“ and ”). On Windows, these can be quickly entered using a keyboard by <kbd>holding the <kbd>Alt</kbd> key and pressing <kbd>0</kbd><kbd>1</kbd><kbd>4</kbd><kbd>7</kbd> and <kbd>0</kbd><kbd>1</kbd><kbd>4</kbd><kbd>8</kbd> respectively on the numerical pad</kbd>. This also applies to quote marks quoted inside a quoted or mentioned title of a press article. For example, when refering to the fictional article ‘Why allegory in “Oddworld” is empowering’, double quote marks are used even though they are only single quote marks in the original source.

The Unicode character <kbd>U+0022 Quotation Mark</kbd> should only be used in samples of code or when quoting user-generated content (e.g. tweets, forum thread titles). Quoting from written articles should upgrade quotation marks per the above rules.

=== Ellipses ===
When 3 full stops are used in a row, it's called an ellipsis. These should be copied exactly when quoting code or user-generated content, but in most circumstances should be replaced with the Unicode character <kbd>U+2026 Horizontal Ellipsis</kbd> (…).

== Markup ==
=== Titles ===
Titles of creative works that are typically rendered in italics should be marked up with the HTML <code>cite</code> element, and not with wiki markup for italic text. Other titles that usually go inside quotation marks should follow the rules of quotations above. See the [[#Titles]] section below for more clarity on which to use when.

=== Keywords ===
Article keywords (such as the subject of the article) should be marked up with the HTML <code>b</code> element, <em>and</em> where relevant with the HTML <code>dfn</code> element, and not the wiki markup for bold text. While the wiki markup is likely compliant with HTML5 semantic markup, it makes it harder to port articles into and out of MediaWiki.

=== Quotations ===
Inline quotations should be marked up with the HTML <code>q</code> element, which should be placed inside any quotation marks. This goes against the HTML5 specification, which advises that quotation marks should be rendered by CSS. However, because punctuation is content, and content should not be defined by CSS, Oddworld Library deviates from the specification.

Samples of code and mentions of article titles are not marked up as quotations. Blocks of quotation are marked up with the HTML <code>blockquote</code> element.

Where computer input and output is being quoted or mentioned, do not use the HTML <code>q</code> element, but <em>do</em> use the HTML elements <code>code</code>, <code>kbd</code> and <code>samp</code> per the HTML5 specification.

=== Date and time ===
All dates, times and durations should be marked up using the HTML <code>time</code> element, unless it cannot be converted into a valid <code>datetime</code> value per the HTML5 specification. This includes quotations of <em>all</em> types. The full date and time should be marked up with the HTML <code>time</code> element, including the day of the week, any prepositions or conjunctions between the date and the time, and the timezone.

Unless the content of the <code>time</code> element is itself a valid <code>datetime</code> value, the <code>datetime</code> attribute of each <code>time</code> element will need to be included in almost all cases. The only likely exception would be a year mentioned with no finer detail (or at least no finer detail that can be turned into a valid <code>datetime</code> value), because the 4-digit year by itself is a valid <code>datetime</code> value.

Because the <code>datetime</code> attribute is limited in the values it can accept, per the HTML5 specification, it is strongly preferable to exclude the HTML <code>time</code> element altogether for invalid times rather than leave a <code>time</code> element with no valid <code>datetime</code>.

Invalid times, which are those for which the <code>datetime</code> attribute cannot be set with a valid value (and therefore for which the <code>time</code> element should be excluded), include the following.
* Times before the Common Era, i.e. any year that is <abbr title="Before Christ">BC</abbr> or <abbr title="Before Common Era">BCE</abbr>
* Times that are specified by a calendar other than the Gregorian calendar (including any fictional calendar, although fictional events that supposedly take place during a real time in the Gregorian calendar <em>can</em> be given a valid datetime, as can durations specified in hours or minutes, but not days)
* Time periods, which for this article are defined as having either a known a start point, a known end point, or both

The <code>datetime</code> value should be as specific as possible. For instance, when the year is known by being established earlier in the text, but is excluded from the specific date to avoid unnecessary repetition, the year should still be included in the <code>datetime</code> value, and not left as a ‘floating’ date value. This is also true where the date of an event is given to the day or month in prose, even though the source may list the time in greater detail: in this case, use the full <code>datetime</code> from the source. Such precise times can often be worked out from the page's <abbr title="uniform resource identifier">URI</abbr> or source code.

==== Time periods ====
A valid <code>datetime</code> value cannot describe a time period (as defined in the bullets above), so when these are mentioned by the text, the start and end point will have to be marked up separately. For example, ‘<code><nowiki>between <time datetime="06-10">10</time> and <time datetime="06-20">20 June</time></nowiki></code>’. In these cases, prepositions and conjunctions connecting the start and end dates should not included inside the <code>time</code> element.

Sometimes the start or end point of an ‘open’ time period, which has only a single known start or end point, may need to be marked up in multiple levels of specificity. For example, ‘<code><nowiki>some time on <time datetime="05-08">8 May</time> before <time datetime="05-08T12:00">midday</time></nowiki></code>’.

This method does not work for time periods where the start and end point are not mentioned explicitly or with separate words, e.g.
* Summer 2015
* Tuesday afternoon
* during development of <cite>Oddworld: Soulstorm</cite>

In these cases, only use the HTML <code>time</code> element to mark up any <em>part</em> of the time that is in itself valid, such as ‘2015’ in the first bullet above, or ‘Tuesday’ in the second bullet <em>if</em> the particular Tuesday is a known specific date.

== Text ==
=== Titles ===
This section refers to titles of works referenced by the text, and not to the titles of pages or sections on Oddworld Library, which are referred to as ‘headings’.

==== Abbreviations ====
The first mention of each title in an article should be written in full, including the ‘Oddworld:’ prefix. Thereafter, mentions in prose can be abbreviated to exclude the ‘Oddworld:’ prefix only. When the title has not been mentioned for a significant period, the full title should again be used.

When the title is mentioned in isolation in a table or list item, it should always be in full. When it is used in prose in the table or article, it may be abbreviated per the above rule.

Abbreviations such as <cite><abbr title="Stranger’s Wrath HD">Stranger HD</abbr></cite> for <cite>Stranger’s Wrath HD</cite> or <cite><abbr title="Abe’s Oddysee">AO</abbr></cite> for <cite>Abe’s Oddysee</cite> should not be used, though when they appear in quotes they should still be marked up with the <code>cite</code> element, and if appropriate, the <code>abbr</code> element for clarity.

Where a title includes a subtitle, such as <cite>The Art of Oddworld Inhabitants: The First Ten Years 1994–2004</cite>, the full title is appropriate in keywords and citations, but not in prose or tables, where <cite>The Art of Oddworld Inhabitants</cite> will suffice.

==== Arthrousness ====
A title is <dfn>arthrous</dfn> if it includes the word ‘the’ at the start.

Most arthrous Oddworld titles are <dfn>softly arthrous</dfn>, meaning the ‘the’ is not capitalized unless it appears at the start of a sentence or list item (or unless it is quoted in that way, including in store listings).

Some arthrous titles are <dnf>strongly arthrous</dnf>, meaning the ‘The’ is always capitalized (unless it is quoted otherwise).

Wherever the ‘the’ is capitalized, regardless of whether it should or should not be, it should be included in the HTML <code>cite</code> element and, if appropriate, linked text.

If arthrous titles are used as an adjectival phrase (e.g. ‘Is this game an <cite>Oddworld Quintology</cite> story?’), the ‘the’ should be excluded, even if it is a strongly arthrous title.

Arthrous Oddworld titles include
* <cite>The OddBoxx</cite>
* <cite>The AbeBoxx</cite>
* <cite>The StrangerBoxx</cite>
* <cite>The Oddworld Quintology</cite>
* <cite>The Movies of Oddworld</cite>
* <cite>The Music of Oddworld Stranger's Wrath</cite>
* <cite>The Art of Oddworld Inhabitants</cite>
* <cite>The Hand of Odd</cite>

=== Case ===
The <cite>OddBoxx</cite>, the <cite>AbeBoxx</cite>, the <cite>StrangerBoxx</cite> and <cite>SligStorm</cite> are UpperCamelCase (unless quoted otherwise). <cite>Oddworld: Soulstorm</cite> is not CamelCase, unlike the proposed title for <cite>Abe's Oddysee</cite>, <cite>SoulStorm</cite>, as well as unlike the in-universe product, SoulStorm Brew, which are both UpperCamelCase.

=== Demarkation ===
Italics (marked up using the <code>cite</code> element) are used for
* book titles
* game titles
* film titles
* album titles
* names of television series and serials
* names of media franchises and series
* names of newspapers and journals

Quotation marks are used for
* names of levels
* article and chapter titles
* video titles
* song titles

== Date and time ==
=== Date ===
Dates in text should be written in the following format, with each part separated by the Unicode character <kbd>U+0020 Space</kbd> ‘ ’.
# Only if it is relevant, the full name of the day of the week
# Date of the month in numbers, with no leading zero and no ordinal suffix
# Full name of the month
# Year in numbers, with no notation (e.g. ‘<abbr title="Before Common Era">BCE</abbr>’) unless necessary to avoid ambiguity; the year should be 4 digits precisely unless referring to years prior to 9999 <abbr title="Before Common Era">BCE</abbr>, between 999 <abbr title="Before Common Era">BCE</abbr> and <time datetime="0999">999 <abbr title="Common Era">CE</abbr></time>, or after <time datetime="9999">9999 <abbr title="Common Era">CE</abbr></time>.

For example, <time datetime="2021-05-30">Sunday 30 May 2021</time>. 

=== Time ===
Times in text should be written in the following format.
# Hour in 12-hour format with no leading zero
# Unicode character <kbd>U+002E Full Stop</kbd> ‘.’, which on Windows can quickly entered using a keyboard by <kbd>holding the <kbd>Alt</kbd> key and pressing <kbd>2</kbd><kbd>5</kbd><kbd>0</kbd>
# Minute with leading zero
# Unicode character <kbd>U+0020 Space</kbd>
# Either ‘a.m.’ or ‘p.m.’, or when the time is 12.00 (even if the seconds are included in the HTML <code>time</code> element) ‘noon’ or ‘midnight’ to avoid ambiguity
# Where the timezone is known and relevant, Unicode character <kbd>U+0020 Space</kbd> followed by the English-language abbreviation of the timezone with no full stops (e.g. <abbr title="Greenwich Mean Time">GMT</abbr>, <abbr title="Australian Eastern Daylight Saving Time">AEDT</abbr>), which should be enclosed with the HTML <code>abbr</code> element

For example, <time datetime="14:41-08:00">2.41 p.m. <abbr title="Pacific Time">PT</abbr></time>

When combining the date and the time in text, they should be separated by a preposition, usually ‘at’.

<time datetime="2019-07-08T06:18Z">8 July 2019 at 6.18 a.m. <abbr title="Universal Coordinated Time">UTC</abbr></time>

When combining the date and the time in tables or citations, they should be separated by the Unicode character <kbd>U+0020 Space</kbd> ‘ ’.

== Tables ==
Tables are constructed using MediaWiki markup. The following style rules should, however, be observed.

=== Sorting ===
When sorting by people's names, the <code>data-sort-value</code> should be defined so that their names are ordered by surname first.

<code><nowiki>| data-sort-value="Lanning, Lorne" | Lorne Lanning</nowiki></code>

When sorting by dates, the above guide on writing dates works when the <code>date-sort-type</code> is defined as <code>date</code> in the table header.

<code><nowiki>! data-sort-type="date" | Date</nowiki></code>

=== Alignment ===
Different types of columns should be aligned in different ways. Columns with ‘short’ data should be centre-aligned.
* Date
* Name of a person
* Titles from a small selection of possibilities, e.g. Oddworld titles

Columns with ‘long’ or variable-length data should be left-aligned.
* Quotes
* Titles that might be long, e.g. press article titles

Unfortunately, alignment cannot be set per column using MediaWiki markup. Instead, one type of alignment must be specified for the overall table, and any cell that should have a different alignment needs to specified per individual cell.

==== Numbers ====
Columns with numbers should be right-aligned with respect to the numbers, but center-aligned with respect to the column. This can be acheived by setting the column alignment to central, but making sure to pad the left of lower-digit numbers with Unicode character <kbd>U+2007 Figure Space</kbd>.

 <nowiki>| style="text-align: center;" | &amp;#8199;32</nowiki>
 <nowiki>|-</nowiki>
 <nowiki>| style="text-align: center;" | &amp;#8199;&amp;#8199;8</nowiki>
 <nowiki>|-</nowiki>
 <nowiki>| style="text-align: center;" | 102</nowiki>

The above code snippet generates the table below.

{| class="wikitable"
|-
! Numbers that are centre-aligned but also right-aligned
|-
| style="text-align: center;" | &#8199;32
|-
| style="text-align: center;" | &#8199;&#8199;8
|-
| style="text-align: center;" | 102
|}

== Citations ==
Citations use MediaWiki's templates, for which the documentation may describe them as ‘references’ or ‘footnotes’. Oddworld Library refers to them almost exclusively as ‘citations’ for clarity, although the same templates may be used to create other types of footnote if appropriate.

=== Markup ===
Citations in text and tables should always be written using the name only.

<code><nowiki>Citations in text and tables should always be written using the name only.<ref name="Only use ref names"/></nowiki></code>

Full citations should be collected together in the citation list, both in the markup and in the wiki page. The following should therefore be placed below most other content of any page, with the exception of any categories the page belongs to.

 <nowiki>== Citations ==</nowiki>
 <nowiki><references></nowiki>
 <nowiki><ref name="Only use ref names">Text of the full citation goes here</ref></nowiki>
 <nowiki></references></nowiki>
 <nowiki></nowiki>
 <nowiki>[[Category:Goes after the citation list]]</nowiki>

In very long articles, it may be appropriate to have multiple citation lists throughout the page, so that each list is short and refers to a manageable subsection of the page. On MediaWiki, each time a citation list is created, it voids any connection to the citations above it: Any citations in the list cannot be used in the text below, and the next citation will be numbered ‘1’ again. This may cause confusion when users look at the numerical inline citation, so in general avoid this method unless each subsection of the page will have its own unique set of citations.

=== Names ===
Names of citations are used as anchors in the page, so keep them short but unambiguous, and don't change them unless for a significant improvement.

=== Text ===
The full text of a citation as it appears in the citation list follows a well-defined pattern, which is based off of the Harvard style of citation.
# Name of the author or host
# Date of publication in brackets
# Title of the screen or section, usually in quotation marks
# Title of the level, chapter, or article, usually in quotation marks
# Title of the game, book, or publication, usually in italics using the <code>cite</code> element
# Title of the platform
# Title of the publisher
# Archival information

The author and date, including the brackets but excluding the full stop, should be marked up with HTML <code>b</code> elements.

==== Author ====
This name is written with the surname first, then a comma, then the first name, similar to how it would be written in the <code>data-sort-value</code> of a table. If an author is not known, use the publication name. The author of a game is the developer, not the character that a quote might come from. The author of an interview is the interviewer, unless it is particularly important to attribute the citation to the interviewee.

==== Date ====
The time is only included when multiple citations are in close proximity, such as rapid forum or chat room conversations. The date (and time if included) goes within brackets. The <code>time</code> element goes around the time, but stays inside the brakcets.

If the exact date is not known, prefix the date with ‘c. ’, but do not mark this up with the <code>time</code> element. If a date cannot be approximated, use only the month and year, or in extreme cases, only the year.

The brackets that go around the date are immediately followed by the Unicode character <kbd>U+002E Full Stop</kbd>.

==== Titles ====
Following the normal rules of how titles should be formatted, the titles that are cited are listed in order from specific to general, separated by the Unicode character <kbd>U+002E Full Stop</kbd>. Some examples include

* ‘SpooceShrub Forest’. <cite>Oddworld: Munch's Oddysee</cite>.
* ‘The Next Oddysee’. ‘Weathering the Soulstorm’. <cite>MCV/Developer</cite> 967 April 2021.
* ‘New ‘n’ Tasty boxart revealed’. OddBlog. Oddworld Library.

Non-title ancilliary information such as page number should be connected to the most appropriate title.

* ‘Weathering the Soulstorm’. Pages 12–18, <cite>MCV/Develop</cite> 967 April 2021.
* Post 56 in ‘The End of OWF’. Forum Suggestion & Help. Oddworld Forums.

==== Platform ====
Platform will usually only be relevant to video games, although the broadcast channel or streaming service of a film may also be included here.

==== Publisher ====
Book and magazine publishers should be preceded by the city and country they are based in.

* Adelaide: Ballistic Publishing.
* London: Biz Media.