Module:Documentation

-- This module implements Documentation. -- -- @module documentation -- @alias p -- @release stable -- @require Module:Arguments -- @require Module:I18n -- @require Module:Message box -- @require Module:Yesno -- @require Module:Documentation/config -- @require Module:Documentation/i18n -- @author User:FishTank -- @author User:ExE Boss -- @attribution Module:Documentation (Wikipedia) -- @see Original module on Wikipedia -- @see w:c:portability:Template:Documentation

--

-- Get required modules. local getArgs = require('Dev:Arguments').getArgs local messageBox = require('Dev:Message box') local yesno = require('Dev:Yesno')

-- Get the config table. local cfg = mw.loadData('Dev:Documentation/config') local i18n = require('Dev:I18n').loadMessages('Documentation') local languages = require('Dev:Languages')

local p = {} p.i18n = i18n

-- Often-used functions. local ugsub = mw.ustring.gsub

-- -- -- Helper functions -- -- These are defined as local functions, but are made available in the p -- table for testing purposes. -- --

-- -- @function p.message -- Gets a message from the cfg table and formats it if appropriate. -- The function raises an error if the value from the cfg table is not -- of the type expectType. The default type for expectType is 'string'. -- If the table valArray is present, strings such as $1, $2 etc. in the -- message are substituted with values from the table keys [1], [2] etc. -- For example, if the message "foo-message" had the value 'Foo $2 bar $1.', -- message('foo-message', {'baz', 'qux'}) would return "Foo qux bar baz." -- local function message(cfgKey, valArray, expectType) local msg = cfg[cfgKey] expectType = expectType or 'string' if type(msg) ~= expectType then error('message: type error in message cfg.' .. cfgKey .. ' (' .. expectType .. ' expected, got ' .. type(msg) .. ')', 2)	end if not valArray then return msg end

local function getMessageVal(match) match = tonumber(match) return valArray[match] or error('message: no value found for key $' .. match .. ' in message cfg.' .. cfgKey, 4) end

local ret = ugsub(msg, '$([1-9][0-9]*)', getMessageVal) return ret end

p.message = message

local function makeWikilink(page, display) if display then return mw.ustring.format('%s', page, display) else return mw.ustring.format('%s', page) end end

p.makeWikilink = makeWikilink

local function makeUrlWikilink(page, display) -- This code prevents redlinks, but doesn't work for categories, and those -- are always blue-linked by the CategoryBlueLinks extension anyway. return mw.ustring.format('[%s %s]', tostring(mw.uri.fullUrl(page)), display or page) end

p.makeUrlWikilink = makeUrlWikilink

local function makeCategoryLink(cat, sort) local catns = mw.site.namespaces[14].name return makeWikilink(catns .. ':' .. cat, sort) end

p.makeCategoryLink = makeCategoryLink

local function makeUrlLink(url, display) return mw.ustring.format('[%s %s]', url, display) end

p.makeUrlLink = makeUrlLink

