Library:Style guide

From Oddworld Library
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Articles on Oddworld Library follow certain conventions in how they are edited. This style guide 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 used in prose, tables and citations, as well as when the term is itself mentioned in the linguistic sense. For example, game titles are mentioned in an article.
citation
Refers exclusively to the use of academic-style references that use MediaWiki's ref and references markup. It does not refer to a work being mentioned in text, even though such mentions should be marked up with the cite 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 Lost Archives table. Compare them with tweets as quoted within prose or citations.

A reminder that these terms as defined only apply when talking about editing 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 U+0027 Apostrophe, 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 New 'n' Tasty.

Oddworld Library previously advised that apostrophes should use the Unicode character U+2019 Right Single Quotation Mark, 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 U+0027 Apostrophe 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 U+2018 Left Single Quotation Mark and U+2019 Right Single Quotation Mark (‘ and ’). On Windows, these can be quickly entered using a keyboard by holding the Alt key and pressing 0145 and 0146 respectively on the numerical pad.

Only when an inline quotation exists inside another inline quotation should they be enclosed within double quotation marks U+201C Left Double Quotation Mark and U+201D Right Double Quotation Mark (“ and ”). On Windows, these can be quickly entered using a keyboard by holding the Alt key and pressing 0147 and 0148 respectively on the numerical pad. 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 U+0022 Quotation Mark 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 U+2026 Horizontal Ellipsis (…).

Markup

Titles

Titles of creative works that are typically rendered in italics should be marked up with the HTML cite 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 b element, and where relevant with the HTML dfn 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 q 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 blockquote element.

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

Date and time

All dates, times and durations should be marked up using the HTML time element, unless it cannot be converted into a valid datetime value per the HTML5 specification. This includes quotations of all types. The full date and time should be marked up with the HTML time 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 time element is itself a valid datetime value, the datetime attribute of each time 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 datetime value), because the 4-digit year by itself is a valid datetime value.

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

Invalid times, which are those for which the datetime attribute cannot be set with a valid value (and therefore for which the time element should be excluded), include the following.

  • Times before the Common Era, i.e. any year that is BC or BCE
  • 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 can 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 datetime 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 datetime 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 datetime from the source. Such precise times can often be worked out from the page's URI or source code.

Time periods

A valid datetime 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, ‘between <time datetime="06-10">10</time> and <time datetime="06-20">20 June</time>’. In these cases, prepositions and conjunctions connecting the start and end dates should not included inside the time 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, ‘some time on <time datetime="05-08">8 May</time> before <time datetime="05-08T12:00">midday</time>’.

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 Oddworld: Soulstorm

In these cases, only use the HTML time element to mark up any part of the time that is in itself valid, such as ‘2015’ in the first bullet above, or ‘Tuesday’ in the second bullet if 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 Stranger HD for Stranger’s Wrath HD or AO for Abe’s Oddysee should not be used, though when they appear in quotes they should still be marked up with the cite element, and if appropriate, the abbr element for clarity.

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

Arthrousness

A title is arthrous if it includes the word ‘the’ at the start.

Most arthrous Oddworld titles are softly arthrous, 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 cite element and, if appropriate, linked text.

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

Arthrous Oddworld titles include

  • The OddBoxx
  • The AbeBoxx
  • The StrangerBoxx
  • The Oddworld Quintology
  • The Movies of Oddworld
  • The Music of Oddworld Stranger's Wrath
  • The Art of Oddworld Inhabitants
  • The Hand of Odd

Case

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

Demarkation

Italics (marked up using the cite 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 U+0020 Space ‘ ’.

  1. Only if it is relevant, the full name of the day of the week
  2. Date of the month in numbers, with no leading zero and no ordinal suffix
  3. Full name of the month
  4. Year in numbers, with no notation (e.g. ‘BCE’) unless necessary to avoid ambiguity; the year should be 4 digits precisely unless referring to years prior to 9999 BCE, between 999 BCE and , or after .

For example, .

Time

Times in text should be written in the following format.

  1. Hour in 12-hour format with no leading zero
  2. Unicode character U+002E Full Stop ‘.’, which on Windows can quickly entered using a keyboard by holding the Alt key and pressing 250
  3. Minute with leading zero
  4. Unicode character U+0020 Space
  5. Either ‘a.m.’ or ‘p.m.’, or when the time is 12.00 (even if the seconds are included in the HTML time element) ‘noon’ or ‘midnight’ to avoid ambiguity
  6. Where the timezone is known and relevant, Unicode character U+0020 Space followed by the English-language abbreviation of the timezone with no full stops (e.g. GMT, AEDT), which should be enclosed with the HTML abbr element

For example,

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

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

Tables

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

Sorting

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

| data-sort-value="Lanning, Lorne" | Lorne Lanning

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

! data-sort-type="date" | Date

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 U+2007 Figure Space.

| style="text-align: center;" | &#8199;32
|-
| style="text-align: center;" | &#8199;&#8199;8
|-
| style="text-align: center;" | 102

The above code snippet generates the table below.

Numbers that are centre-aligned but also right-aligned
 32
  8
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.

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

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.

== Citations ==
<references>
<ref name="Only use ref names">Text of the full citation goes here</ref>
</references>

[[Category:Goes after the citation list]]

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.

  1. Name of the author or host
  2. Date of publication in brackets
  3. Title of the screen or section, usually in quotation marks
  4. Title of the level, chapter, or article, usually in quotation marks
  5. Title of the game, book, or publication, usually in italics using the cite element
  6. Title of the platform
  7. Title of the publisher
  8. Archival information

The author and date, including the brackets but excluding the full stop, should be marked up with HTML b 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 data-sort-value 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 time 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 time 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 U+002E Full Stop.

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 U+002E Full Stop. Some examples include

  • ‘SpooceShrub Forest’. Oddworld: Munch's Oddysee.
  • ‘The Next Oddysee’. ‘Weathering the Soulstorm’. MCV/Developer 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, MCV/Develop 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.