Module:Documentation

-- 这个模块实现 {{documentation}} 模板。

-- 获取所需的模块。
local getArgs = require('Module:Arguments').getArgs
local messageBox = require('Module:Message box')

-- 获取配置表。
local cfg = mw.loadData('Module:Documentation/config')
local i18n = mw.loadData('Module:Documentation/i18n')
local p = {}

-- 常用函数。
local ugsub = mw.ustring.gsub

----------------------------------------------------------------------------
-- 辅助函数
--
-- 这些函数定义为局部函数，但为了测试目的在 p 表中可用。
----------------------------------------------------------------------------

local function message(cfgKey, valArray, expectType)
	--[[
	-- 从配置表中获取消息并在适当时格式化。
	-- 如果配置表中的值不是 expectType 类型，函数会报错。expectType 的默认类型是 'string'。
	-- 如果存在 valArray 表，消息中的 $1、$2 等字符串会被替换为表中 [1]、[2] 等键的值。
	-- 例如，如果消息 "foo-message" 的值为 'Foo $2 bar $1.'，
	-- message('foo-message', {'baz', 'qux'}) 将返回 "Foo qux bar baz."
	--]]
	local msg = cfg[cfgKey]
	expectType = expectType or 'string'
	if type(msg) ~= expectType then
		error(require('Module:TNT').format('I18n/Documentation', 'cfg-error-msg-type', cfgKey, expectType, type(msg)), 2)
	end
	if not valArray then
		return msg
	end

	local function getMessageVal(match)
		match = tonumber(match)
		return valArray[match] or error(require('Module:TNT').format('I18n/Documentation', 'cfg-error-msg-empty', '$' .. match, 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|%s]]', page, display)
	else
		return mw.ustring.format('[[%s]]', page)
	end
end

p.makeWikilink = makeWikilink

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)
	-- 创建URL链接
	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 '<small style="font-style: normal;">(' .. table.concat(ret, ' &#124; ') .. ')</small>'
end	

p.makeToolbar = makeToolbar

----------------------------------------------------------------------------
-- 参数处理
----------------------------------------------------------------------------

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*$') -- 移除空白字符
					if key == 'heading' or value ~= '' then
						return value
					else
						return nil
					end
				else
					return value
				end
			end
		})
		return p[funcName](args)
	end
end

----------------------------------------------------------------------------
-- 加载模板样式
----------------------------------------------------------------------------

p.main = function(frame)
	-- 主函数，处理模板调用
	local parent = frame.getParent(frame)
	local output = p._main(parent.args)
	return frame:extensionTag{ name='templatestyles', args = { src= message('templatestyles-scr') } } .. output
end

----------------------------------------------------------------------------
-- 主逻辑函数
----------------------------------------------------------------------------

function p._main(args)
	--[[
	-- 这个函数定义了模块的逻辑流程。
	-- @args - 用户传递的参数表
	-- 
	-- 消息：
	-- 'main-div-id' --> 'template-documentation'
	-- 'main-div-classes' --> 'template-documentation iezoomfix'
	--]]
	local env = p.getEnvironment(args)
	local root = mw.html.create()
	root
		:wikitext(p._getModuleWikitext(args, env))
		:wikitext(p.protectionTemplate(env))
		:wikitext(p.sandboxNotice(args, env))
			 -- 这个 div 标签来自 {{documentation/start box}}，但移到这里
			 -- 这样我们就不必担心未闭合的标签。
			:tag('div')
				:attr('id', message('main-div-id'))
				:addClass(message('main-div-class'))
				:wikitext(p._startBox(args, env))
				:wikitext(p._content(args, env))
				:done()
			:wikitext(p._endBox(args, env))
			:wikitext(p.addTrackingCategories(env))
	return tostring(root)
end

----------------------------------------------------------------------------
-- 环境设置
----------------------------------------------------------------------------