local function makeToolbar(...) local ret = {} local lim = select('#', ...) if lim < 1 then return nil end for i = 1, lim do		ret[#ret + 1] = select(i, ...) end return '(' .. table.concat(ret, ' &#124; ') .. ') ' end

p.makeToolbar = makeToolbar

-- -- @function p.resolveNamespace -- @param {int} subjectSpace -- @return {string} -- local function resolveNamespace(subjectSpace) if subjectSpace == 10 then -- Template namespace return 'template' elseif subjectSpace == 828 then -- Module namespace return 'module' elseif subjectSpace == 6 then -- File namespace return 'file' end return 'other' end

p.resolveNamespace = resolveNamespace;

-- -- -- Argument processing -- --

local function makeInvokeFunc(funcName) return function (frame) local args = getArgs(frame, {			valueFunc = function (key, value)				if type(value) == 'string' then					value = value:match('^%s*(.-)%s*$') -- Remove whitespace.					if key == 'heading' or value ~= '' then						return value					else						return nil					end				else					return value				end			end		}) return p[funcName](args) end end

-- -- -- Main function -- --

-- -- @function p.main -- This function defines logic flow for the module. -- -- ; Messages: -- : 'main-div-id' --> 'template-documentation' -- : 'main-div-classes' --> 'template-documentation iezoomfix' -- -- @param args - table of arguments passed by the user -- p.main = makeInvokeFunc('_main')

function p._main(args) local env = p.getEnvironment(args) local root = mw.html.create root :wikitext(p.protectionTemplate(env)) :wikitext(p.sandboxNotice(args, env)) -- This div tag is from documentation/start box, but moving it here -- so that we don't have to worry about unclosed tags. :tag('div') :attr('id', message('main-div-id')) :addClass(message('main-div-classes')) :newline :wikitext(p._startBox(args, env)) :wikitext(p._content(args, env)) :tag('div') :css('clear', 'both') -- So right or left floating items don't stick out of the doc box. :newline :done :done -- p._endBox(...) is mostly covered by p._content(...): :wikitext(p._endBox(args, env)) :wikitext(p.addTrackingCategories(env)) return tostring(root) end

-- -- -- Environment settings -- --

-- -- @type Environment -- -- ; Title objects include: -- @field Environment.title - the page we are making documentation for (usually the current title) -- @field Environment.templateTitle - the template (or module, file, etc.) -- @field Environment.docTitle - the /doc subpage. -- @field Environment.docTitleEn - the /doc/en subpage. -- @field Environment.sandboxTitle - the /sandbox subpage. -- @field Environment.testcasesTitle - the /testcases subpage. -- @field Environment.printTitle - the print version of the template, located at the /Print subpage. -- -- ; Data includes: -- @field Environment.protectionLevels - the protection levels table of the title object. -- @field Environment.subjectSpace - the number of the title's subject namespace. -- @field Environment.docSpace - the number of the namespace the title puts its documentation in. -- @field Environment.docpageBase - the text of the base page of the /doc, /sandbox and /testcases pages, with namespace. -- @field Environment.compareUrl - URL of the Special:ComparePages page comparing the sandbox with the template. -- -- @note All table lookups are passed through pcall so that errors are caught. -- If an error occurs, the value returned will be nil. --

-- -- @function p.getEnvironment -- -- Returns a table with information about the environment, including title objects and other namespace- or -- path-related data. -- -- @param args - table of arguments passed by the user -- @return {Environment} -- function p.getEnvironment(args) local env, envFuncs = {}, {}

-- Set up the metatable. If triggered we call the corresponding function in the envFuncs table. The value -- returned by that function is memoized in the env table so that we don't call any of the functions -- more than once. (Nils won't be memoized.) setmetatable(env, {		__index = function (t, key)			local envFunc = envFuncs[key]			if envFunc then				local success, val = pcall(envFunc)				if success then					env[key] = val -- Memoise the value.					return val				end			end			return nil		end	})

-- The title object for the current page, or a test page passed with args.page. function envFuncs.title local title local titleArg = args.page if titleArg then title = mw.title.new(titleArg) else title = mw.title.getCurrentTitle end return title end

-- The template (or module, etc.) title object. -- ; Messages: -- : 'sandbox-subpage' --> 'sandbox' -- : 'testcases-subpage' --> 'testcases' function envFuncs.templateTitle local subjectSpace = env.subjectSpace local title = env.title local subpage = title.subpageText if subpage == message('sandbox-subpage') or subpage == message('testcases-subpage') then return mw.title.makeTitle(subjectSpace, title.baseText) else return mw.title.makeTitle(subjectSpace, title.text) end end

-- Title object of the /doc subpage. -- ; Messages: -- : 'doc-subpage' --> 'doc' function envFuncs.docTitle local docname = args[1] -- User-specified doc page. local docpage if docname then docpage = docname else docpage = env.docpageBase .. '/' .. message('doc-subpage') end return mw.title.new(docpage) end

-- Title object of the /doc/en subpage. function envFuncs.docTitleEn local docTitle = env.docTitle return mw.title.new(docTitle.text .. '/en', docTitle.nsText) end

function envFuncs.subpages local docTitle = env.docTitle return languages.subpages(docTitle.text, docTitle.nsText) end

function envFuncs.hasSubpages local subpages = env.subpages return #subpages > 1 or subpages[1] ~= '' end

function envFuncs.docTitleCreate local hasSubpages = env.hasSubpages local docTitle = env.docTitle local docTitleEn = env.docTitleEn local forceI18n = yesno(args.i18n) if (forceI18n or hasSubpages) and (docTitleEn.exists or not docTitle.exists) then return docTitleEn end return docTitle end

function envFuncs.docTitleCurrentLang local currentLang = mw.getCurrentFrame:preprocess('') if currentLang == 'en' then return env.docTitleCreate else local docTitle = env.docTitle return mw.title.new(docTitle.text .. '/' .. currentLang, docTitle.nsText) end end

-- Title object for the /sandbox subpage. -- ; Messages: -- : 'sandbox-subpage' --> 'sandbox' function envFuncs.sandboxTitle if message('sandbox-notice-testcases-show') then return mw.title.new(env.docpageBase .. '/' .. message('sandbox-subpage')) end end

-- Title object for the /testcases subpage. -- ; Messages: -- : 'testcases-subpage' --> 'testcases' function envFuncs.testcasesTitle if message('sandbox-subpage-show') then return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) end end

