Module:Cite source/doc

Module:Cite source is the Lua module that forms the guts of {{cite source}}. You should aim to be familiar with Lua before editing it.

Broadly, the module is broken up into 2 major sections. The first is for formatting and storing information gathered from {{Infobox Story}}. The second is for acessing this information and producing citations. The main method used by this module for storing data is LuaCache with Semantic MediaWiki as a backup. Variables is used for caching queries on individual pages.

The module opens by importing other util libraries. Currently, these are named in snake_case for some reason but this may be changed to camelCase in future. PREFIX is a constant used by Lua Cache and Variables to name the data stores used by the module. In the case of something going seriously wrong, incriment the number in the prefix. This will reset all data stored by the module. The p table stores the functions returned by the module. These are accesible by the wider wiki. The h table stores the functions only used by other functions in this module.

Following this, there is a short function taken from Stack Overflow that inverts tables, swapping keys and values.

Generating and saving citations

The first major part of this module deals with gathering information from {{Infobox Story}}, formatting it into citations and saving it. The main functions here are p.infoboxStore and p.variantStore, the others being called from these 2. The general idea is that each of these 2 functions put together a table containing raw data from the infobox that is then processed by various helper functions to produce the output. These will now be discussed in more detail in the same order as in the module.

h.getAndFormatUnlinkedItems

This function deals with anything that is enterred into the infobox unlinked and comma-separated in the case of multiple entries. Namely, these are the source's anthology, writer, publisher, network and the source that it was adapted from. None of these will be aplicable to every source but they are all handled at the same time by this function.

The function takes as an argument the full table of infobox arguments. A data table is then created with blank entries for each piece of data handled by this function. The keys in this table must match the corresponding keys in the args table and hence the names of the parameters in {{Infobox Story}}.

The function then iterates through each entry in this data table and checks if there's a non-empty corresponding entry in the args table. This way, it processes only the entries in the data that actually have information in the infobox. The potentially comma-separated string passed to the infobox is then converted into a table. This occurs whever there are actually multiple values for infobox field or not. Either way, we get a table, even if it only has 1 entry.

If this table has more than 4 items, only the first will be assigned to the relevant entry in the data table, followed by "et al.". This phrase is wrapped in a span with the other values in the table placed in the span's title attribute, displaying them when "et al." is hovered over on desktop. Otherwise (in most cases), all values will be listed in the relevant data table entry. Each of these are linked with the display text set to the undabbed page name.

The data table is then returned. This table will be added to by subsequent functions before being converted into an output string.

h.getAndFormatIssuesText (unused)

Following this is an old unused function which formatted issues for comics. However, this information is not currently being displayed in finished citations and so it has been removed.

It worked very similarly to the above but without links (and without the whole "et al." thing when more than 4 items are given.

h.getAndFormatSeriesText

This function creates the bit of text stating the source's series. There are multiple places that this could come from in the infobox, none of which are ideal or one-size-fits-tall, which are dealt with here. Therefore, it takes the args table as an argument.

The simplest case is if citation series is specified. This is an overide field that allows the exact series to be used to be specified. No further formatting occurs here.

The slightly more complex fallback is if range is specified. In this case, the field is linked and that is used.

Failing this, series is used. This infobox field is primarily used for navigation and so is unideal but is often the best that we have. The overrides (not variable is a data module, Module:Cite source/series overrides, that holds common overrides that should be applied automatically. For example, "[[Doctor Who television stories|''Doctor Who'' television stories]]" is very commonly given in the series infobox field and this data module contains a rule to automatically convert this to "''[[Doctor Who]]''". If an override does exist, it is used. Otherwise, the raw text passed to series is used. series is a freeform variable which should already have links and hence no additional formatting is applied. Finally, the season number entry in the args table is checked and, if this exists, the season/series is added to the end of the series text.

The series text produced is this return. Note that, if no series is specified anywhere, this may be blank and this is fine.

h.getReleaseYearText

This function formats the release year presented in the infobox. This should be presented unlinked in accordance with {{date link}} and hence a lot of formatting must be done here.

Firstly, all date fields from the infobox are combined, using the first non-empty field in the following list:

• release date
• broadcast date
• premiere
• beta release date
• cover date

These fields are run through util_link.stripDab in order to remove parenthetical notes and are then split on "-" in order to separate the start and end release dates of serialised sources, these 2 dates being placed in a table.

If this table has 2 or more entries, it can be assumed that there is both a release date and a release end date. These are extracted and assigned to their respective variables. :gsub("%s+", "") strips any whitespace while :sub(-4) extracts the final 4 characters of the date which should be the year. One simple way to check is to see if the string contained the year can be converted into a number. This is done and, if it can't, the dates are readjusted accordingly.

If the table only has 1 entry, the source only has a single release date and the same process as above occurs on this, without the check to see if the year is a number.

The release date(s) are then formatted with links added and the resulting string is returned.

h.makeOutput

This is a key function in this half of the module which combines all of the processed data from all previous functions into a cohesive string of text. It takes as arguments a data table containing all of the processed data produced by the previous functions and an args table containg the raw arguments from the infobox.

If data["writer"] is non-empty, this is added to the output. A check is then made to see if data["adapted from"] is non-empty. If it is, this to is added to the output. Moreover, a SMW query is used to check if the source from which the current source was adapted from has a writer. If it does, this added to the output in brackets. If there was no writer, this bit is skipped and only the "adapted from" information is added to the output.

The remaining data is then formatted so that most of it is placed in brackets with the first piece of data outside of the brackets. For example, "Doctor Who season 1 (BBC tv, 1963-1964)". To achieve this, all possible pieces of data are looped through and, if they exist, they are added to a table called loopData. It is at this stage that italics are added to the source's anthology, if it was published within one. The remainder of the output is then built up through a series of if statements.

Following this, if the outputText variable is, for whatever reason, blank, it is set to an error message. Otherwise, a full stop is added. outputText is then returned.

h.storeText

This little function deals with storing the output of this half of the module. The first line stores it to Extension:Variables. The next line deletes any previous text for this source stored in Extension:LuaCache and the line following this stores the up to date output to LuaCache. The final line stores the output to Extension:Semantic MediaWiki in Property:Story info.

This function returns nothing.

p.infoboxStore

This function is the main way in which all of those discussed so far will be called. It is integrated into {{Infobox Story SMW}} and will execute on any pages with this infobox. It is responsible for combining all prior functions to take all of the arguments from the infobox and process them into a cohesive string of text which is then stored.

It takes as an argument the frame object. If you are unsure what this is, have a look at this blog post. The arguments passed to the infobox are then extracted and assigned to the args table. The next line takes the first unamed argument passed to the module when it is invoked in the template. This is not the first argument passed to the infobox, rather something hardcoded and passed into the module directly by the template. This first unamed argument will be {{PAGENAME}}, a magic word that evaluates to the name of the page that the infobox is used on.

more technical documentation to be added

visit Module:Cite_source/doc to edit this page