function p.getEnvironment(args)
	--[[
	-- 返回包含环境信息的表，包括标题对象和其他命名空间或路径相关数据。
	-- @args - 用户传递的参数表
	--
	-- 标题对象包括：
	-- env.title - 我们为其制作文档的页面（通常是当前标题）
	-- env.templateTitle - 模板（或模块、文件等）
	-- env.docTitle - /doc 子页面
	-- env.sandboxTitle - /sandbox 子页面
	-- env.testcasesTitle - /testcases 子页面
	-- env.printTitle - 模板的打印版本，位于 /Print 子页面
	--
	-- 数据包括：
	-- env.protectionLevels - 标题对象的保护级别表
	-- env.subjectSpace - 标题主题命名空间的编号
	-- env.docSpace - 标题放置其文档的命名空间编号
	-- env.docpageBase - /doc、/sandbox 和 /testcases 页面的基础页面文本，包含命名空间
	-- env.compareUrl - 比较沙盒与模板的 Special:ComparePages 页面 URL
	-- 
	-- 所有表查找都通过 pcall 传递，以便捕获错误。如果发生错误，返回的值将为 nil。
	--]]
	
	local env, envFuncs = {}, {}

	-- 设置元表。如果触发，我们调用 envFuncs 表中的相应函数。
	-- 该函数返回的值会被缓存在 env 表中，这样我们就不会多次调用任何函数。（nil 不会被缓存。）
	setmetatable(env, {
		__index = function (t, key)
			local envFunc = envFuncs[key]
			if envFunc then
				local success, val = pcall(envFunc)
				if success then
					env[key] = val -- 缓存值
					return val
				end
			end
			return nil
		end
	})

	-- 当前标题
	envFuncs.title = function()
		return mw.title.getCurrentTitle()
	end

	-- 模板标题
	envFuncs.templateTitle = function()
		local title = env.title
		local argsTitle = args.title
		if argsTitle then
			return mw.title.new(argsTitle)
		end
		return title
	end

	-- 文档标题
	envFuncs.docTitle = function()
		local templateTitle = env.templateTitle
		local docSubpage = message('doc-subpage')
		return templateTitle:subPageTitle(docSubpage)
	end

	-- 沙盒标题
	envFuncs.sandboxTitle = function()
		local templateTitle = env.templateTitle
		local sandboxSubpage = message('sandbox-subpage')
		return templateTitle:subPageTitle(sandboxSubpage)
	end

	-- 测试用例标题
	envFuncs.testcasesTitle = function()
		local templateTitle = env.templateTitle
		local testcasesSubpage = message('testcases-subpage')
		return templateTitle:subPageTitle(testcasesSubpage)
	end

	-- 打印标题
	envFuncs.printTitle = function()
		local templateTitle = env.templateTitle
		local printSubpage = message('print-subpage')
		return templateTitle:subPageTitle(printSubpage)
	end

	-- 保护级别
	envFuncs.protectionLevels = function()
		local templateTitle = env.templateTitle
		return templateTitle.protectionLevels
	end

	-- 主题命名空间
	envFuncs.subjectSpace = function()
		local templateTitle = env.templateTitle
		return templateTitle.namespace
	end

	-- 文档命名空间
	envFuncs.docSpace = function()
		local subjectSpace = env.subjectSpace
		if subjectSpace == 0 then
			return 10 -- 模板命名空间
		elseif subjectSpace == 828 then
			return 828 -- 模块命名空间
		else
			return subjectSpace
		end
	end

	-- 文档页面基础
	envFuncs.docpageBase = function()
		local templateTitle = env.templateTitle
		local docSpace = env.docSpace
		local docNsText = mw.site.namespaces[docSpace].name
		return docNsText .. ':' .. templateTitle.text
	end

	-- 比较URL
	envFuncs.compareUrl = function()
		local sandboxTitle = env.sandboxTitle
		local templateTitle = env.templateTitle
		if sandboxTitle and templateTitle then
			return mw.uri.fullUrl('Special:ComparePages', {
				page1 = templateTitle.fullText,
				page2 = sandboxTitle.fullText
			})
		end
		return nil
	end

	return env