-- Title object for the /Print subpage. -- ; Messages: -- : 'print-subpage' --> 'Print' function envFuncs.printTitle if message('print-show') then return env.templateTitle:subPageTitle(message('print-subpage')) end end

-- The protection levels table of the title object. function envFuncs.protectionLevels return env.title.protectionLevels end

-- The subject namespace number. function envFuncs.subjectSpace return mw.site.namespaces[env.title.namespace].subject.id	end

-- The documentation namespace number. For most namespaces this is the same as the -- subject namespace. However, pages in the Article, File, MediaWiki or Category -- namespaces must have their /doc, /sandbox and /testcases pages in talk space. function envFuncs.docSpace local subjectSpace = env.subjectSpace if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then return subjectSpace + 1 else return subjectSpace end end

-- The base page of the /doc, /sandbox, and /testcases subpages. -- For some namespaces this is the talk page, rather than the template page. function envFuncs.docpageBase local templateTitle = env.templateTitle local docSpace = env.docSpace local docSpaceText = mw.site.namespaces[docSpace].name -- Assemble the link. docSpace is never the main namespace, so we can hardcode the colon. return docSpaceText .. ':' .. templateTitle.text end

-- Diff link between the sandbox and the main template using Special:ComparePages. function envFuncs.compareUrl local templateTitle = env.templateTitle local sandboxTitle = env.sandboxTitle if templateTitle.exists and sandboxTitle.exists then local compareUrl = mw.uri.fullUrl(				'Special:ComparePages',				{page1 = templateTitle.prefixedText, page2 = sandboxTitle.prefixedText}			) return tostring(compareUrl) else return nil end end

function envFuncs.docStatus local docTitle = env.docTitle if not args.content then if not docTitle.exists and not env.hasSubpages then return 'nodoc' elseif not docTitle.exists and not env.docTitleEn.exists and env.hasSubpages then return 'baddoc' end end end

function envFuncs.docIcon local docStatus = env.docStatus if not docStatus then return message('documentation-icon') end return message('documentation-icon-' .. docStatus) end

return env end

-- -- -- Auxiliary templates -- --

--- -- @function p.sandboxNotice -- Generates a sandbox notice for display above sandbox pages. -- -- ; Messages: -- : 'sandbox-notice-image' --> '' -- : 'sandbox-notice-blurb' --> 'This is the $1 for $2.' -- : 'sandbox-notice-diff-blurb' --> 'This is the $1 for $2 ($3).' -- : 'sandbox-notice-pagetype-template' --> 'template sandbox page' -- : 'sandbox-notice-pagetype-module' --> 'module sandbox page' -- : 'sandbox-notice-pagetype-other' --> 'sandbox page' -- : 'sandbox-notice-compare-link-display' --> 'diff' -- : 'sandbox-notice-testcases-blurb' --> 'See also the companion subpage for $1.' -- : 'sandbox-notice-testcases-link-display' --> 'test cases' -- : 'sandbox-category' --> 'Template sandboxes' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment function p.sandboxNotice(args, env) local title = env.title local sandboxTitle = env.sandboxTitle local templateTitle = env.templateTitle local subjectSpace = env.subjectSpace if not (subjectSpace and title and sandboxTitle and templateTitle and mw.title.equals(title, sandboxTitle)) then return nil end -- Build the table of arguments to pass to ombox. We need just two fields, "image" and "text". local omargs = {} omargs.image = message('sandbox-notice-image') -- Get the text. We start with the opening blurb, which is something like -- "This is the template sandbox for Template:Foo (diff)." local text = '' local frame = mw.getCurrentFrame local isPreviewing = frame:preprocess() ==  -- True if the page is being previewed. local pagetype if subjectSpace == 10 then pagetype = message('sandbox-notice-pagetype-template') elseif subjectSpace == 828 then pagetype = message('sandbox-notice-pagetype-module') else pagetype = message('sandbox-notice-pagetype-other') end local templateLink = makeUrlWikilink(templateTitle.prefixedText) local compareUrl = env.compareUrl if isPreviewing or not compareUrl then text = text .. message('sandbox-notice-blurb', {pagetype, templateLink}) else local compareDisplay = message('sandbox-notice-compare-link-display') local compareLink = makeUrlLink(compareUrl, compareDisplay) text = text .. message('sandbox-notice-diff-blurb', {pagetype, templateLink, compareLink}) end -- Get the test cases page blurb if the page exists. This is something like -- "See also the companion subpage for test cases." local testcasesTitle = env.testcasesTitle if testcasesTitle and testcasesTitle.exists then if testcasesTitle.namespace == mw.site.namespaces.Module.id then local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display') local testcasesRunLinkDisplay = message('sandbox-notice-testcases-run-link-display') local testcasesLink = makeUrlWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay) local testcasesRunLink = makeUrlWikilink(testcasesTitle.talkPageTitle.prefixedText, testcasesRunLinkDisplay) text = text .. ' ' .. message('sandbox-notice-testcases-run-blurb', {testcasesLink, testcasesRunLink}) else local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display') local testcasesLink = makeUrlWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay) text = text .. ' ' .. message('sandbox-notice-testcases-blurb', {testcasesLink}) end end -- Add the sandbox to the sandbox category. text = text .. makeCategoryLink(message('sandbox-category')) omargs.text = text local ret = ' ' ret = ret .. messageBox.main('ombox', omargs) return ret end

