Module:Countries/North America/doc

This documentation is transcluded from Module:Countries/Africa/doc.

The countries and text displayed for a particular region are defined in a subpage of Module:Countries. For example, Module:Countries/Africa lists the countries in Africa and defines text such as "Countries of Africa" that is displayed if the user's language is en, and "Staaten in Afrika" if it is de. Country names are obtained from Wikidata.

Each section under titles defines text that depends on the current user's language. The procedures that apply to {{Fallback}} are used to determine which language should be used.

TODO: Standard titles should be defined in one module so they do not need to be duplicated for each countries submodule. Only items listed in each section are translated once from Wikidata labels. This may require adding also Wikidata entries for them (or locating existing Wikidata items for their topic), and being able to select their plural form when needed.

Module:Countries/Africa defines pattern twice. The first is a pattern for the text that is normally displayed by {{Countries of Africa}}, while the second applies when the parameter |simple=yes is used.

Each occurrence of {name} in the pattern is replaced with appropriate text. The names used for Africa when simple does not apply are:

You can specify patterns in various ways, the simplest one being a single string containing all the layout wikitext and {name} placeholders described above. This will only generate a static list with a single layout.

But you can also split the pattern into multiple "conditional supatterns" (all of them containing arbitrary wikitext or {name} placeholders), and put them in an ordered table, in the order in which they must appear on the result. This allows some fragments of the layout to be removed (for example dropping the section title if the list after it in the same section is empty, or dropping the static separators between sections).

Each "conditional subpattern" is represented either:

• as a simple string like 'subpattern with {name} placeholders' when there's no condition (this unconditional pattern will be always added to the result), or
• as an ordered table, where:
  • first element is a string for the subpattern, and
  • the other elements represent an union of several (non-exclusive) "conditions"

  for example, { 'subpattern with {name} placeholders', condition1, condition2, ... }

  (if any one of the listed conditions evaluates to true (OR), the conditional subpattern will be used).

Each "condition" listed in a array after the initial subpattern may itself be represented either:

• as a simple string for "simple conditions", or
• as an ordered table of "subconditions", i.e. a conjunction of several (non-exclusive) simple conditions

  for example, { 'subpattern with {name} placeholders', { subcondition1, subcondition2, ... }, ... }

  (if any one of the subconditions evaluates to false (AND), the conditional subpattern will NOT be used according to this condition, but may be used if other conditions part of the union allow it).

Each "simple condition" is used to evaluate tests based on names of variables (usable in placeholders of patterns or subpatterns). A simple condition is represented by a string and can currently take one the following forms:

• 'name'  : the simple condition is true if the variable with that name is non-empty (i.e. the subpattern {name} would be replaced by an actual text);
• '!name' : the simple condition is true if the variable with that name is empty (i.e. the subpattern {name} would be replaced by nothing);

The variable names used in simple conditions don't need to be present within the "conditional subpattern" string to which the condition applies (indicated at start of the table describing the conditional subpattern). This means for example that a subpattern continaining only static wikitext and no {name} placeholder, can be conditional. This is useful notably

• to generate static wikitext (for example breaks or punctuation or other presentational elements), that will be present in the result only if other conditional patterns actually generate text (depending on their own placeholders).
• to suppress every layout elements surrounding the inner content, when there's nothing useful to display: the result can then be entirely empty.

If the template that invokes the module has |simple=yes, the simple section is used.

• simple.pattern replaces pattern
• simple.sections specifies which sections from titles and lists will be processed.

In Module:Countries/Africa, simple.sections has

main = { EH = true, },

The fact that main is defined means that titles.main and lists.main will be used. The fact that other is not defined means that titles.other and lists.other will be ignored.

EH = true is used when simple does not apply. When the template is used normally (without |simple=yes), the country identified by EH is ignored. That is done because EH is included in the other section. However, with |simple=yes, EH will appear in the main section.

The simple version can also use a single pattern, or multiple conditional subpatterns like previously.

Each section under lists defines the list of country codes that will be used to display country names. Similarly to titles, the list depends on the current user's language.

Countries are listed in the order specified. If the default order is unsatisfactory for a particular language, an entry for the language can be added. The entry should include all the country codes in a suitable order.

For example, lists.main may include the following (... replaces some text omitted for simplicity).

main = {
    english   = 'automatic',
    default   = 'automatic sorted',
    en        = 'automatic sorted',
    mk        = 'DZ AO BJ BW BF BI CM CAVE CF TD KM CI ... SADR EH ZM ZW',
    automatic = 'DZ AO BJ BW BF BI CM CAVE CF TD KM CD ...   UG EH ZM ZW',
},

Each country code such as DZ is defined under countries. All lists should contain the same codes, only ordered differently depending on language; every localized list (keyed by language code) should then have exactly the same length as the one given for the 'automatic' list (which is required), or should be one of 'automatic sorted' or 'automatic'.

The following keys have special meaning when used before =.

The following values have special meaning when used after =.