end

p.getModuleWikitext = makeInvokeFunc('_getModuleWikitext')

function p._getModuleWikitext(args, env)
	-- 获取模块wikitext
	local currentTitle = mw.title.getCurrentTitle()
	if currentTitle.contentModel ~= 'Scribunto' then return end
	pcall(require, currentTitle.prefixedText) -- 如果失败，我们不关心
	local moduleWikitext =  package.loaded["Module:Module wikitext"]
	if moduleWikitext then
		return moduleWikitext.main()
	end
end

function p.sandboxNotice(args, env)
	--[=[
	-- 为沙盒页面生成沙盒通知。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 
	-- 消息：
	-- 'sandbox-notice-image' --> '[[Image:Sandbox.svg|50px|alt=|link=]]'
	-- 'sandbox-notice-blurb' --> '这是 $2 的 $1。'
	-- 'sandbox-notice-diff-blurb' --> '这是 $2 的 $1 ($3)。'
	-- 'sandbox-notice-pagetype-template' --> '[[w:Wikipedia:Template test cases|模板沙盒]]页面'
	-- 'sandbox-notice-pagetype-module' --> '[[w:Wikipedia:Template test cases|模块沙盒]]页面'
	-- 'sandbox-notice-pagetype-other' --> '沙盒页面'
	-- 'sandbox-notice-compare-link-display' --> '差异'
	-- 'sandbox-notice-testcases-blurb' --> '另请参阅 $1 的配套子页面。'
	-- 'sandbox-notice-testcases-link-display' --> '测试用例'
	-- 'sandbox-category' --> '模板沙盒'
	--]=]
	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
	-- 构建传递给 {{ombox}} 的参数表。我们只需要两个字段："image" 和 "text"。
	local omargs = {}
	omargs.image = message('sandbox-notice-image')
	-- 获取文本。我们从开头的说明开始，类似于
	-- "这是 [[Template:Foo]] 的模板沙盒 (差异)。"
	local text = ''
	local frame = mw.getCurrentFrame()
	local isPreviewing = frame:preprocess('{{REVISIONID}}') == '' -- 如果页面正在预览则为真
	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 = makeWikilink(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
	-- 如果页面存在，获取测试用例页面说明。类似于
	-- "另请参阅 [[Template:Foo/testcases|测试用例]] 的配套子页面。"
	local testcasesTitle = env.testcasesTitle
	if testcasesTitle and testcasesTitle.exists then
		if testcasesTitle.contentModel == "Scribunto" then
			local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display')
			local testcasesRunLinkDisplay = message('sandbox-notice-testcases-run-link-display')
			local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
			local testcasesRunLink = makeWikilink(testcasesTitle.talkPageTitle.prefixedText, testcasesRunLinkDisplay)
			text = text .. '<br />' .. message('sandbox-notice-testcases-run-blurb', {testcasesLink, testcasesRunLink})
		else
			local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display')
			local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
			text = text .. '<br />' .. message('sandbox-notice-testcases-blurb', {testcasesLink})
		end
	end
	-- 将沙盒添加到沙盒分类中。
	text = text .. makeCategoryLink(message('sandbox-category'))
	omargs.text = text
	omargs.class = message('sandbox-class')
	local ret = '<div style="clear: both;"></div>'
	ret = ret .. messageBox.main('ombox', omargs)
	return ret
end

function p.protectionTemplate(env)
	-- 生成右上角的挂锁图标。
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 消息：
	-- 'protection-template' --> 'pp-template'
	-- 'protection-template-args' --> {docusage = 'yes'}
	local title = env.title
	local protectionLevels
	local protectionTemplate = message('protection-template')
	local namespace = title.namespace
	if not (protectionTemplate and (namespace == 10 or namespace == 828)) then
		-- 如果不在模板或模块命名空间中，不显示保护模板。
		return nil
	end
	protectionLevels = env.protectionLevels
	if not protectionLevels then
		return nil
	end
	local editLevels = protectionLevels.edit
	local moveLevels = protectionLevels.move

	if moveLevels and moveLevels[1] == 'sysop' or editLevels and editLevels[1] then
		-- 页面被完全移动保护，或完全、模板或半保护。
		local frame = mw.getCurrentFrame()
		return frame:expandTemplate{title = protectionTemplate, args = message('protection-template-args', nil, 'table')}
	else
		return nil
	end
end

----------------------------------------------------------------------------
-- 起始框
----------------------------------------------------------------------------

p.startBox = makeInvokeFunc('_startBox')

function p._startBox(args, env)
	--[[
	-- 这个函数生成起始框。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 
	-- 实际工作由 p.makeStartBoxLinksData 和 p.renderStartBoxLinks 完成，它们创建
	-- [查看] [编辑] [历史] [清除] 链接，以及由 p.makeStartBoxData 和 p.renderStartBox
	-- 生成框的 HTML。
	--]]
	env = env or p.getEnvironment(args)
	local links
	local content = args.content
	if not content then
		-- 如果文档在模板页面本身，则不需要包含链接。
		local linksData = p.makeStartBoxLinksData(args, env)
		if linksData then
			links = p.renderStartBoxLinks(linksData)
		end
	end
	-- 生成起始框的 HTML。
	local data = p.makeStartBoxData(args, env, links)
	if data then
		return p.renderStartBox(data)
	else
		-- 用户指定了无标题。
		return nil
	end
end

function p.makeStartBoxLinksData(args, env)
	--[[
	-- 对数据进行初步处理以创建 [查看] [编辑] [历史] [清除] 链接。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 
	-- 消息：
	-- 'view-link-display' --> '查看'
	-- 'edit-link-display' --> '编辑'
	-- 'history-link-display' --> '历史'
	-- 'purge-link-display' --> '清除'
	-- 'file-docpage-preload' --> 'Template:Documentation/preload-filespace'
	-- 'module-preload' --> 'Template:Documentation/preload-module-doc'
	-- 'docpage-preload' --> 'Template:Documentation/preload'
	-- 'create-link-display' --> '创建'
	--]]
	local subjectSpace = env.subjectSpace
	local title = env.title
	local docTitle = env.docTitle
	if not title or not docTitle then
		return nil
	end
	if docTitle.isRedirect then 
		docTitle = docTitle.redirectTarget
	end

	local data = {}
	data.title = title
	data.docTitle = docTitle
	-- 如果 /doc 存在，查看、显示、编辑和清除链接。
	data.viewLinkDisplay = i18n['view-link-display']
	data.editLinkDisplay = i18n['edit-link-display']
	data.historyLinkDisplay = i18n['history-link-display']
	data.purgeLinkDisplay = i18n['purge-link-display']
	-- 如果 /doc 不存在，创建链接。
	local preload = args.preload
	if not preload then
		if subjectSpace == 6 then -- 文件命名空间
			preload = message('file-docpage-preload')
		elseif subjectSpace == 828 then -- 模块命名空间
			preload = message('module-preload')
		else
			preload = message('docpage-preload')
		end
	end
	data.preload = preload
	data.createLinkDisplay = i18n['create-link-display']
	return data
end

function p.renderStartBoxLinks(data)
	--[[
	-- 从数据表生成 [查看][编辑][历史][清除] 或 [创建] 链接。
	-- @data - 由 p.makeStartBoxLinksData 生成的数据表
	--]]
	
	local function escapeBrackets(s)
		-- 用 HTML 实体转义方括号。
		s = s:gsub('%[', '&#91;') -- 用 HTML 实体替换方括号。
		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'}, data.editLinkDisplay)
		local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, data.historyLinkDisplay)
		local purgeLink = makeUrlLink(title:fullUrl{action = 'purge'}, 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', preload = data.preload}, data.createLinkDisplay)
		ret = '[%s]'
		ret = escapeBrackets(ret)
		ret = mw.ustring.format(ret, createLink)
	end
	return ret
end

function p.makeStartBoxData(args, env, links)
	--[=[
	-- 对数据进行初步处理以传递给起始框渲染函数 p.renderStartBox。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- @links - 包含 [查看][编辑][历史][清除] 链接的字符串 - 如果有错误可能为 nil。
	--
	-- 消息：
	-- 'documentation-icon-wikitext' --> '[[File:Test Template Info-Icon - Version (2).svg|50px|link=|alt=Documentation icon]]'
	-- 'template-namespace-heading' --> '模板文档'
	-- 'module-namespace-heading' --> '模块文档'
	-- 'file-namespace-heading' --> '摘要'
	-- 'other-namespaces-heading' --> '文档'
	-- 'start-box-linkclasses' --> 'mw-editsection-like plainlinks'
	-- 'start-box-link-id' --> 'doc_editlinks'
	-- 'testcases-create-link-display' --> '创建'
	--]=]
	local subjectSpace = env.subjectSpace
	if not subjectSpace then
		-- 默认为"其他命名空间"，以便在发生错误时至少有一些输出。
		subjectSpace = 2
	end
	local data = {}
	
	-- 标题
	local heading = args.heading -- 空值不会被移除。
	if heading == '' then
		-- 如果 heading 参数已定义但为空，则不显示起始框。
		return nil
	end
	if heading then
		data.heading = heading
	elseif subjectSpace == 10 then -- 模板命名空间
		data.heading = i18n['template-namespace-heading']
	elseif subjectSpace == 828 then -- 模块命名空间
		data.heading = i18n['module-namespace-heading']
	elseif subjectSpace == 6 then -- 文件命名空间
		data.heading = i18n['file-namespace-heading']
	else
		data.heading = i18n['other-namespaces-heading']
	end
	
	-- [查看][编辑][历史][清除] 或 [创建] 链接的数据。
	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(data)
	-- 渲染起始框的 HTML。
	-- @data - 由 p.makeStartBoxData 生成的数据表。
	local sbox = mw.html.create('div')
	sbox
		:addClass(message('header-div-class'))
		:tag('div')
			:addClass(message('heading-div-class'))
			:wikitext(data.heading)
	local links = data.links
	if links then
		sbox
			:tag('div')
				:addClass(data.linksClass)
				:attr('id', data.linksId)
				:wikitext(links)
	end

	return tostring(sbox)
end

----------------------------------------------------------------------------
-- 文档内容
----------------------------------------------------------------------------

p.content = makeInvokeFunc('_content')

function p._content(args, env)
	-- 显示文档内容
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	env = env or p.getEnvironment(args)
	local docTitle = env.docTitle
	local content = args.content
	if not content and docTitle and docTitle.exists then
		content = args._content or mw.getCurrentFrame():expandTemplate{title = docTitle}
	end
	-- 下面的换行符是必要的，以便文档开头和结尾的 "=== 标题 ===" 被正确解释。
	local cbox = mw.html.create('div')
	cbox
		:addClass(message('content-div-class'))
		:wikitext('\n' .. (content or '') .. '\n')
	return tostring(cbox)
end

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

----------------------------------------------------------------------------
-- 结束框
----------------------------------------------------------------------------

p.endBox = makeInvokeFunc('_endBox')

function p._endBox(args, env)
	--[=[
	-- 这个函数生成结束框（也称为链接框）。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	--]=]
	
	-- 获取环境数据。
	env = env or p.getEnvironment(args)
	local subjectSpace = env.subjectSpace
	local docTitle = env.docTitle
	if not subjectSpace or not docTitle then
		return nil
	end
		
	-- 检查是否应该输出结束框。如果文档存在或者我们在用户、模块或模板命名空间中，默认添加结束框。
	local linkBox = args['link box']
	if linkBox == 'off'
		or not (
			docTitle.exists
			or subjectSpace == 2
			or subjectSpace == 828
			or subjectSpace == 10
		)
	then
		return nil
	end

	-- 组装页脚文本字段。
	local text = ''
	if linkBox then
		text = text .. linkBox
	else
		text = text .. (p.makeDocPageBlurb(args, env) or '') -- "此文档是从 [[Foo]] 嵌入的。" 
		if subjectSpace == 2 or subjectSpace == 10 or subjectSpace == 828 then
			-- 我们在用户、模板或模块命名空间中。
			-- 添加沙盒和测试用例链接。
			-- "编辑者可以在此模板的沙盒和测试用例页面中进行实验。"
			text = text .. (p.makeExperimentBlurb(args, env) or '')
			text = text .. '<br />'
			if not args.content and not args[1] then
				-- "请将分类添加到 /doc 子页面。"
				-- 对于内联文档或明确指定的文档页面，不显示此消息，
				-- 因为不清楚在哪里添加分类。
				text = text .. (p.makeCategoriesBlurb(args, env) or '')
			end
			text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '') --"此模板的子页面"
			local printBlurb = p.makePrintBlurb(args, env) -- 关于模板打印版本的两行说明。
			if printBlurb then
				text = text .. '<br />' .. printBlurb
			end
		end
	end

	local ebox = mw.html.create('div')
	ebox
		:addClass(message('footer-div-class'))
		:wikitext(text)
	return tostring(ebox)
