This function attempts to apply appropriate formatting to unformatted ship names. The formats supported are:
fix> <name> <(disambiguator)> where:
#*<prefix> – one from a list of defined prefixes commonly used for ships (ARA, HMS, USS, etc.); rendered in upright font
#*<name> – the ship's proper name; rendered in italic font
#*<(disambiguator)> (optional) – typically the ship's [[hull number|hull]] or [[pennant number]], or other disambiguator; always contained in parentheses; rendered in upright font
#<name> <(disambiguator)> where:
#*<name> – the ship's proper name; rendered in italic font
#*<(disambiguator)> (required) – the ship's [[hull number|hull]] or [[pennant number]] or a recognized ship-type descriptor; always contained in parentheses; rendered in upright font
#**hull and pennant numbers take two basic forms
#***uppercase letters, possibly followed by a space or hyphen, followed by digits (SSBN-659, R07, ON 688)
#***digits, possibly followed by a space or hyphen, followed by uppercase letters (401B)
#<nationality> <ship type> <name> <(disambiguator)> where:
#*<nationality> – one- or two- word nation name in adjectival form (Dutch, East Timorese, French, Ottoman, etc.); rendered in upright font
#*<ship type> – one from a list of one- to four-word phrases that describes a ship's type ([[aviso]], [[brig sloop]], [[landing ship medium]], [[ship of the line]]); rendered in upright font
#*<name> – the ship's proper name; rendered in italic font
#*<(disambiguator)> (optional) – typically the ship's hull or pennant number, or other disambiguator; always contained in parentheses; rendered in upright font
The function will also attempt to render ship-class names when the name is in the form:
*<name>-class <ship type> where:
**<name> – the class' proper name; rendered in italic font according to the setting of {{para|sclass}}
**<ship type> – a phrase that describes a ship's type; rendered in upright font
===Lists===
The function relies on three lists to accomplish its task. These lists are:
#<code>ship_prefix_list</code> – a list of commonly used ship prefixes initially taken from {{tlx|ship prefix}}; these are usually, but not always wholly uppercase
#<code>nationality_list</code> – a list of nation names in their adjectival form; these are always capitalized; always one or two words
#<code>ship_type_list</code> – a list ship-type descriptor phrases; these are usually, but not always wholly lowercase; always one to two words
To add to any of these lists, the form is:
:<code><nowiki>['</nowiki>''addition''<nowiki>'] = true,</nowiki></code>
the trailing comma is important. See the instructions that accompany each list for limitations and implementation details.
===Usage===
The minimal form is:
:<code><nowiki>{{#invoke:WPSHIPS_utilities|ship_name_format|name=}}</nowiki></code>
====Parameters====
The function requires one parameter and supports several optional parameters.
:'''|name=''' – (required) the name to format
:'''|dab=none''' – for use with {{para|infobox caption|nodab}} in {{tlx|infobox ship begin}}, excludes a disambiguator from the formatted name
:'''|sclass=2''' – for use with <code><nowiki>{{</nowiki>DISPLAYTITLE}}</code> and with {{para|infobox caption|yes}} or {{para|infobox caption|nodab}} in {{tld|infobox ship begin}}, when the class is not named for a member of the class; causes the class name to be rendered in upright font
:'''|adj=off''' – for use in ship-class articles with {{para|infobox caption|yes}} or {{para|infobox caption|nodab}} in {{tld|infobox ship begin}}, formats the class name in its noun form and excludes the ship type phrase and disambiguator
:'''|showerrs=yes''' – debug tool; not currently supported in any templates;
====Wrapper template====
* {{tl|Ship name format}} is a wrapper template to make it easier for editors to label ships in the main body of articles or as ''input'' to templates or modules. It supports the same parameters as the module.
* In most cases, {{tl|ship}} is preferred over using this wrapper template or this module.
* It is useful to set the DISPLAYTITLE of redirects, disambiguation pages, or other pages named after ships which do not use one of the other "ships" templates such as {{tl|Infobox ship begin}} to do this. Example: <code><nowiki>{{DISPLAYTITLE:{{ship_name_format|name={{FULLPAGENAME}}}}}}</nowiki></code>
* Other templates and modules should not transclude this template, instead they should call the module directly.
* Wikipedia pages should not transclude this template many times, as it may cause the page to exceed Wikipedia's [[Wikipedia:Template limits|template limits]]. Those pages should invoke the module directly.
==wpsu.navsource==
This function is the driver for {{tlx|navsource}}. The function assembles an external wikilink from known fragments and positional parameter <code><nowiki>{{{1}}}</nowiki></code>. A ship name provided in positional parameter <code><nowiki>{{{2}}}</nowiki></code> is formatted using <code>ship_name_format</code>. New with this implementation of {{tld|navsource}} is the addition of {{para|showerrs}}. The <code><nowiki>{{#invoke:}}</nowiki></code> in the template defaults to {{para|showerrs|yes}} which can be overridden by setting {{para|showerrs|no}} in the template.
==wpsu.hnsa==
Similar to {{tlx|navsource}}, this code supports {{tlx|hnsa}} by attempting to construct a link to a ship article at the Historic Naval Ships Association website.
The template has the form:
:<code><nowiki>{{hnsa|<page>|<name>}}</nowiki></code>
where:
:<page> is the name of the page from the url <code><nowiki>http://hnsa.org/hnsa-ships/<page></nowiki></code>
:<name> (optional) is the name of the ship; if left blank, the template uses the current page title; if a ship name, it is formatted using <code>do_ship_name_format</code>
from which this code produces:
:<code><nowiki>[http://hnsa.org/hnsa-ships/<page> <name>] at Historic Naval Ships Association</nowiki></code>
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->
}}</includeonly>