A module is not able to properly collate names for a language other than en. However, Module:Countries can satisfactorily collates some names that use letters with diacritics which sort after their equivalent letters.

The collation (performed only when the option all is not set when calling the main function Module:Countries) is based on a function, defined in Module:MakeSortKey, creating sort keys from a translated label and the target language code (this language code could be later used to tailor the collation according to sorting rules for specific languages, but for now the sort order is locale-neutral). Generally, this sorting works for most languages, but the localisation may be needed to take into account ignorable prefixes, or for complex scripts that still have no support for a basic collation order.

Several examples from a countries table follow:

countries = {
    CI    = { 'Ivory Coast', "Côte d'Ivoire",  qid = 'Q1008', },
    DZ    = { 'Algeria',                       qid = 'Q262', },
    EG    = { 'Egypt',                         qid = 'Q79', mark = '‡', },
    GM    = { 'Gambia',                        qid = 'Q1005', the = true, },
    XBRTW = { 'Bir Tawil',                     qid = 'Q620634', },
}

CI, DZ, EG, and GM are country codes that identify a particular country. Where available, ISO 3166-2 codes are used, but any code can be used as they only have a meaning within the module (you should use a private extension, starting by "X", of ISO 3166-1 if the territory is part of another recognized country but has no ISO 3166-2 code, or use one of the prefixes reserved in ISO 3166-1 for private use, like "AA", "QM" to "QZ", "X", or "ZZ").

Note that Module:Countries is generic and is not restricted for listing only countries, it can process any list of up to 200 known items; the key defined as countries = {...} above can be alternatively named infos = {...} with the same content for list items.

The country names Algeria and Gambia are the titles of pages which should exist at Commons, and where the category page generally also exists. English names should be used but need to match names used in titles of titles in Commons. If several alternative names are used in Commons to refer to the same country in related page titles (such as "Côte d'Ivoire"), you may list these alternate names.

The qid codes identify the corresponding item at Wikidata. It allows translating the displayed label in the user's language (when option all is not set to render the box). For example,

• d:Q262 on Wikidata is associated to Algeria on Commons, and will also be used to get the translated label for other related pages like Category:Algeria
• d:Q1005 on Wikidata is associated to Gambia on Commons, and will also be used to get the translated label for other related pages like Category:Gambia

If the |all=yes option is not set to render the box, or if qid is not defined, or if qid is not found in Wikidata, or Wikidata does not define a label for it, then the first name listed in the data defining the country (normally in English and used in page titles in Commons) will be used as a default (untranslated) label.

Normally, a link is shown in the rendered bulleted lists only if the page exists.

But when rendering the list with |all=yes option, all possible page titles will be listed, without testing their existence, and without translating the displayed labels (this will frequently generate red links, but it allows the maintenance of page names on Commons, to find those that redirect to unexpected pages, or to facilitate the creation of missing pages with coherent titles that will be found and used when the |all=yes option will be removed to hide all possible aliases from the list and to get translated and sorted labels).

The entry for Gambia illustrates use of the optional the in country's data, whose effect is that the Gambia is tested for existence before Gambia: if a page exists in Commons using the in its title, this page will be selected as the target of the link.

The wikitext for each link has the following form:

[[PrefixTitleSuffix|<bdi>Label</bdi>]]

The entry for Egypt illustrates use of the optional mark in country's data, whose effect is that a superscripted mark will be added after the label. This is used as a note call, which will be rendered at bottom of the table. If you use such marks, you should create a conditional section (such as "partly") which lists all concerned codes (in arbitrary code order); this list will not be rendered, but will appear conditionally if any one of the listed codes is displayed from the other lists.

This list (currently maintained in Module:Convert/tester) is partial but contains the most frequently used modules. It autodetects differences between the normal modules and templates and their sandbox version, and list their associated testcases and talk pages (when they exist).

It also shows that the main module is not necessarily used for listing countries (or territories), it could be used as well to create navigation boxes for lists of cities, chemical elements, and so on, provided that these lists are bounded, wellknown and stable over years (and not overlong) : if a list contains more than 200 items, consider generated separate modules and navbox for sublists using some criteria). New data modules also don't necessarily have to be created and named as subpages of Module:Countries.

The sandbox versions of modules should be identical, except temporarily for testing changes (rendered with the sandbox template, in their comparative test cases)

For example, {{Countries of Africa/sandbox}} displays:

If the user's language is en, Module:Countries/Africa/sandbox could be edited and

en = 'Countries of Africa',

changed to

en = 'African countries',

Do not save the change. Instead, under "Preview page with this template" enter the title of this page

Module:Countries/Africa/doc

then click "Show preview". That will display this documentation page including the output from the above {{Countries of Africa/sandbox}} template. The output will start with "African countries" instead of "Countries of Africa". In the same manner, other changes could be made and previewed before saving the changes. Close the current browser window without saving the changes to discard them (or get back to a previous page using the button of the browser navigating in the session history).

Before updating the main data module, changes should be made in the sandbox data module and tested with the sandbox template.