-- -- @function p.protectionTemplate -- Generates the padlock icon in the top right. -- -- ; Messages: -- : 'protection-template' --> 'pp-template' -- : 'protection-template-args' --> {docusage = 'yes'} -- -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.protectionTemplate(env) local protectionLevels, mProtectionBanner local title = env.title if title.namespace ~= 10 and title.namespace ~= 828 then -- Don't display the protection template if we are not in the template or module namespaces. return nil end protectionLevels = env.protectionLevels if not protectionLevels then return nil end local editProt = protectionLevels.edit and protectionLevels.edit[1] local moveProt = protectionLevels.move and protectionLevels.move[1] if editProt then -- The page is edit-protected. mProtectionBanner = require('Module:Protection banner') local reason = message('protection-reason-edit') return mProtectionBanner._main{reason, small = true} elseif moveProt and moveProt ~= 'autoconfirmed' then -- The page is move-protected but not edit-protected. Exclude move -- protection with the level "autoconfirmed", as this is equivalent to -- no move protection at all. mProtectionBanner = require('Module:Protection banner') return mProtectionBanner._main{action = 'move', small = true} else return nil end end

-- -- -- Start box -- --

-- -- @function p.startBox -- This function generates the start box. -- -- The actual work is done by p.makeStartBoxLinksData and p.renderStartBoxLinks which make -- the [view] [edit] [history] [purge] links, and by p.makeStartBoxData and p.renderStartBox -- which generate the box HTML. -- -- @param args - a table of arguments passed by the user -- @param[opt] env - environment table containing title objects, etc., generated with p.getEnvironment -- p.startBox = makeInvokeFunc('_startBox')

function p._startBox(args, env) env = env or p.getEnvironment(args) local links local content = args.content if not content then -- No need to include the links if the documentation is on the template page itself. local linksData = p.makeStartBoxLinksData(args, env) if linksData then links = p.renderStartBoxLinks(linksData) end end -- Generate the start box html. local data = p.makeStartBoxData(args, env, links) if data then return p.renderStartBox(data) else -- User specified no heading. return nil end end

-- -- @function p.makeStartBoxLinksData -- Does initial processing of data to make the [view] [edit] [history] [purge] links. -- -- ; Messages: -- : 'file-docpage-preload' --> 'Template:Documentation/preload-filespace' -- : 'module-preload' --> 'Template:Documentation/preload-module-doc' -- : 'docpage-preload' --> 'Template:Documentation/preload' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.makeStartBoxLinksData(args, env) local subjectSpace = env.subjectSpace local title = env.title local docTitleCurrentLang = env.docTitleCurrentLang if not title or not docTitleCurrentLang then return nil end

local frame = mw.getCurrentFrame local data = {} data.title = title data.docTitle = docTitleCurrentLang -- View, display, edit, and purge links if /doc exists. data.viewLinkDisplay = frame:preprocess('') data.editLinkDisplay = frame:preprocess('') data.historyLinkDisplay = frame:preprocess('') data.purgeLinkDisplay = frame:preprocess('') -- Create link if /doc doesn't exist. local preload = args.preload if not preload then if subjectSpace == 6 then -- File namespace preload = message('file-docpage-preload') elseif subjectSpace == 828 then -- Module namespace preload = message('module-preload') else preload = message('docpage-preload') end end data.preload = preload data.createLinkDisplay = frame:preprocess('') return data end

-- -- @function p.renderStartBoxLinks -- Generates the [view][edit][history][purge] or [create] links from the data table. -- -- @param data - a table of data generated by p.makeStartBoxLinksData -- function p.renderStartBoxLinks(data) local function escapeBrackets(s) -- Escapes square brackets with HTML entities. s = s:gsub('%[', '&#91;') -- Replace square brackets with HTML entities. s = s:gsub('%]', '&#93;') return s	end