end

function p.makeDocPageBlurb(args, env)
	--[=[
	-- 生成说明 "此文档是从 [[Template:Foo]] (编辑, 历史) 嵌入的。"
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 
	-- 消息：
	-- 'edit-link-display' --> '编辑'
	-- 'history-link-display' --> '历史'
	-- 'transcluded-from-blurb' --> 
	-- '上面的 [[w:Wikipedia:Template documentation|文档]] 
	-- 是从 $1 [[w:Wikipedia:Transclusion|嵌入]] 的。'
	-- 'module-preload' --> 'Template:Documentation/preload-module-doc'
	-- 'create-link-display' --> '创建'
	-- 'create-module-doc-blurb' -->
	-- '您可能想要为此 [[w:Wikipedia:Lua|Scribunto 模块]] $1 一个文档页面。'
	--]=]
	local docTitle = env.docTitle
	if not docTitle or args.content then
		return nil
	end
	local ret
	if docTitle.exists then
		-- /doc 存在；链接到它。
		local docLink = makeWikilink(docTitle.prefixedText)
		local editUrl = docTitle:fullUrl{action = 'edit'}
		local editDisplay = i18n['edit-link-display']
		local editLink = makeUrlLink(editUrl, editDisplay)
		local historyUrl = docTitle:fullUrl{action = 'history'}
		local historyDisplay = i18n['history-link-display']
		local historyLink = makeUrlLink(historyUrl, historyDisplay)
		ret = message('transcluded-from-blurb', {docLink})
			.. ' '
			.. makeToolbar(editLink, historyLink)
			.. '<br />'
	elseif env.subjectSpace == 828 then
		-- /doc 不存在；请求创建它。
		local createUrl = docTitle:fullUrl{action = 'edit', preload = message('module-preload')}
		local createDisplay = i18n['create-link-display']
		local createLink = makeUrlLink(createUrl, createDisplay)
		ret = message('create-module-doc-blurb', {createLink})
			.. '<br />'
	end
	return ret
