Module:Cs1 documentation support

This module provides support for cs1|2 documentation by fetching data from the various modules, most notably Module:Citation/CS1/Configuration and rendering that data in a reader-accessible format.

Usage

{{#invoke:Cs1 documentation support|function_name}}

---

require('strict');
local getArgs = require ('Module:Arguments').getArgs;

local cfg = mw.loadData ('Module:Citation/CS1/Configuration');					-- load the configuration module
local whitelist = mw.loadData ('Module:Citation/CS1/Whitelist');				-- load the whitelist module


local exclusion_lists = {														-- TODO: move these tables into a separate ~/data module and mw.loadData() it
	['cite book'] = {
		['agency'] = true,
		['air-date'] = true,
		['arxiv'] = true,
		['biorxiv'] = true,
		['citeseerx'] = true,
		['class'] = true,
		['conference'] = true,
		['conference-format'] = true,
		['conference-url'] = true,
		['degree'] = true,
		['department'] = true,
		['display-interviewers'] = true,
		['docket'] = true,
		['episode'] = true,
		['interviewer#'] = true,
		['interviewer-first#'] = true,
		['interviewer-link#'] = true,
		['interviewer-mask#'] = true,
		['ismn'] = true,
		['issn'] = true,
		['issue'] = true,
		['jfm'] = true,
		['journal'] = true,
		['jstor'] = true,
		['mailinglist'] = true,
		['message-id'] = true,
		['minutes'] = true,
		['MR'] = true,
		['network'] = true,
		['number'] = true,
		['RFC'] = true,
		['script-journal'] = true,
		['season'] = true,
		['section'] = true,
		['sections'] = true,
		['series-link'] = true,
		['series-number'] = true,
		['series-separator'] = true,
		['sheet'] = true,
		['sheets'] = true,
		['SSRN'] = true,
		['station'] = true,
		['time'] = true,
		['time-caption'] = true,
		['trans-article'] = true,
		['trans-journal'] = true,
		['transcript'] = true,
		['transcript-format'] = true,
		['transcript-url'] = true,
		['ZBL'] = true,
		},
	['cite journal'] = {
		['agency'] = true,
		['air-date'] = true,
		['book-title'] = true,
		['chapter'] = true,
		['chapter-format'] = true,
		['chapter-url'] = true,
		['chapter-url-access'] = true,
		['class'] = true,
		['conference'] = true,
		['conference-format'] = true,
		['conference-url'] = true,
		['contribution'] = true,
		['contributor#'] = true,
		['contributor-first#'] = true,
		['contributor-link#'] = true,
		['contributor-mask#'] = true,
		['degree'] = true,
		['department'] = true,
		['display-interviewers'] = true,
		['docket'] = true,
		['edition'] = true,
		['editor#'] = true,
		['editor-first#'] = true,
		['editor-link#'] = true,
		['editor-mask#'] = true,
		['editors'] = true,
		['encyclopedia'] = true,
		['episode'] = true,
		['ignore-isbn-error'] = true,
		['interviewer#'] = true,
		['interviewer-first#'] = true,
		['interviewer-link#'] = true,
		['interviewer-mask#'] = true,
		['isbn'] = true,
		['ismn'] = true,
		['LCCN'] = true,
		['mailinglist'] = true,
		['message-id'] = true,
		['minutes'] = true,
		['network'] = true,
		['script-chapter'] = true,
		['season'] = true,
		['section'] = true,
		['sections'] = true,
		['series-link'] = true,
		['series-number'] = true,
		['series-separator'] = true,
		['sheet'] = true,
		['sheets'] = true,
		['station'] = true,
		['time'] = true,
		['time-caption'] = true,
		['trans-article'] = true,
		['transcript'] = true,
		['transcript-format'] = true,
		['transcript-url'] = true,
		},
	}

--[[-------------------------< A D D _ T O _ L I S T >---------------------------------------------------------

adds code/name pair to code_list and name/code pair to name_list; code/name pairs in override_list replace those
taken from the MediaWiki list; these are marked with a superscripted dagger.

|script-<param>= lang codes always use override names so dagger is omitted

]]

local function add_to_list (code_list, name_list, override_list, code, name, dagger)
	if false == dagger then
		dagger = '';															-- no dagger for |script-<param>= codes and names
	else
		dagger = '<sup>†</sup>';												-- dagger for all other lists using override
	end

	if override_list[code] then													-- look in the override table for this code
		code_list[code] = override_list[code] .. dagger;						-- use the name from the override table; mark with dagger
		name_list[override_list[code]] = code .. dagger;
	else
		code_list[code] = name;													-- use the MediaWiki name and code
		name_list[name] = code;
	end
end


--[[-------------------------< L I S T _ F O R M A T >---------------------------------------------------------

formats key/value pair into a string for rendering
	['k'] = 'v'	→ k: v

]]

local function list_format (result, list)
	for k, v in pairs (list)	do
		table.insert (result, k .. ': ' .. v);
	end
end


--[[-------------------------< L A N G _ L I S T E R >---------------------------------------------------------

Module entry point

Crude documentation tool that returns one of several lists of language codes and names.

Used in Template:Citation Style documentation/language/doc

{{#invoke:cs1 documentation support|lang_lister|list=<selector>|lang=<code>}}

where <selector> is one of the values:
	2char – list of ISO 639-1 codes and names sorted by code
	3char – list of ISO 639-2, -3 codes and names sorted by code
	ietf – list of IETF language tags and names sorted by tag
	ietf2 – list of ISO 639-1 based IETF language tags and names sorted by tag
	ietf3 – list of list of ISO 639-2, -3 based IETF language tags and names sorted by tag
	name – list of language names and codes sorted by name
	all - list all language codes/tags and names sorted by code/tag

where <code> is a MediaWiki supported 2, 3, or ietf-like language code; because of fall-back, language names may
be the English-language names.


]]

local function lang_lister (frame)
	local lang = (frame.args.lang and '' ~= frame.args.lang) and frame.args.lang or mw.getContentLanguage():getCode()
	local source_list = mw.language.fetchLanguageNames(lang, 'all');
	local override = cfg.lang_tag_remap;
	local code_1_list={};
	local code_2_list={};
	local ietf_list={};
	local ietf_list2={};
	local ietf_list3={};
	local name_list={};
	
	if not ({['2char']=true, ['3char']=true, ['ietf']=true, ['ietf2']=true, ['ietf3']=true, ['name']=true, ['all']=true})[frame.args.list] then
		return '<span style="color:#d33">unknown list selector: ' .. frame.args.list .. '</span>';
	end

	for code, name in pairs (source_list) do
		if 'all' == frame.args.list then
			add_to_list (code_1_list, name_list, override, code, name);			-- use the code_1_list because why not?
		elseif 2 == code:len() then
			add_to_list (code_1_list, name_list, override, code, name);
		elseif 3 == code:len() then
			add_to_list (code_2_list, name_list, override, code, name);
		elseif code:match ('^%a%a%-.+') then									-- ietf with 2-character language tag
			add_to_list (ietf_list, name_list, override, code, name);			-- add to main ietf list for |list=ietf
			add_to_list (ietf_list2, name_list, override, code, name);			-- add to ietf2 list
		elseif code:match ('^%a%a%a%-.+') then									-- ietf with 3-character language tag
			add_to_list (ietf_list, name_list, override, code, name);			-- add to main ietf list for |list=ietf
			add_to_list (ietf_list3, name_list, override, code, name);			-- add to ietf3 list
		end
	end
	
	local result = {};
	local out = {};

	if '2char' == frame.args.list or 'all' == frame.args.list then				-- iso 639-1
		list_format (result, code_1_list);
	elseif '3char' == frame.args.list then										-- iso 639-2, 3
		list_format (result, code_2_list);
	elseif 'ietf' == frame.args.list then										-- all ietf tags
		list_format (result, ietf_list);
	elseif 'ietf2' == frame.args.list then										-- 2-character ietf tags
		list_format (result, ietf_list2);
	elseif 'ietf3' == frame.args.list then										-- 3 character ietf tags
		list_format (result, ietf_list3);
	else																		--must be 'name'
		list_format (result, name_list);
	end
	
	local templatestyles = frame:extensionTag{
		name = 'templatestyles', args = { src = "Div col/styles.css" }
	}
	
	table.sort (result);
	table.insert (result, 1, templatestyles .. '<div class="div-col" style="column-width:16em">');
	table.insert (out, table.concat (result, '\n*'));
	table.insert (out, '</div>');
	
	return table.concat (out, '\n');
end


--[[--------------------------< S C R I P T _ L A N G _ L I S T E R >------------------------------------------

Module entry point

Crude documentation tool that returns list of language codes and names supported by the various |script-<param>= parameters.

used in Help:CS1 errors

{{#invoke:cs1 documentation support|script_lang_lister}}

]]

local function script_lang_lister (frame)
	local lang_code_src = cfg.script_lang_codes ;								-- get list of allowed script language codes
	local override = cfg.lang_tag_remap;
	local this_wiki_lang = mw.language.getContentLanguage().code;				-- get this wiki's language

	local code_list = {};														-- interim list of aliases
	local name_list={};															-- not used; defined here so that we can reuse add_to_list() 
	local out = {};																-- final output (for now an unordered list)
	
	for _, code in ipairs (lang_code_src) do									-- loop through the list of codes
		local name = mw.language.fetchLanguageName (code, this_wiki_lang);		-- get the language name associated with this code
		add_to_list (code_list, name_list, override, code, name, false);		-- name_list{} not used but provided so that we can reuse add_to_list(); don't add superscript dagger
	end
	
	local result = {};
	local out = {};

	list_format (result, code_list);
	
	local templatestyles = frame:extensionTag{
		name = 'templatestyles', args = { src = "Div col/styles.css" }
	}

	table.sort (result);
	table.insert (result, 1, templatestyles .. '<div class="div-col" style="column-width:16em">');
	table.insert (out, table.concat (result, '\n*'));
	table.insert (out, '</div>');
	
	return table.concat (out, '\n');
end


--[[--------------------------< A L I A S _ L I S T E R >------------------------------------------------------

experimental code that lists parameters and their aliases.  Perhaps basis for some sort of documentation?

{{#invoke:cs1 documentation support|alias_lister}}

]]

local function alias_lister ()
	local alias_src = cfg.aliases;												-- get master list of aliases
	local key;																	-- key for k/v in a new table
	local list = {};															-- interim list of aliases
	local out = {};																-- final output (for now an unordered list)
	
	for _, aliases in pairs (alias_src) do										-- loop throu the master list of aliases
		if 'table' == type (aliases) then										-- table only when there are aliases
			for i, alias in ipairs (aliases) do									-- loop through all of the aliases
				if 1 == i then													-- first 'alias' is the canonical parameter name
					key = alias;												-- so it becomes the key in list
				else
					list[key] = list[key] and (list[key] .. ', ' .. alias) or alias;	-- make comma-separated list of aliases
					list[alias] = 'see ' .. key;								-- make a back reference from this alias to the canonical parameter
				end
			end
		end
	end
	
	for k, v in pairs (list) do													-- loop through the list to make a simple unordered list
		table.insert (out, table.concat ({'*', k, ': ', v}));
	end
	
	table.sort (out);															-- sort it
	return table.concat (out, '\010');											-- concatenate with \n
--	return (mw.dumpObject (list))
end


--[[--------------------------< C A N O N I C A L _ P A R A M _ L I S T E R >----------------------------------

experimental code that lists canonical parameter names.  Perhaps basis for some sort of documentation?

returns a comma separated, alpha sorted, list of the canonical parameters.  If given a template name, excludes
parameters listed in that template's exclusion_list[<template>]{} table (if a table has been defined).

{{#invoke:cs1 documentation support|canonical_param_lister|<template>}}

]]

local function canonical_param_lister (frame)
	local template = frame.args[1];
	if '' == template then
		template = nil;
	end

	if template then
		template = mw.text.trim (template:lower());
	end

	local alias_src = cfg.aliases;												-- get master list of aliases
	local id_src = cfg.id_handlers;												-- get master list of identifiers
	
	local list = {};															-- interim list of aliases
	local out = {};																-- final output (for now an unordered list)
	
	for _, aliases in pairs (alias_src) do										-- loop through the master list of aliases
		local name;
		if 'table' == type (aliases) then										-- table only when there are aliases
			name = aliases[1];													-- first member of an aliases table is declared canonical
		else
			name = aliases;														-- for those parameters that do not have any aliases, the parameter is declared canonical
		end

		if not template then													-- no template name, add this parameter
			table.insert (list, name);
		elseif not exclusion_lists[template] then								-- template name but no exclusion list
			table.insert (list, name);
		elseif not exclusion_lists[template][name] then							-- template name and exclusion list but name not in list
			table.insert (list, name);
		end
	end
	
	for k, ids in pairs (id_src) do												-- spin through the list of identifiers
		local name = id_src[k].parameters[1];									-- get the first (left-most) parameter name
		local access = id_src[k].custom_access;									-- get the access-icon parameter if it exists for this identifier
		if not template then													-- no template name
			table.insert (list, name);											-- add this parameter
			if access then
				table.insert (list, access);									-- add this access-icon parameter
			end
		elseif not exclusion_lists[template] then								-- template name but no exclusion list
			table.insert (list, name);
			if access then
				table.insert (list, access);
			end
		elseif not exclusion_lists[template][name] then							-- template name and exclusion list but name not in list
			table.insert (list, name);
			if access then
				table.insert (list, access);
			end
		end
	end
	
	for _, param in ipairs (list) do											-- loop through the list to make a simple unordered list
		table.insert (out, table.concat ({'*', param}));
	end
	
	local function comp( a, b )													-- used in following table.sort()
		return a:lower() < b:lower();
	end
	
	table.sort (out, comp);														-- sort the list
	return table.concat (out, '\010');											-- concatenate with \n
--	return (mw.dumpObject (list))
end


--[[--------------------------< C A N O N I C A L _ N A M E _ G E T >------------------------------------------

returns first (canonical) name when metaparameter is assigned a table of names
returns name when metaparameter is assigned a single name
returns empty string when metaparameter name not found in alias_src{}, id_src{}, or id_src[meta].custom_access

metaparameter <metaparam> is the key in Module:Citation/CS1 aliases{} table or id_handlers{} table.  Because access-icon
don't have <metaparam> keys, per se, we create pseudo <metaparam> keys by appending 'access' to the identifier <metaparam>:
	the <metaparam> for |doi-access= is, for the purposes of this function, DOIaccess, etc

Some lists of aliases might be better served when a particular alias is identified as the canonical alias for a 
particular use case.  If, for example, <metaparam> Perodical lists:
	'journal', 'magazine', 'newspaper', 'periodical', 'website', 'work'
that order works fine for {{cite journal}} documentation but doesn't work so well for {{cite magazine}}, {{cite news}},
or {{cite web}}.  So, for using this function to document {{cite magazine}} the returned value should be the
parameter best suited for that template so we can specify magazine in the override (frame.args[2])

While for this function, it would be just as simple to not use the function, this mechanism is implemented here 
to match similar functionality in alias_names_get() (there are slight differences)
	<override> must exist in the alias list
	does not apply to the access icon parameters (ignored - these have no aliases)

(and which would be best for {{cite news}}? |newspaper= or |work=? can't solve all of the worlds problems at once).

output format is controlled by |format=
	plain - renders in plain text in a <span> tag; may have id attribute
	para - renders as it would in {{para|<param>}}

{{#invoke:cs1 documentation support|canonical_name_get|<metaparam>|<override>|id=<attribute>|format=[plain|para]}}

]]

local function canonical_name_get (frame)
	local alias_src = cfg.aliases;												-- get master list of aliases
	local id_src = cfg.id_handlers;												-- get master list of identifiers
	local args = getArgs (frame);

	local name;
	local meta = args[1]
	local override = args[2];

	local access;																-- for id-access parameters
	if meta:match ('^(%u+)access') then											-- the metaparameter (which is not used in ~/Configuration) is id_handlers key concatenated with access: BIBCODEaccess
		meta, access = meta:gsub ('^(%u+)access', '%1');						-- strip 'access' text from meta and use returned count value as a flag
	end

	if alias_src[meta] then
		name = alias_src[meta];													-- name is a string or a table
		if 'table' == type (name) then											-- table only when there are aliases
			if not override then
				name = name[1];													-- first member of an aliases table is declared canonical
			else
				for _, v in ipairs (name) do									-- here when override is set; spin throu the aliases to make sure override matches alias in table
					if v == override then
						name = v;												-- declare override to be the canonical param for this use case
						break;
					end
				end
			end
		end

	elseif id_src[meta]then														-- if there is an id handler
		if access then															-- and if this is a request for the handler's custom access parameter
			if id_src[meta].custom_access then									-- if there is a custom access parameter
				name = id_src[meta].custom_access;								-- use it
			else
				return '';														-- nope, return empty string
			end
		else
			if not override then
				name = id_src[meta].parameters[1];								-- get canonical id handler parameter
			else
				for _, v in ipairs (id_src[meta].parameters) do					-- here when override is set; spin throu the aliases to make sure override matches alias in table
					if v == override then
						name = v;												-- declare override to be the canonical param for this use case
						break;
					end
				end
			end
		end
	else
		return '';																-- metaparameter not specified, or no such metaparameter
	end
	
	if 'plain' == args.format then												-- format and return the output
		if args.id then
			return string.format ('<span id="%s">%s</span>', args.id, name);	-- plain text with id attribute
		else
			return name;														-- plain text
		end
	elseif 'para' == args.format then
		return string.format ('<code class="nowrap">|%s=</code>', name);		-- same as {{para|<param>}}
	end

	return string.format ('<b id="%s">%s</b>', args.id or '', name);			-- because {{csdoc}} bolds param names
end


--[[--------------------------< A L I A S _ N A M E S _ G E T >------------------------------------------------

returns list of aliases for metaparameter <metaparam>
returns empty string when there are no aliases
returns empty string when <metaparam> name not found in alias_src{} or id_src{}; access icon parameters have no aliases so ignored

metaparameter <metaparam> is the key in Module:Citation/CS1 aliases{} table or id_handlers{} table.

Some lists of aliases might be better served when a particular alias is identified as the canonical alias for a 
particular use case.  If, for example, <metaparam> Perodical lists:
	'journal', 'magazine', 'newspaper', 'periodical', 'website', 'work'
that order works fine for {{cite journal}} documentation but doesn't work so well for {{cite magazine}}, {{cite news}},
or {{cite web}}.  So, for using this function to document {{cite magazine}} the returned value should be the
aliases that are not best suited for that template so we can specify magazine in the override (frame.args[2])
to be the canonical parameter so it won't be listed with the rest of the aliases (normal canonical journal will be)

	<override> must exist in the alias list except:
		when <override> value is 'all', returns the canonical parameter plus all of the aliases

output format is controlled by |format=
	plain - renders in plain text in a <span> tag; may have id attribute
	para - renders as it would in {{para|<param>}}
	when not specified, refurns the default bold format used for {{csdoc}}

{{#invoke:cs1 documentation support|alias_name_get|<metaparam>|<override>|format=[plain|para]}}

]]

local function alias_names_get (frame)
	local alias_src = cfg.aliases;												-- get master list of aliases
	local id_src = cfg.id_handlers;												-- get master list of identifiers
	local args = getArgs (frame);
	
	local meta = args[1];
	local override = args[2];

	local out = {};
	local source;																-- selected parameter or id aliases list
	local aliases;

	source = alias_src[meta] or (id_src[meta] and id_src[meta].parameters);
	if not source then
		if meta:match ('%u+access') then
			return 'no' == args.none and '' or 'none';							-- custom access parameters don't have aliases
		else
			return '';															-- no such meta
		end
	elseif not source[2] then													-- id_source[meta] is always a table; if no second member, no aliases
		return 'no' == args.none and '' or 'none';
	end
	
	if not override then
		aliases = source;														-- normal skip-canonical param case
	else
		local flag = 'all' == override and true or nil;							-- so that we know that <override> parameter is a valid alias; spoof when override == 'all'
		aliases = {[1] = ''};													-- spoof to push alias_src[meta][1] and id_src[meta][1] into aliases[2]
		for _, v in ipairs (source) do											-- here when override is set; spin through the aliases to make sure override matches alias in table
			if v ~= override then
				table.insert (aliases, v);										-- add all but overridden param to the the aliases list for this use case
			else
				flag = true;													-- set the flag so we know that <override> is a valid alias
			end
		end
		if not flag then
			aliases = {}														-- unset the table as error indicator
		end
	end

	if 'table' == type (aliases) then											-- table only when there are aliases
		for i, alias in ipairs (aliases) do
			if 1 ~= i then														-- aliases[1] is the canonical name; don't include it
				if 'plain' == args.format then									-- format and return the output
					table.insert (out, alias);									-- plain text
				elseif 'para' == args.format then
					table.insert (out, string.format ('<code class="nowrap">|%s=</code>', alias));	-- same as {{para|<param>}}
				else
					table.insert (out, string.format ("'''%s'''", alias));		-- because csdoc bolds param names
				end
			end
		end
		
		return table.concat (out, ', ');										-- make pretty list and quit
	end

	return 'no' == args.none and '' or 'none';									-- no metaparameter with that name or no aliases
end


--[[--------------------------< I S _ B O O K _ C I T E _ T E M P L A T E >------------------------------------

fetch the title of the current page; if it is a preprint template, return true; empty string else

]]

local book_cite_templates = {
	['citation'] = true,
	['cite book'] = true,
	}

local function is_book_cite_template ()
	local title = mw.title.getCurrentTitle().rootText;							-- get title of current page without namespace and without sub-pages; from Template:Cite book/new -> Cite book
	
	title = title and title:lower() or '';
	return book_cite_templates[title] or '';
end


--[[--------------------------< I S _ L I M I T E D _ P A R A M _ T E M P L A T E >----------------------------

fetch the title of the current page; if it is a preprint template, return true; empty string else

]]

local limited_param_templates = {												-- if ever there is a need to fetch info from ~/Whitelist then
	['cite arxiv'] = true,														-- this list could also be fetched from there
	['cite biorxiv'] = true,
	['citeseerx'] = true,
	['ssrn'] = true,
	}

local function is_limited_param_template ()
	local title = mw.title.getCurrentTitle().rootText;							-- get title of current page without namespace and without sub-pages; from Template:Cite book/new -> Cite book
	
	title = title and title:lower() or '';
	return limited_param_templates[title] or '';
end


--[[--------------------------< H E A D E R _ M A K E >--------------------------------------------------------

makes a section header from <header_text> and <level>; <level> defaults to 2; cannot be less than 2

]]

local function _header_make (args)
	if not args[1] then
		return '';																-- no header text
	end
	
	local level = args[2] and tonumber (args[2]) or 2;
	
	level = string.rep ('=', level);
	return level .. args[1] .. level;
end


--[[--------------------------< H E A D E R _ M A K E >--------------------------------------------------------

Entry from an {{#invoke:}}
makes a section header from <header_text> and <level>; <level> defaults to 2; cannot be less than 2

]]

local function header_make (frame)
	local args = getArgs (frame);
	return _header_make (args);
end


--[[--------------------------< I D _ L I M I T S _ G E T >----------------------------------------------------

return the limit values for named identifier parameters that have <id> limits (pmc, pmid, ssrn, s2cid, oclc, osti, rfc); the return
value used in template documentation and error message help-text

{{#invoke:Cs1 documentation support|id_limits_get|<id>}}

]]

local function id_limits_get (frame)
	local args = getArgs (frame);
	local handlers = cfg.id_handlers;											-- get id_handlers {} table from ~/Configuration

	return args[1] and handlers[args[1]:upper()].id_limit or ('<span style="color:#d33">No limit defined for identifier: ' .. (args[1] or '<unknown name>') .. '</span>');
end


--[[--------------------------< C A T _ L I N K _ M A K E >----------------------------------------------------
]]

local function cat_link_make (cat)
	return table.concat ({'[[:Category:', cat, ']]'});
end


--[[--------------------------< S C R I P T _ C A T _ L I S T E R >--------------------------------------------

utility function to get script-language categories

]]

local lang_list_t = mw.language.fetchLanguageNames ('en', 'all');
 
local function script_cat_lister (script_lang_codes_t, lang_tag_remap_t, cats_list_t)
	for _, lang_code in ipairs (script_lang_codes_t) do
		local lang_name = lang_tag_remap_t[lang_code] or lang_list_t[lang_code];	-- use remap table to get Bengali instead of Bangla and the like; else use standard MediaWiki names
		local cat = 'CS1 uses ' .. lang_name .. '-language script (' .. lang_code .. ')';	-- build a category name
		cats_list_t[cat] = 1;													-- and save it
	end
end


--[[--------------------------< C S 1 _ C A T _ L I S T E R >--------------------------------------------------

This is a crude tool that reads the category names from Module:Citation/CS1/Configuration, makes links of them,
and then lists them in sorted lists.  A couple of parameters control the rendering of the output:
	|select=	-- (required) takes one of three values: error, maint, prop
	|sandbox=	-- takes one value: no
	|hdr-lvl=	-- base header level (number of == that make a header); default:2 min:2

This tool will automatically attempt to load a sandbox version of ~/Configuration if one exists.
Setting |sandbox=no will defeat this.

{{#invoke:cs1 documentation support|cat_lister|select=<error|maint|prop>|sandbox=<no>}}

]]

local function cat_lister (frame)
	local args = getArgs (frame);

	local list_live_cats = {};													-- list of live categories
	local list_sbox_cats = {};													-- list of sandbox categories
	
	local live_sbox_out = {}													-- list of categories that are common to live and sandbox modules
	local live_not_in_sbox_out = {}												-- list of categories in live but not sandbox
	local sbox_not_in_live_out = {}												-- list of categories in sandbox but not live
	
	local out = {};																-- final output assembled here
	
	local sandbox;																-- boolean; true: evaluate the sandbox module
	local hdr_lvl;																-- 
	
	local sb_cfg;
	local sandbox, sb_cfg = pcall (mw.loadData, 'Module:Citation/CS1/Configuration/sandbox');	-- get sandbox configuration

	local cat;

	local select = args.select;
	if 'no' == args.sandbox then												-- list sandbox?
		sandbox = false;														-- no, live only
	end
	if hdr_lvl then																-- if set and
		if tonumber (hdr_lvl) then												-- can be converted to number
			if 2 > tonumber (hdr_lvl) then										-- min is 2
				hdr_lvl = 2;													-- so set to min
			end
		else																	-- can't be converted
			hdr_lvl = 2;														-- so default to min
		end
	else
		hdr_lvl = 2;															-- not set so default to min
	end

	if 'error' == select or 'maint' == select then								-- error and main categorys handling different from poperties cats
		for _, t in pairs (cfg.error_conditions) do								-- get the live module's categories
			if ('error' == select and t.message) or ('maint' == select and not t.message) then
				cat = t.category:gsub ('|(.*)$', '');							-- strip sort key if any
				list_live_cats[cat] = 1;										-- add to the list
			end
		end
		
		if sandbox then															-- if ~/sandbox module exists and |sandbox= not set to 'no'
			for _, t in pairs (sb_cfg.error_conditions) do						-- get the sandbox module's categories
				if ('error' == select and t.message) or ('maint' == select and not t.message) then
					cat = t.category:gsub ('|(.*)$', '');						-- strip sort key if any
					list_sbox_cats[cat] = 1;									-- add to the list
				end
			end
		end
		
	elseif 'prop' == select then												-- prop cats
		for _, cat in pairs (cfg.prop_cats) do									-- get the live module's categories
			cat = cat:gsub ('|(.*)$', '');										-- strip sort key if any
			list_live_cats[cat] = 1;											-- add to the list
		end

		script_cat_lister (cfg.script_lang_codes, cfg.lang_tag_remap, list_live_cats);	-- get live module's foriegn language script cats

		if sandbox then															-- if ~/sandbox module exists and |sandbox= not set to 'no'
			for _, cat in pairs (sb_cfg.prop_cats) do							-- get the sandbox module's categories
				cat = cat:gsub ('|(.*)$', '');									-- strip sort key if any
				list_sbox_cats[cat] = 1;										-- add to the list
			end

			script_cat_lister (sb_cfg.script_lang_codes, sb_cfg.lang_tag_remap, list_sbox_cats);	-- get sandbox module's foriegn language script cats
		end
	else
		return '<span style="color:#d33; font-style:normal;">error: unknown selector: ' .. select .. '</span>'
	end	

	for k, _ in pairs (list_live_cats) do										-- separate live/sbox common cats from cats not in sbox
		if not list_sbox_cats[k] and sandbox then
			table.insert (live_not_in_sbox_out, cat_link_make (k));				-- in live but not in sbox
		else
			table.insert (live_sbox_out, cat_link_make (k));					-- in both live and sbox
		end
	end

	for k, _ in pairs (list_sbox_cats) do										-- separate sbox/live common cats from cats not in live
		if not list_live_cats[k] then
			table.insert (sbox_not_in_live_out, cat_link_make (k));				-- in sbox but not in live
		end
	end

	local function comp (a, b)													-- local function for case-agnostic category name sorting
		return a:lower() < b:lower();
	end

	local header;																-- initialize section header with name of selected category list
	if 'error' == select then
		header = 'error';
	elseif 'maint' == select then
		header = 'maintenance';
	else
		header = 'properties';
	end
	
	header = table.concat ({													-- build the main header
		'Live ',																-- always include this
		((sandbox and 'and sandbox ') or ''),									-- if sandbox evaluated, mention that
		header,																	-- add the list name
		' categories (',														-- finish the name and add
		#live_sbox_out,															-- count of categories listed
		')'																		-- close
	})

	local templatestyles = frame:extensionTag{
		name = 'templatestyles', args = { src = "Div col/styles.css" }
	}

	header = table.concat ({													-- make a useable header
		_header_make ({header, hdr_lvl}),
		'\n' .. templatestyles .. '<div class="div-col">'	-- opening <div> for columns
		});

	table.sort (live_sbox_out, comp);											-- sort case agnostic acsending
	table.insert (live_sbox_out, 1, header);									-- insert the header at the top
	table.insert (out, table.concat (live_sbox_out, '\n*'));					-- make a big string of unordered list markup
	table.insert (out, '</div>\n');												-- close the </div> and add new line so the next header works

	if 0 ~= #live_not_in_sbox_out then											-- when there is something in the table
		header = table.concat ({												-- build header for subsection
			'In live but not in sandbox (',
			#live_not_in_sbox_out,
			')'
			});
	
		header = table.concat ({												-- make a useable header
			_header_make ({header, hdr_lvl+1}),
			'\n' .. templatestyles .. '<div class="div-col">'
			});
	
		table.sort (live_not_in_sbox_out, comp);
		table.insert (live_not_in_sbox_out, 1, header);
		table.insert (out, table.concat (live_not_in_sbox_out, '\n*'));
		table.insert (out, '</div>\n');
	end
	
	if 0 ~= #sbox_not_in_live_out then											-- when there is something in the table
		header = table.concat ({												-- build header for subsection
			'In sandbox but not in live (',
			#sbox_not_in_live_out,
			')'
			});
	
		header = table.concat ({												-- make a useable header
			_header_make ({header, hdr_lvl+1}),
			'\n' .. templatestyles .. '<div class="div-col">'
			});
	
		table.sort (sbox_not_in_live_out, comp);
		table.insert (sbox_not_in_live_out, 1, header);
		table.insert (out, table.concat (sbox_not_in_live_out, '\n*'));
		table.insert (out, '</div>\n');
	end

	return table.concat (out);													-- concat into a huge string and done
end


--[=[--------------------------< H E L P _ T E X T _ C A T S >--------------------------------------------------

To create category links at the bottom of each error help text section and on the individual error category pages;
fetches category names from ~/Configuration; replaces this:
	{{#ifeq:{{FULLPAGENAME}}|Category:CS1 errors: bioRxiv|Category:CS1 errors: bioRxiv|[[:Category:CS1 errors: bioRxiv]]}}
with this:
	{{#invoke:Cs1 documentation support|help_text_cats|err_bad_biorxiv}}
where {{{1}}} is the error_conditions key from Module:Citation/CS1/Configuration

add |pages=yes to append the number of pages in the category

]=]

local function help_text_cats (frame)
	local args_t = getArgs (frame);
	local error_conditions_t = cfg.error_conditions;							-- get the table of error conditions
	local replacements_t = {};													-- table to hold replacement parameters for $1 etc placeholders in category names
	for k, v in pairs (args_t) do												-- look for |$1=<replacement> parameters
		if 'string' == type (k) and k:match ('^$%d+$') then						-- if found
			replacements_t[k] = v;												-- save key and value
		end
	end

	if args_t[1] and error_conditions_t[args_t[1]] then							-- must have error_condition key and it must exist
		local error_cat = error_conditions_t[args_t[1]].category;				-- get error category from cs1|2 configuration
		if error_cat:match ('$%d') then											-- look for placeholders in <error_cat>
			error_cat = error_cat:gsub ('$%d', replacements_t)					-- replace place holders with matching value from replacements_t
		end
		
		local title_obj = mw.title.getCurrentTitle();							-- get a title object for the currently displayed page
		local name_space = title_obj.nsText;
		if ('Category' == name_space) and (error_cat == title_obj.text) then	-- if this is the category page for the error message
			return table.concat ({'Category:', error_cat});						-- no link; just category name
		else																	-- here when currently displayed page is other than the error message category
			local pages = '';													-- default empty strin for concatenation
			if 'yes' == args_t.pages then										-- if we should display category page count: TODO: do we need to keep this?
				pages = mw.site.stats.pagesInCategory (error_cat, 'all');		-- get category page count
				pages = table.concat ({' (', mw.language.getContentLanguage():formatNum (pages), ' page', (1 == pages) and ')' or 's)'});	-- make renderable text
			end
			return table.concat ({'[[:Category:', error_cat, ']]', pages});		-- link to category with or without page count
		end
	else
		return '<span style="color:#d33">unknown error_conditions key: ' .. (args_t[1] or 'key missing') .. '</span>';
	end
end


--[[--------------------------< H E L P _ T E X T _ E R R O R _ M E S S A G E >--------------------------------

to render help text example error messages
	{{#invoke:Cs1 documentation support|help_text_error_messages|err_bad_biorxiv}}

assign a single underscore to any of the |$n= parameters to insert an empty string in the error message:
	{{#invoke:Cs1 documentation support|help_text_error_messages|err_bad_issn|$1=_}} -> Check |issn= value
	{{#invoke:Cs1 documentation support|help_text_error_messages|err_bad_issn|$1=e}} -> Check |eissn= value

error message is rendered at 120% font size; to specify another font size use |size=; must include unit specifier (%, em, etc)

]]

local function help_text_error_messages (frame)
	local args_t = getArgs (frame);
	local error_conditions = mw.loadData ('Module:Citation/CS1/Configuration').error_conditions;
--	local span_o = '<span class="cs1-visible-error citation-comment">';
	local span_o = '<span class="citation-comment" style="color:#d33; font-size:' .. ((args_t.size and args_t.size) or '120%') .. '">';
	local span_c = '</span>';

	local message;
	local out = {};																-- output goes here
	
	if args_t[1] and error_conditions[args_t[1]] then								-- must have error_condition key and it must exist
		message = error_conditions[args_t[1]].message;
		local i=1;
		local count;
		local rep;
		repeat
			rep = '$'..i
			args_t[rep] = args_t[rep] and args_t[rep]:gsub ('^%s*_%s*$', '') or nil;	-- replace empty string marker with actual empty string
			message, count = message:gsub (rep, args_t[rep] or rep)
			i = i + 1;
			until (0 == count);

		table.insert (out, span_o);
		table.insert (out, message);
		table.insert (out, span_c);
	else
		return '<span style="color:#d33">unknown error_conditions key: ' .. (args_t[1] or 'key missing') .. '</span>';
	end
	
	local out_str = table.concat (out);
	return table.concat ({frame:extensionTag ('templatestyles', '', {src='Module:Citation/CS1/styles.css'}), out_str});
end


--[[--------------------------< T E M P L A T E S _ T >--------------------------------------------------------

This table is a k/v table of sequence tables.  The keys in this table are collapsed lowercase form of the cs1|2
template names ({{ROOTPAGENAME}}):
	Template:Cite AV media -> citeavmedia
	
Each subsequence table holds:
	[1] documentation page where the TemplateData json is stored ({{cite book}} is the oddball)
	[2] key to 'preprint_arguments_t' and unique_arguments_t' tables in Module:Citation/CS1/Whitelist; these keys
		dictate which of the basic or limited arguments and numbered arguments tables will be used to validate
		the content of the TemplateData

]]

local templates_t = {
	citearxiv = {'Template:Cite_arXiv/doc', 'arxiv'},							-- preprint arguments 
	citeavmedia = {'Template:Cite AV media/doc', 'audio-visual'},				-- unique arguments
	citeavmedianotes = {'Template:Cite AV media notes/doc'},					-- no template data
	citebiorxiv = {'Template:Cite bioRxiv/doc', 'biorxiv'},						-- preprint arguments
	citebook = {'Template:Cite book/TemplateData'},
	citeciteseerx = {'Template:Cite CiteSeerX/doc', 'citeseerx'},				-- no template data; preprint uses limited arguments
	citeconference = {'Template:Cite conference/doc', 'conference'},			-- unique arguments
	citedocument = {'Template:Cite document/doc', 'document'},					-- special case; uses whitelist.document_parameters_t
	citeencyclopedia = {'Template:Cite encyclopedia/doc'},
	citeepisode = {'Template:Cite episode/doc', 'episode'},						-- unique arguments
	citeinterview = {'Template:Cite interview/doc'},
	citejournal = {'Template:Cite journal/doc'},
	citemagazine = {'Template:Cite magazine/doc'},
	citemailinglist = {'Template:Cite mailing list/doc', 'mailinglist'},		-- unique arguments			-- no template data
	citemap = {'Template:Cite map/TemplateData', 'map'},						-- unique arguments
	citemedrxiv = {'Template:Cite medRxiv/doc', 'medrxiv'},						-- preprint arguments
	citenews = {'Template:Cite news/doc'},
	citenewsgroup = {'Template:Cite newsgroup/doc', 'newsgroup'},				-- unique arguments
	citepodcast = {'Template:Cite podcast/doc'},
	citepressrelease = {'Template:Cite press release/doc'},
	citereport = {'Template:Cite report/doc', 'report'},						-- unique arguments
	citeserial = {'Template:Cite serial/doc', 'serial'},						-- unique arguments			-- no template data
	citesign = {'Template:Cite sign/doc'},
	citespeech = {'Template:Cite speech/doc', 'speech'},						-- unique arguments			-- no template data
	citessrn = {'Template:Cite SSRN/doc', 'ssrn'},								-- preprint arguments		-- no template data
	citetechreport = {'Template:Cite techreport/doc'},
	citethesis = {'Template:Cite thesis/doc', 'thesis'},						-- unique arguments
	citeweb = {'Template:Cite web/doc'},
	citation = {'Template:Citation/doc'},
	}


--[[--------------------------< N O _ P A G E _ T E M P L A T E S _ T >----------------------------------------


]]

local no_page_templates_t = {};


--[[--------------------------< I D E N T I F I E R _ A L I A S E S _ T >--------------------------------------

a table of the identifier aliases

]]

local identifier_aliases_t = {}
for identifier, handler in pairs (cfg.id_handlers) do							-- for each identifier
	local aliases_t = {};														-- create a table
	for _, alias in ipairs (handler.parameters) do								-- get the alaises
		aliases_t[alias] = true;												-- and add them to the table in a form that mimics the whitelist tables
	end
	identifier_aliases_t[identifier:lower()] = aliases_t;						-- add new table to the identifier aliases table; use lowercase identifier base name for the key
end


--[[--------------------------< T E M P L A T E _ D A T A _ J S O N _ G E T >----------------------------------

get template doc page content and extract the content of the TemplateData tags (case insensitive)

<template> is the canonical name of the template doc page (with namespace) that holds the template data; usually
Template:Cite xxx/doc (except Template:Cite book/TemplateData)

]]

local function template_data_json_get (template)
	local json = mw.title.new (template):getContent() or '';					-- get the content of the article or ''; new pages edited w/ve do not have 'content' until saved; ve does not preview; phab:T221625
	json = json:match ('<[Tt]emplate[Dd]ata>(.-)</[Tt]emplate[Dd]ata>');		-- remove everything exept the content of the TemplatData tags
	return json and mw.text.jsonDecode (json);									-- decode the json string and return as a table; nil if not found
end


--[[--------------------------< V A L I D A T E _ D O C U M E N T _ P A R A M >--------------------------------

looks for <param> (can be the canonical parameter name or can be an alias) in whitelist.document_parameters_t.
When found, returns true; nil else

<param> is the parameter's name as listed in the TemplateData

]]

local function validate_document_param (param)
	if true == whitelist.document_parameters_t[param] then
		return true;
	end
end


--[[--------------------------< V A L I D A T E _ U N I Q U E _ P A R A M >------------------------------------

looks for <param> (can be the canonical parameter name or can be an alias) in whitelist.basic_arguments{} and if
necessary in whitelist.numbered_arguments{}.  When found, returns true; nil else

<param> is the parameter's name as listed in the TemplateData

]]

local function validate_basic_param (param)
	if true == whitelist.common_parameters_t[param] then
		return true;
	end
end


--[[--------------------------< V A L I D A T E _ P R E P R I N T _ P A R A M >--------------------------------

looks for <param> (can be the canonical parameter name or can be an alias) in whitelist.preprint_arguments_t{} or
whitelist.limited_basic_arguments{} or whitelist.limited_numbered_arguments{}.  When found, returns true; nil else

<param> is the parameter's name as listed in the TemplateData
<key> is key neccessary to look in the appropriate subtable of whitelist.preprint_arguments_t{}

]]

local function validate_preprint_param (param, key)
	if true == whitelist.preprint_arguments_t[key][param] or
		true == whitelist.limited_parameters_t[param] then
--		true == whitelist.limited_basic_arguments_t[param] or
--		true == whitelist.limited_numbered_arguments_t[param] then
			return true;
	end
end


--[[--------------------------< V A L I D A T E _ U N I Q U E _ P A R A M >------------------------------------

looks for <param> (can be the canonical parameter name or can be an alias) in whitelist.unique_arguments_t{} or
whitelist.basic_arguments{} or whitelist.numbered_arguments{}.  When found, returns true; nil else

<param> is the parameter's name as listed in the TemplateData
<key> is key neccessary to look in the appropriate subtable of whitelist.unique_arguments_t{}

]]

local function validate_unique_param (param, key, cfg_aliases_t)
	if true == whitelist.unique_arguments_t[key][param] or true == validate_basic_param (param) then
		return true;
	end
end


--[[--------------------------< V A L I D A T E _ I D _ P A R A M >--------------------------------------------

looks for <param> <alias> in identifier_aliases_t{}.  When found, returns true; nil else

<param> is the parameter's name as listed in the TemplateData
<alias> is the alias that we're looking for

]]

local function validate_id_alias (param, alias)
	return identifier_aliases_t[param] and identifier_aliases_t[param][alias];
end
	

--[[--------------------------< P A R A M _ E R R O R_ M S G >-------------------------------------------------


]]

local function param_error_msg (param)
	return '<code style="color: inherit; background: inherit; border: none; padding: inherit">|' .. param .. '=</code> is not a valid parameter';
end


--[[--------------------------< A L I A S _ E R R O R_ M S G >-------------------------------------------------


]]

local function alias_error_msg (param, alias)
	return '<code style="color: inherit; background: inherit; border: none; padding: inherit">|' .. alias .. '=</code> is not a valid alias of: <code style="color: inherit; background: inherit; border: none; padding: inherit">|' .. param .. '=</code>';
end


--[[--------------------------< C F G _ A L I A S E S _ T _ M A K E >------------------------------------------

convert this from cfg.aliases{}:
	['AccessDate'] = {'access-date', 'accessdate'}

to this in out_t{}
	['access-date'] = 'AccessDate',
	['accessdate'] = 'AccessDate',

to test if |accessdate= is an aliases of |access-date=:
	if out_t['access-date'] == out_t['accessdate']
]]

local function cfg_aliasts_t_make ()
	local out_t = {};
	for meta, params_t in pairs (cfg.aliases) do
		if 'table' == type (params_t) then										-- metaparameters that are assigned string values do not have aliases
			for _, param in ipairs (params_t) do								-- for each alias
				param = param:gsub ('#', '');									-- get rid of enumerators
				out_t[param] = meta;											-- add it to the output table
			end
		end
	end
--error (mw.dumpObject (out_t))
	return out_t;
end


--[[--------------------------< T E M P L A T E _ D A T A _ V A L I D A T E >----------------------------------

compairs parameter names listed in a cs1|2 template's TemplateData structure (everything between <TemplateData>
and </TemplateData> tag case insensitive).  Returns error messages when errors found, empty string else.

	{{#invoke:Cs1 documentation support|template_data_validate|{{ROOTPAGENAME}}}}

When called from a different page:
	{{#invoke:cs1 documentation support|template_data_validate|<canonical template name>}}
where the <canonical template name> is the template's canonical name with or without namespace and or subpages

]]

local function template_data_validate (frame)
	local args_t = getArgs (frame);

	if not args_t[1] then
		return '<span style="color:#d33">Error: cs1|2 template name required</span>';
	end

	local template_idx = args_t[1]:lower():match ('cit[ae][^/]+');				-- args_t[1] has something
	if not template_idx then													-- but if not a cs1|2 template abandon with error message
		return '<span style="color:#d33">Error: cs1|2 template name required</span>';
	else
		template_idx = template_idx:gsub (' ', '');								-- is what appears to be a cs1|2 template so strip spaces
	end

	local cfg_aliases_t = cfg_aliasts_t_make ();

	local template_t = templates_t[template_idx];
	local out = {};

	local template_doc = template_t[1];
	local json_t = template_data_json_get (template_doc);
	
	if not json_t then
		 table.insert (out, 'Error: can\'t find TemplateData');
	else
		for param, param_t in pairs (json_t['params']) do
			local param_i;														-- this will be the parameter name that gets validated
			if param:find ('[Ss]2[Cc][Ii][Dd]') then							-- |s2cid*= parameters are not enumerated ...
				param_i = param;												-- ... so don't convert the '2' to '#'
			else
				param_i = param:gsub ('%d+', '#');								-- for enumerated parameters, convert the enumerator digits to a single '#' character; all others unmolested
			end

			local param_is_valid;												-- boolean true when param is valid; nil else
			if template_t[2] then												-- if template is a preprint or uses unique parameters of 'document' parameters
				if 'document' == template_t[2] then								-- if a {{cite document}} template
					param_is_valid = validate_document_param (param_i, template_t[2]);
					if param_is_valid then
						if param_t['aliases'] then
							for _, alias in ipairs (param_t['aliases']) do
								local alias_i = alias:gsub ('%d+', '#');		-- in case an enumerated parameter, convert the enumerator digits to a single '#' character
								if not validate_document_param (alias_i, template_t[2]) then	-- is 'alias' a known parameter?
	 								table.insert (out, alias_error_msg (param, alias));			-- may be known but is not supported
								elseif cfg_aliases_t[param_i:gsub ('#', '')] ~= cfg_aliases_t[alias_i:gsub ('#', '')] then	-- is 'alias' known to be an alias of 'param'?
									table.insert (out, alias_error_msg (param, alias));
 								end
							end
						end
					else														-- here when param not valid preprint param
						table.insert (out, param_error_msg (param))
 					end
				elseif whitelist.preprint_arguments_t[template_t[2]] then			-- if a preprint template
					param_is_valid = validate_preprint_param (param_i, template_t[2]);
					if param_is_valid then
						if param_t['aliases'] then
							for _, alias in ipairs (param_t['aliases']) do
								local alias_i = alias:gsub ('%d+', '#');		-- in case an enumerated parameter, convert the enumerator digits to a single '#' character
								if not validate_preprint_param (alias_i, template_t[2]) then	-- is 'alias' a known parameter?
	 								table.insert (out, alias_error_msg (param, alias));			-- may be known but is not supported
								elseif cfg_aliases_t[param_i:gsub ('#', '')] ~= cfg_aliases_t[alias_i:gsub ('#', '')] then	-- is 'alias' known to be an alias of 'param'?
									table.insert (out, alias_error_msg (param, alias));
 								end
							end
						end
					else														-- here when param not valid preprint param
						table.insert (out, param_error_msg (param))
 					end
				elseif whitelist.unique_arguments_t[template_t[2]] then			-- if a unique parameters template
					param_is_valid = validate_unique_param (param_i, template_t[2]);
					if param_is_valid then
						if param_t['aliases'] then
							for _, alias in ipairs (param_t['aliases']) do
								local alias_i = alias:gsub ('%d+', '#');		-- in case an enumerated parameter, convert the enumerate digits to a single '#' character
								if not validate_unique_param (alias_i, template_t[2]) then	-- is 'alias' a known parameter?
									table.insert (out, alias_error_msg (param, alias));
								elseif cfg_aliases_t[param_i:gsub ('#', '')] ~= cfg_aliases_t[alias_i:gsub ('#', '')] then	-- is 'alias' known to be an alias of 'param'?
									table.insert (out, alias_error_msg (param, alias));
 								end
							end
						end
					else														-- here when param not valid unique parameter
						table.insert (out, param_error_msg (param))
 					end
				else															-- should never be here if coder is doing the right thing ...
					table.insert (out, 'internal error: unexpected keyword in templates_t: ' .. template_t[2]);
					break;
				end
			else																-- here when not unique or preprint
				param_is_valid = validate_basic_param (param_i);
				if param_is_valid then
					if param_t['aliases'] then
						for _, alias in ipairs (param_t['aliases']) do
							local alias_i = alias:gsub ('%d+', '#');			-- in case an enumerated parameter, convert the enumerate digits to a single '#' character
							if not validate_basic_param (alias_i) and not validate_id_alias (param, alias) then	-- for isbn13 (while still supported) must not mask the digits
 								table.insert (out, alias_error_msg (param, alias));
							elseif cfg_aliases_t[param_i:gsub ('#', '')] ~= cfg_aliases_t[alias_i:gsub ('#', '')] then	-- is 'alias' known to be an alias of 'param'?
								table.insert (out, alias_error_msg (param, alias));
 							end
						end
					end
				else															-- here when param not valid
					table.insert (out, param_error_msg (param))
 				end
			end
		end
	end

---------- this emits errors when page/pages/at listed in templatedata of templates that don't support those parameters ----------
--	if json_t then
--		if ({['citeavmedia']=true, ['citeepisode']=true, ['citemailinglist']=true, ['citenewsgroup']=true, ['citepodcast']=true, ['citeserial']=true, ['citesign']=true, ['citespeech']=true})[template_idx] then
--			local insource_params_t = {};										-- build sequence of pagination params not supported by these templates
--			for _, meta_param in ipairs ({'At', 'Page', 'Pages', 'QuotePage', 'QuotePages'}) do
--				if 'table' == type (cfg.aliases[meta_param]) then
--					for _, alias in ipairs (cfg.aliases[meta_param]) do			-- metaparameter is a sequence
--						table.insert (insource_params_t, alias);				-- add the aliases from the metaparameter sequence to the table
--					end
--				else															-- metaparameter is plain text
--					table.insert (insource_params_t, cfg.aliases[meta_param]);	-- add the alias to the table
--				end
--			end
--		
--			for _, param in ipairs (insource_params_t) do
--				if json_t.params[param] then
--					table.insert (out, param_error_msg (param));				-- error; this parameter not supported by this template
--				end
--			end
--		end
--	end
---------- end page/pages/at error detection ----------

	if 0 ~= #out then
		table.sort (out);
		out[1] = '*' .. out[1];													-- add a splat to the first error message

--		return table.concat ({'[[' .. template_doc .. ']] TemplateData has errors:<div style="color:#d33; font-style: normal">\n', table.concat (out, '\n*'), '</div>'});
		return table.concat ({
			'[[Template:' .. args_t[1] .. ']]  uses ',
			whitelist.preprint_arguments_t[template_t[2]] and 'preprint and limited parameter sets' or (whitelist.unique_arguments_t[template_t[2]] and 'unique and standard parameter sets' or 'standard parameter set'),
			'; TemplateData has errors:\n',
			'<div style="color:#d33; font-style: normal">\n', table.concat (out, '\n*'), '</div>'
			});
	else
		return;																	-- no errors detected; return nothing
	end
end


--[[--------------------------< E R R O R _ C A T _ P A G E _ T A L L Y >--------------------------------------

loop through Module:Citation/CS1/Configuration error_conditions {} fetching error category names.  For each error
category add the number of pages in the category to the tally.  Render the number when done.

{{#invoke:cs1 documentation support|error_cat_page_tally}}

]]

local function error_cat_page_tally ()
	local error_conditions_t = cfg.error_conditions;							-- get the table of error conditions
	local tally = 0;
	local cat_t = {};															-- some error message share a category; save tallied cats here so we don't recount the already counted
	local i = 0;																-- number of categories
	
	for k, v_t in pairs (error_conditions_t) do
		if k:match ('^err') then
			if not cat_t[v_t.category] then
				cat_t[v_t.category] = true;
				tally = tally +  mw.site.stats.pagesInCategory (v_t.category, 'pages');		-- get category page count; ignore subcats and files
				i = i + 1;
			end
		end
	end

	return mw.language.getContentLanguage():formatNum (tally)
end


--[[--------------------------< M A I N T _ C A T _ P A G E _ T A L L Y >--------------------------------------

loop through Module:Citation/CS1/Configuration error_conditions {} fetching error category names.  For each error
category add the number of pages in the category to the tally.  Render the number when done.

{{#invoke:cs1 documentation support|maint_cat_page_tally}}

Dynamic subcats of CS1 maint: DOI inactive not counted because these names come and go as time goes by.

]]

local function maint_cat_page_tally ()
	local error_conditions_t = cfg.error_conditions;							-- get the table of error conditions
	local tally = 0;
	local cat_t = {};															-- some error message share a category; save tallied cats here so we don't recount the already counted
	local i = 0;																-- number of categories
	
	for k, v_t in pairs (error_conditions_t) do
		if not k:match ('^err') then											-- if not an error key its a maint key
			if not cat_t[v_t.category] then
				cat_t[v_t.category] = true;
				if 'maint_mult_names' == k or 'maint_numeric_names' == k then
					local special_case_translation_t = cfg.special_case_translation;
					for _, name in ipairs ({'AuthorList', 'ContributorList', 'EditorList', 'InterviewerList', 'TranslatorList'}) do
						local cat_name = v_t.category:gsub ('$1', special_case_translation_t[name]);	-- replace $1 with translated list name
						tally = tally +  mw.site.stats.pagesInCategory (cat_name, 'pages');		-- get category page count; ignore subcats and files
						i = i + 1;
					end
				else	
					tally = tally +  mw.site.stats.pagesInCategory (v_t.category, 'pages');		-- get category page count; ignore subcats and files
					i = i + 1;
				end
			end
		end
	end

	return mw.language.getContentLanguage():formatNum (tally)
end


--[[--------------------------< U N C A T E G O R I Z E D _ N A M E S P A C E _ L I S T E R >------------------

For use in the Help:CS1 error §Notes

Get namespace names and identifiers from MediaWiki.  Make a human readable list of namespace names and identifiers
that cs1|2 does not categorize.

{{#invoke:cs1 documentation support|uncategorized_namespace_lister}}

For convenience, 
{{#invoke:cs1 documentation support|uncategorized_namespace_lister|all=<anything>}}

returns a list of all namespace names and identifiers used on the current wiki.  Any namespace with an
identifier less than 1, currently Mainspace (0), Special (-1), and Media (-2), is excluded from the list.

]]

local function uncategorized_namespace_lister (frame)
	local list_t = {};
	local function compare (a, b)												-- local function to sort namespaces numerically by the identifiers
		local a_num = tonumber (a:match ('%d+'));								-- get identifiers and convert to numbers
		local b_num = tonumber (b:match ('%d+'));
		return a_num < b_num;													-- do the comparison
	end
	
	for i, _ in pairs (mw.site.namespaces) do									-- for each namespace in the table
		if '' == frame.args.all or not frame.args.all then						-- when |all= not set, make a list of uncategorized namespaces
			if cfg.uncategorized_namespaces[i] then								-- if the identifier is listed in our uncategorized namespace list
				table.insert (list_t, table.concat ({mw.site.namespaces[i].name, ' (', i, ')'}))	-- add name and identifier to our local list
			end
		elseif 0 < i then														-- |all=<anything>: all namespace names and identifiers; ignore identifiers less than 1
			table.insert (list_t, table.concat ({'*', mw.site.namespaces[i].name, ' (', i, ')'}))	-- add name and identifier as an unordered list item
		end
	end
	
	table.sort (list_t, compare);												-- ascending numerical sort by identifier

	if not frame.args.all then													-- when |all= not set, format list of uncategorized namespaces and identifiers
		list_t[#list_t] = 'and ' .. list_t[#list_t];							-- add 'and ' to the last name/identifier pair
		return table.concat (list_t, ', ');										-- make a big string and done
	else																		-- make list of all namespaces and identifiers
		return table.concat (list_t, '\n');									-- make a big string and done
	end
end


--[[--------------------------< S I N G L E _ L T R _ 2 N D _ L V L _ D O M A I N  _ L I S T E R >-------------

for Help:CS1_errors#bad_url, list the supported top level domains that support single-letter 2nd level names

	{{#invoke:Module:cs1 documentation support|single_ltr_2nd_lvl_domain_lister}}

]]

local function single_ltr_2nd_lvl_domain_lister ()
	local out_t = {};															-- output goes here
	for _, tld in ipairs (cfg.single_letter_2nd_lvl_domains_t) do				-- fetch each tld
		table.insert (out_t, '.' .. tld);										-- prefix with a dot and save in out_t{}
	end
	return table.concat (out_t, ', ');											-- make a big string and done
end

	
--[[--------------------------< E X P O R T E D   F U N C T I O N S >------------------------------------------
]]

return {
	alias_lister = alias_lister,
	alias_names_get = alias_names_get,
	canonical_param_lister = canonical_param_lister,
	canonical_name_get = canonical_name_get,
	cat_lister = cat_lister,
	error_cat_page_tally = error_cat_page_tally,
	header_make = header_make,
	help_text_cats = help_text_cats,
	help_text_error_messages = help_text_error_messages,
	id_limits_get = id_limits_get,
	is_book_cite_template = is_book_cite_template,
	is_limited_param_template = is_limited_param_template,
	lang_lister = lang_lister,
	maint_cat_page_tally = maint_cat_page_tally,
	script_lang_lister = script_lang_lister,
	single_ltr_2nd_lvl_domain_lister = single_ltr_2nd_lvl_domain_lister,
	template_data_validate = template_data_validate,
	uncategorized_namespace_lister = uncategorized_namespace_lister,
	};