local ret local docTitle = data.docTitle local title = data.title if docTitle.exists then local viewLink = makeWikilink(docTitle.prefixedText, data.viewLinkDisplay) local editLink = makeUrlLink(docTitle:fullUrl({ action = 'edit' }, 'https'), data.editLinkDisplay) local historyLink = makeUrlLink(docTitle:fullUrl({ action = 'history' }, 'https'), data.historyLinkDisplay) local purgeLink = makeUrlLink(title:fullUrl({ action = 'purge' }, 'https'), data.purgeLinkDisplay) ret = '[%s] [%s] [%s] [%s]' ret = escapeBrackets(ret) ret = mw.ustring.format(ret, viewLink, editLink, historyLink, purgeLink) else local createLink = makeUrlLink(docTitle:fullUrl({ action = 'edit', redlink = '1', preload = data.preload, }, 'https'), data.createLinkDisplay) ret = '[%s]' ret = escapeBrackets(ret) ret = mw.ustring.format(ret, createLink) end return ret end

--- -- @function p.makeStartBoxData -- Does initial processing of data to pass to the start-box render function, p.renderStartBox. -- -- ; Messages: -- : 'documentation-icon-wikitext' --> '' -- : 'documentation-icon' --> 'Template-info.svg' -- : 'documentation-icon-nodoc' --> 'Template-noinfo.svg' -- : 'documentation-icon-baddoc' --> 'Template-badinfo.svg' -- : 'start-box-linkclasses' --> 'mw-editsection-like plainlinks' -- : 'start-box-link-id' --> 'doc_editlinks' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- @param links - a string containing the [view][edit][history][purge] links - could be nil if there's an error. function p.makeStartBoxData(args, env, links) local subjectSpace = env.subjectSpace if not subjectSpace then -- Default to an "other namespaces" namespace, so that we get at least some output -- if an error occurs. subjectSpace = 2 end local data = {} -- Heading local heading = args.heading -- Blank values are not removed. if heading == '' then -- Don't display the start box if the heading arg is defined but blank. return nil end

if heading then data.heading = heading elseif subjectSpace == 10 then -- Template namespace data.heading = message('documentation-icon-wikitext', {env.docIcon}) .. ' ' .. i18n:msg('documentation-heading') data.subHeading = i18n:msg('documentation-visibility') elseif subjectSpace == 828 then -- Module namespace data.heading = message('documentation-icon-wikitext', {env.docIcon}) .. ' ' .. i18n:msg('module-namespace-heading') elseif subjectSpace == 6 then -- File namespace data.heading = i18n:msg('file-namespace-heading') else data.heading = i18n:msg('other-namespaces-heading') end -- Heading CSS local headingStyle = args['heading-style'] if headingStyle then data.headingStyleText = headingStyle elseif subjectSpace == 10 then -- We are in the template or template talk namespaces. data.headingFontWeight = 'bold' data.headingFontSize = '125%' else data.headingFontSize = '150%' end -- Data for the [view][edit][history][purge] or [create] links. if links then data.linksClass = message('start-box-linkclasses') data.linksId = message('start-box-link-id') data.links = links end return data end

-- -- @function p.renderStartBox -- Renders the start box html. -- -- ; Messages -- : 'start-box-div-classes' --> 'template-documentation-header' -- -- @param data - a table of data generated by p.makeStartBoxData. -- function p.renderStartBox(data) local sbox = mw.html.create('div') sbox :addClass(message('start-box-div-classes')) :newline :tag('span') :cssText(data.headingStyleText) :css('font-weight', data.headingFontWeight) :css('font-size', data.headingFontSize) :wikitext(data.heading) local links = data.links if links then sbox :tag('div') :css('font-size', data.headingFontSize) :css('float', 'right') :tag('span') :addClass(data.linksClass) :attr('id', data.linksId) :wikitext(links) end local subHeading = data.subHeading if subHeading then sbox :tag('br') :css('clear', 'right') sbox :tag('i') :wikitext(subHeading) end return tostring(sbox) end

-- -- -- Documentation content -- --

-- -- @function p.content -- Displays the documentation contents -- -- ; Messages -- : 'content-box-div-classes' --> 'template-documentation-content' -- -- @param args - a table of arguments passed by the user -- @param[opt] env - environment table containing title objects, etc., generated with p.getEnvironment -- p.content = makeInvokeFunc('_content')

function p._content(args, env) env = env or p.getEnvironment(args) local docTitle = env.docTitle local content = args.content local root = mw.html.create if not content and docTitle then local subjectSpace = env.subjectSpace local preload = args.preload if not preload then if subjectSpace == 6 then -- File namespace preload = message('file-docpage-preload') elseif subjectSpace == 828 then -- Module namespace preload = message('module-preload') else preload = message('docpage-preload') end end

local hasSubpages = env.hasSubpages local docTitleCreate = env.docTitleCreate

local docMissing = i18n:msg(			resolveNamespace(subjectSpace) .. '-documentation-missing',			docTitleCreate:fullUrl({ action = 'edit', redlink = '1', preload = mw.uri.encode(preload, 'WIKI'), }, 'https'):gsub('%%', '%%%%')		)