end

function p.makeExperimentBlurb(args, env)
	--[[
	-- 渲染文本 "编辑者可以在此模板的沙盒 (编辑 | 差异) 和测试用例 (编辑) 页面中进行实验。"
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 
	-- 消息：
	-- 'sandbox-link-display' --> '沙盒'
	-- 'sandbox-edit-link-display' --> '编辑'
	-- 'compare-link-display' --> '差异'
	-- 'module-sandbox-preload' --> 'Template:Documentation/preload-module-sandbox'
	-- 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox'
	-- 'sandbox-create-link-display' --> '创建'
	-- 'mirror-edit-summary' --> '创建 $1 的沙盒版本'
	-- 'mirror-link-display' --> '镜像'
	-- 'mirror-link-preload' --> 'Template:Documentation/mirror'
	-- 'sandbox-link-display' --> '沙盒'
	-- 'testcases-link-display' --> '测试用例'
	-- 'testcases-edit-link-display'--> '编辑'
	-- 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox'
	-- 'testcases-create-link-display' --> '创建'
	-- 'testcases-link-display' --> '测试用例'
	-- 'testcases-edit-link-display' --> '编辑'
	-- 'module-testcases-preload' --> 'Template:Documentation/preload-module-testcases'
	-- 'template-testcases-preload' --> 'Template:Documentation/preload-testcases'
	-- 'experiment-blurb-module' --> '编辑者可以在此模块的 $1 和 $2 页面中进行实验。'
	-- 'experiment-blurb-template' --> '编辑者可以在此模板的 $1 和 $2 页面中进行实验。'
	--]]
	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
	-- 创建链接。
	local sandboxLinks, testcasesLinks
	if sandboxTitle.exists then
		local sandboxPage = sandboxTitle.prefixedText
		local sandboxDisplay = message('sandbox-link-display')
		local sandboxLink = makeWikilink(sandboxPage, sandboxDisplay)
		local sandboxEditUrl = sandboxTitle:fullUrl{action = 'edit'}
		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', preload = sandboxPreload}
		local sandboxCreateDisplay = message('sandbox-create-link-display')
		local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay)
		local mirrorSummary = message('mirror-edit-summary', {makeWikilink(templatePage)})
		local mirrorPreload = message('mirror-link-preload')
		local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = mirrorPreload, summary = mirrorSummary}
		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 = makeWikilink(testcasesPage, testcasesDisplay)
		local testcasesEditUrl = testcasesTitle:fullUrl{action = 'edit'}
		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', preload = testcasesPreload}
		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(args, env)
	--[[
	-- 生成文本 "请将分类添加到 /doc 子页面。"
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	-- 消息：
	-- 'doc-link-display' --> '/doc'
	-- 'add-categories-blurb' --> '请将分类添加到 $1 子页面。'
	--]]
	local docTitle = env.docTitle
	if not docTitle then
		return nil
	end
	local docPathLink = makeWikilink(docTitle.prefixedText, message('doc-link-display'))
	return message('add-categories-blurb', {docPathLink})
end

function p.makeSubpagesBlurb(args, env)
	--[[
	-- 生成 "此模板的子页面" 链接。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	
	-- 消息：
	-- 'template-pagetype' --> '模板'
	-- 'module-pagetype' --> '模块'
	-- 'default-pagetype' --> '页面'
	-- 'subpages-link-display' --> '此 $1 的子页面'
	--]]
	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(args, env)
	--[=[
	-- 生成当模板有打印版本可用时显示的说明。
	-- @args - 用户传递的参数表
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	--
	-- 消息：
	-- 'print-link-display' --> '/Print'
	-- 'print-blurb' --> '此模板的 [[Help:Books/for experts#Improving the book layout|打印版本]]'
	--		.. ' 存在于 $1。'
	--		.. ' 如果您对此模板进行了更改，请同时更新打印版本。'
	-- 'display-print-category' --> true
	-- 'print-category' --> '有打印版本的模板'
	--]=]
	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

----------------------------------------------------------------------------
-- 跟踪分类
----------------------------------------------------------------------------

function p.addTrackingCategories(env)
	--[[
	-- 检查 {{documentation}} 是否嵌入在 /doc 或 /testcases 页面上。
	-- @env - 包含标题对象等的环境表，由 p.getEnvironment 生成
	
	-- 消息：
	-- 'display-strange-usage-category' --> true
	-- 'doc-subpage' --> 'doc'
	-- 'testcases-subpage' --> 'testcases'
	-- 'strange-usage-category' --> '使用奇怪的 ((documentation)) 的维基百科页面'
	-- 
	-- 模块命名空间中的 /testcases 页面不会被分类，因为它们可能自动嵌入了 {{documentation}}。
	--]]
	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
	return ret
end

return p