if not docTitle.exists and not hasSubpages then content = docMissing else if yesno(args.i18n, false) or hasSubpages then local currentLang = mw.getCurrentFrame:preprocess('') root:node(languages.langs{					'en',					currentLang,					format = 'list',					page = docTitle.prefixedText,					class = message('languages-list-div-classes'),					select = currentLang,					editintro = 'Template:Documentation/editintro',				}) end

content = args._content or tostring(languages.langs{				format = 'transclude',				page = docTitle.prefixedText,				notice = 'bottom',				missing = docMissing,			}) end end local cbox = root:tag('div') cbox :addClass(message('content-box-div-classes')) -- The line breaks are necessary so that "=== Headings ===" at the start -- and end of docs are interpreted correctly. :wikitext(mw.getCurrentFrame:expandTemplate{title = 'tocright'}) :newline :wikitext(content or '') :newline return tostring(root) end

-- -- @function p.contentTitle -- Gets the content title -- -- @param args - a table of arguments passed by the user -- @param[opt] env - environment table containing title objects, etc., generated with p.getEnvironment -- p.contentTitle = makeInvokeFunc('_contentTitle')

function p._contentTitle(args, env) env = env or p.getEnvironment(args) local docTitle = env.docTitle if not args.content and docTitle and docTitle.exists then return docTitle.prefixedText else return '' end end

-- -- -- End box -- --

--- -- @function p.endBox -- This function generates the end box (also known as the link box). -- -- The HTML is generated by the fmbox template, courtesy of Module:Message box. -- -- ; Messages: -- : 'fmbox-id' --> 'documentation-meta-data' -- : 'fmbox-style' --> 'background-color: #ecfcf4' -- : 'fmbox-textstyle' --> 'font-style: italic' -- -- @param args - a table of arguments passed by the user -- @param[opt] env - environment table containing title objects, etc., generated with p.getEnvironment p.endBox = makeInvokeFunc('_endBox')

function p._endBox(args, env) -- Get environment data. env = env or p.getEnvironment(args) local subjectSpace = env.subjectSpace local docTitle = env.docTitle if not subjectSpace or not docTitle then return nil end

-- Check whether we should output the end box at all. Add the end -- box by default if the documentation exists or if we are in the -- user, module or template namespaces. local linkBox = args['link box'] if not yesno(linkBox, true) --[=[		-- Disabled by default because it's mostly covered -- by Module:Languages.langs. or not (			docTitle.exists			or subjectSpace == 2			or subjectSpace == 828			or subjectSpace == 10		) --]=]	then return nil end

-- Assemble the arguments for fmbox. local fmargs = {} fmargs.id = message('fmbox-id') -- Sets 'documentation-meta-data' fmargs.image = 'none' fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4' fmargs.textstyle = message('fmbox-textstyle') -- 'font-style: italic;'

-- Assemble the fmbox text field. local text = '' if linkBox and yesno(linkBox) == nil then text = text .. linkBox else text = text .. (p.makeDocPageBlurb(args, env) or '') -- "This documentation is transcluded from Foo." if subjectSpace == 2 or subjectSpace == 10 or subjectSpace == 828 then -- We are in the user, template or module namespaces. -- Add sandbox and testcases links. -- "Editors can experiment in this template's sandbox and testcases pages." text = text .. (p.makeExperimentBlurb(args, env) or '') text = text .. ' '			if not args.content and not args[1] then -- "Please add categories to the /doc subpage." -- Don't show this message with inline docs or with an explicitly specified doc page, -- as then it is unclear where to add the categories. text = text .. (p.makeCategoriesBlurb(args, env) or '') end text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '') --"Subpages of this template" local printBlurb = p.makePrintBlurb(args, env) -- Two-line blurb about print versions of templates. if printBlurb then text = text .. ' ' .. printBlurb end end end fmargs.text = text

return messageBox.main('fmbox', fmargs) end

--- -- @function p.makeDocPageBlurb -- Makes the blurb "This documentation is transcluded from Template:Foo (edit, history)". -- -- ; Messages: -- : 'edit-link-display' --> 'edit' -- : 'history-link-display' --> 'history' -- : 'transcluded-from-blurb' --> --  'The above documentation --   is transcluded from $1.' -- : 'module-preload' --> 'Template:Documentation/preload-module-doc' -- : 'create-link-display' --> 'create' -- : 'create-module-doc-blurb' --> --  'You might want to $1 a documentation page for this Scribunto module.' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment function p.makeDocPageBlurb(args, env) local docTitle = env.docTitle if not docTitle then return nil end local ret if docTitle.exists then -- /doc exists; link to it. local docLink = makeWikilink(docTitle.prefixedText) local editUrl = docTitle:fullUrl({ action = 'edit' }, 'https') local editDisplay = message('edit-link-display') local editLink = makeUrlLink(editUrl, editDisplay) local historyUrl = docTitle:fullUrl({ action = 'history' }, 'https') local historyDisplay = message('history-link-display') local historyLink = makeUrlLink(historyUrl, historyDisplay) ret = message('transcluded-from-blurb', {docLink}) .. ' '			.. makeToolbar(editLink, historyLink) .. ' '	elseif env.subjectSpace == 828 then -- /doc does not exist; ask to create it. local createUrl = docTitle:fullUrl({			action = 'edit',			redlink = '1',			preload = message('module-preload'),		}, 'https') local createDisplay = message('create-link-display') local createLink = makeUrlLink(createUrl, createDisplay) ret = message('create-module-doc-blurb', {createLink}) .. ' '	end return ret end

-- diff) and testcases (edit) pages." -- -- ; Messages: -- : 'sandbox-link-display' --> 'sandbox' -- : 'sandbox-edit-link-display' --> 'edit' -- : 'compare-link-display' --> 'diff' -- : 'module-sandbox-preload' --> 'Template:Documentation/preload-module-sandbox' -- : 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox' -- : 'sandbox-create-link-display' --> 'create' -- : 'mirror-edit-summary' --> 'Create sandbox version of $1' -- : 'mirror-link-display' --> 'mirror' -- : 'mirror-link-preload' --> 'Template:Documentation/mirror' -- : 'sandbox-link-display' --> 'sandbox' -- : 'testcases-link-display' --> 'testcases' -- : 'testcases-edit-link-display'--> 'edit' -- : 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox' -- : 'testcases-create-link-display' --> 'create' -- : 'testcases-link-display' --> 'testcases' -- : 'testcases-edit-link-display' --> 'edit' -- : 'module-testcases-preload' --> 'Template:Documentation/preload-module-testcases' -- : 'template-testcases-preload' --> 'Template:Documentation/preload-testcases' -- : 'experiment-blurb-module' --> 'Editors can experiment in this module's $1 and $2 pages.' -- : 'experiment-blurb-template' --> 'Editors can experiment in this template's $1 and $2 pages.' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.makeExperimentBlurb(args, env) local subjectSpace = env.subjectSpace local templateTitle = env.templateTitle local sandboxTitle = env.sandboxTitle local testcasesTitle = env.testcasesTitle local templatePage = templateTitle.prefixedText if not subjectSpace or not templateTitle or not sandboxTitle or not testcasesTitle then return nil end -- Make links. local sandboxLinks, testcasesLinks if sandboxTitle.exists then local sandboxPage = sandboxTitle.prefixedText local sandboxDisplay = message('sandbox-link-display') local sandboxLink = makeUrlWikilink(sandboxPage, sandboxDisplay) local sandboxEditUrl = sandboxTitle:fullUrl({ action = 'edit' }, 'https') local sandboxEditDisplay = message('sandbox-edit-link-display') local sandboxEditLink = makeUrlLink(sandboxEditUrl, sandboxEditDisplay) local compareUrl = env.compareUrl local compareLink if compareUrl then local compareDisplay = message('compare-link-display') compareLink = makeUrlLink(compareUrl, compareDisplay) end sandboxLinks = sandboxLink .. ' ' .. makeToolbar(sandboxEditLink, compareLink) else local sandboxPreload if subjectSpace == 828 then sandboxPreload = message('module-sandbox-preload') else sandboxPreload = message('template-sandbox-preload') end local sandboxCreateUrl = sandboxTitle:fullUrl({			action = 'edit',			redlink = '1',			preload = sandboxPreload,		}, 'https') local sandboxCreateDisplay = message('sandbox-create-link-display') local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay) local mirrorSummary = message('mirror-edit-summary', {makeUrlWikilink(templatePage)}) local mirrorPreload = message('mirror-link-preload') local mirrorUrl = sandboxTitle:fullUrl({			action = 'edit',			redlink = '1',			preload = mirrorPreload,			summary = mirrorSummary,		}, 'https') local mirrorDisplay = message('mirror-link-display') local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay) sandboxLinks = message('sandbox-link-display') .. ' ' .. makeToolbar(sandboxCreateLink, mirrorLink) end if testcasesTitle.exists then local testcasesPage = testcasesTitle.prefixedText local testcasesDisplay = message('testcases-link-display') local testcasesLink = makeUrlWikilink(testcasesPage, testcasesDisplay) local testcasesEditUrl = testcasesTitle:fullUrl({ action = 'edit' }, 'https') local testcasesEditDisplay = message('testcases-edit-link-display') local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay) testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink) else local testcasesPreload if subjectSpace == 828 then testcasesPreload = message('module-testcases-preload') else testcasesPreload = message('template-testcases-preload') end local testcasesCreateUrl = testcasesTitle:fullUrl({			action = 'edit',			redlink = '1',			preload = testcasesPreload,		}, 'https') local testcasesCreateDisplay = message('testcases-create-link-display') local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay) testcasesLinks = message('testcases-link-display') .. ' ' .. makeToolbar(testcasesCreateLink) end local messageName if subjectSpace == 828 then messageName = 'experiment-blurb-module' else messageName = 'experiment-blurb-template' end return message(messageName, {sandboxLinks, testcasesLinks}) end

-- -- @function p.makeCategoriesBlurb -- Generates the text "Please add categories to the /doc subpage." -- -- ; Messages: -- : 'doc-link-display' --> '/doc' -- : 'add-categories-blurb' --> 'Please add categories to the $1 subpage.' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.makeCategoriesBlurb(args, env) local docTitle = env.docTitle if not docTitle then return nil end local docPathLink = makeUrlWikilink(docTitle.prefixedText, message('doc-link-display')) return message('add-categories-blurb', {docPathLink}) end

-- -- @function p.makeSubpagesBlurb -- Generates the "Subpages of this template" link. -- -- ; Messages: -- : 'template-pagetype' --> 'template' -- : 'module-pagetype' --> 'module' -- : 'default-pagetype' --> 'page' -- : 'subpages-link-display' --> 'Subpages of this $1' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.makeSubpagesBlurb(args, env) local subjectSpace = env.subjectSpace local templateTitle = env.templateTitle if not subjectSpace or not templateTitle then return nil end local pagetype if subjectSpace == 10 then pagetype = message('template-pagetype') elseif subjectSpace == 828 then pagetype = message('module-pagetype') else pagetype = message('default-pagetype') end local subpagesLink = makeWikilink(		'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/',		message('subpages-link-display', {pagetype})	) return message('subpages-blurb', {subpagesLink}) end

--- -- @function p.makePrintBlurb -- Generates the blurb displayed when there is a print version of the template available. -- -- ; Messages: -- : 'print-link-display' --> '/Print' -- : 'print-blurb' --> 'A print version' --		.. ' of this template exists at $1.' --		.. ' If you make a change to this template, please update the print version as well.' -- : 'display-print-category' --> true -- : 'print-category' --> 'Templates with print versions' -- -- @param args - a table of arguments passed by the user -- @param env - environment table containing title objects, etc., generated with p.getEnvironment function p.makePrintBlurb(args, env) local printTitle = env.printTitle if not printTitle then return nil end local ret if printTitle.exists then local printLink = makeWikilink(printTitle.prefixedText, message('print-link-display')) ret = message('print-blurb', {printLink}) local displayPrintCategory = message('display-print-category', nil, 'boolean') if displayPrintCategory then ret = ret .. makeCategoryLink(message('print-category')) end end return ret end

-- -- -- Tracking categories -- --

-- -- @function p.addTrackingCategories -- Check if documentation is transcluded on a /doc or /testcases page. -- -- ; Messages: -- : 'display-strange-usage-category' --> true -- : 'doc-subpage' --> 'doc' -- : 'testcases-subpage' --> 'testcases' -- : 'strange-usage-category' --> 'Pages with strange ((documentation)) usage' -- : 'nodoc-category-template' --> 'Templates with no documentation' -- : 'nodoc-category-module' --> 'Modules with no documentation' -- : 'nodoc-category-file' --> 'Files with no summary' -- : 'nodoc-category-other' --> 'Pages with no documentation' -- : 'baddoc-category-template' --> 'Templates with bad documentation' -- : 'baddoc-category-module' --> 'Modules with bad documentation' -- : 'baddoc-category-file' --> 'Files with bad summary' -- : 'baddoc-category-other' --> 'Pages with bad documentation' -- -- /testcases pages in the module namespace are not categorised, as they may have -- documentation transcluded automatically. -- -- @param env - environment table containing title objects, etc., generated with p.getEnvironment -- function p.addTrackingCategories(env) local title = env.title local subjectSpace = env.subjectSpace if not title or not subjectSpace then return nil end local subpage = title.subpageText local ret = '' if message('display-strange-usage-category', nil, 'boolean') and (			subpage == message('doc-subpage')			or subjectSpace ~= 828 and subpage == message('testcases-subpage')		) then ret = ret .. makeCategoryLink(message('strange-usage-category')) end local docStatus = env.docStatus if docStatus then ret = ret .. makeCategoryLink(message(docStatus .. '-category-' .. resolveNamespace(subjectSpace))) end return ret end

return p --