Modul:Documentation

-- This module implements {{documentation}}.

-- Get required modules.
localgetArgs=require('Module:Arguments').getArgs

-- Get the config table.
localcfg=mw.loadData('Module:Documentation/config')

localp={}

-- Often-used functions.
localugsub=mw.ustring.gsub
localformat=mw.ustring.format

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

localfunctionmessage(cfgKey,valArray,expectType)
--[[
-- 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."
--]]
localmsg=cfg[cfgKey]
expectType=expectTypeor'string'
iftype(msg)~=expectTypethen
error('message: type error in message cfg.'..cfgKey..' ('..expectType..' expected, got '..type(msg)..')',2)
end
ifnotvalArraythen
returnmsg
end

localfunctiongetMessageVal(match)
match=tonumber(match)
returnvalArray[match]orerror('message: no value found for key $'..match..' in message cfg.'..cfgKey,4)
end

returnugsub(msg,'$([1-9][0-9]*)',getMessageVal)
end

p.message=message

localfunctionmakeWikilink(page,display)
ifdisplaythen
returnformat('[[%s|%s]]',page,display)
else
returnformat('[[%s]]',page)
end
end

p.makeWikilink=makeWikilink

localfunctionmakeCategoryLink(cat,sort)
localcatns=mw.site.namespaces[14].name
returnmakeWikilink(catns..':'..cat,sort)
end

p.makeCategoryLink=makeCategoryLink

localfunctionmakeUrlLink(url,display)
returnformat('[%s %s]',url,display)
end

p.makeUrlLink=makeUrlLink

localfunctionmakeToolbar(...)
localret={}
locallim=select('#',...)
iflim<1then
returnnil
end
fori=1,limdo
ret[#ret+1]=select(i,...)
end
-- 'documentation-toolbar'
returnformat(
'<span class= "%s" >(%s)</span>',
message('toolbar-class'),
table.concat(ret,' &#124; ')
)
end

p.makeToolbar=makeToolbar

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

localfunctionmakeInvokeFunc(funcName)
returnfunction(frame)
localargs=getArgs(frame,{
valueFunc=function(key,value)
iftype(value)=='string'then
value=value:match('^%s*(.-)%s*$')-- Remove whitespace.
ifkey=='heading'orvalue~=''then
returnvalue
else
returnnil
end
else
returnvalue
end
end
})
returnp[funcName](args)
end
end

----------------------------------------------------------------------------
-- Entry points
----------------------------------------------------------------------------

functionp.nonexistent(frame)
ifmw.title.getCurrentTitle().subpageText=='testcases'then
returnframe:expandTemplate{title='module test cases notice'}
else
returnp.main(frame)
end
end

p.main=makeInvokeFunc('_main')

functionp._main(args)
--[[
-- This function defines logic flow for the module.
-- @args - table of arguments passed by the user
--]]
localenv=p.getEnvironment(args)
localroot=mw.html.create()
root
:wikitext(p._getModuleWikitext(args,env))
:wikitext(p.protectionTemplate(env))
:wikitext(p.sandboxNotice(args,env))
:tag('div')
-- 'documentation-container'
:addClass(message('container'))
:attr('role','complementary')
:attr('aria-labelledby',args.heading~=''and'documentation-heading'ornil)
:attr('aria-label',args.heading==''and'Documentation'ornil)
:newline()
:tag('div')
-- 'documentation'
:addClass(message('main-div-classes'))
:newline()
:wikitext(p._startBox(args,env))
:wikitext(p._content(args,env))
:tag('div')
-- 'documentation-clear'
:addClass(message('clear'))
:done()
:newline()
:done()
:wikitext(p._endBox(args,env))
:done()
:wikitext(p.addTrackingCategories(env))
-- 'Module:Documentation/styles.css'
returnmw.getCurrentFrame():extensionTag(
'templatestyles','',{src=cfg['templatestyles']
})..tostring(root)
end

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

functionp.getEnvironment(args)
--[[
-- Returns a table with information about the environment, including title
-- objects and other namespace- or path-related data.
-- @args - table of arguments passed by the user
--
-- Title objects include:
-- env.title - the page we are making documentation for (usually the current title)
-- env.templateTitle - the template (or module, file, etc.)
-- env.docTitle - the /doc subpage.
-- env.sandboxTitle - the /sandbox subpage.
-- env.testcasesTitle - the /testcases subpage.
--
-- Data includes:
-- env.protectionLevels - the protection levels table of the title object.
-- env.subjectSpace - the number of the title's subject namespace.
-- env.docSpace - the number of the namespace the title puts its documentation in.
-- env.docpageBase - the text of the base page of the /doc, /sandbox and /testcases pages, with namespace.
-- env pareUrl - URL of the Special:ComparePages page comparing the sandbox with the template.
--
-- All table lookups are passed through pcall so that errors are caught. If an error occurs, the value
-- returned will be nil.
--]]

localenv,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)
localenvFunc=envFuncs[key]
ifenvFuncthen
localsuccess,val=pcall(envFunc)
ifsuccessthen
env[key]=val-- Memoise the value.
returnval
end
end
returnnil
end
})

functionenvFuncs.title()
-- The title object for the current page, or a test page passed with args.page.
localtitle
localtitleArg=args.page
iftitleArgthen
title=mw.title.new(titleArg)
else
title=mw.title.getCurrentTitle()
end
returntitle
end

functionenvFuncs.templateTitle()
--[[
-- The template (or module, etc.) title object.
-- Messages:
-- 'sandbox-subpage' --> 'sandbox'
-- 'testcases-subpage' --> 'testcases'
--]]
localsubjectSpace=env.subjectSpace
localtitle=env.title
localsubpage=title.subpageText
ifsubpage==message('sandbox-subpage')orsubpage==message('testcases-subpage')then
returnmw.title.makeTitle(subjectSpace,title.baseText)
else
returnmw.title.makeTitle(subjectSpace,title.text)
end
end

functionenvFuncs.docTitle()
--[[
-- Title object of the /doc subpage.
-- Messages:
-- 'doc-subpage' --> 'doc'
--]]
localtitle=env.title
localdocname=args[1]-- User-specified doc page.
localdocpage
ifdocnamethen
docpage=docname
else
docpage=env.docpageBase..'/'..message('doc-subpage')
end
returnmw.title.new(docpage)
end

functionenvFuncs.sandboxTitle()
--[[
-- Title object for the /sandbox subpage.
-- Messages:
-- 'sandbox-subpage' --> 'sandbox'
--]]
returnmw.title.new(env.docpageBase..'/'..message('sandbox-subpage'))
end

functionenvFuncs.testcasesTitle()
--[[
-- Title object for the /testcases subpage.
-- Messages:
-- 'testcases-subpage' --> 'testcases'
--]]
returnmw.title.new(env.docpageBase..'/'..message('testcases-subpage'))
end

functionenvFuncs.protectionLevels()
-- The protection levels table of the title object.
returnenv.title.protectionLevels
end

functionenvFuncs.subjectSpace()
-- The subject namespace number.
returnmw.site.namespaces[env.title.namespace].subject.id
end

functionenvFuncs.docSpace()
-- 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.
localsubjectSpace=env.subjectSpace
ifsubjectSpace==0orsubjectSpace==6orsubjectSpace==8orsubjectSpace==14then
returnsubjectSpace+1
else
returnsubjectSpace
end
end

functionenvFuncs.docpageBase()
-- The base page of the /doc, /sandbox, and /testcases subpages.
-- For some namespaces this is the talk page, rather than the template page.
localtemplateTitle=env.templateTitle
localdocSpace=env.docSpace
localdocSpaceText=mw.site.namespaces[docSpace].name
-- Assemble the link. docSpace is never the main namespace, so we can hardcode the colon.
returndocSpaceText..':'..templateTitle.text
end

functionenvFuncs.compareUrl()
-- Diff link between the sandbox and the main template using [[Special:ComparePages]].
localtemplateTitle=env.templateTitle
localsandboxTitle=env.sandboxTitle
iftemplateTitle.existsandsandboxTitle.existsthen
localcompareUrl=mw.uri.canonicalUrl(
'Special:ComparePages',
{page1=templateTitle.prefixedText,page2=sandboxTitle.prefixedText}
)
returntostring(compareUrl)
else
returnnil
end
end

returnenv
end

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

p.getModuleWikitext=makeInvokeFunc('_getModuleWikitext')

functionp._getModuleWikitext(args,env)
localcurrentTitle=mw.title.getCurrentTitle()
ifcurrentTitle.contentModel~='Scribunto'thenreturnend
pcall(require,currentTitle.prefixedText)-- if it fails, we don't care
localmoduleWikitext=package.loaded["Module:Module wikitext"]
ifmoduleWikitextthen
returnmoduleWikitext.main()
end
end

functionp.sandboxNotice(args,env)
--[=[
-- Generates a sandbox notice for display above sandbox pages.
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- Messages:
-- 'sandbox-notice-image' --> '[[File:Sandbox.svg|50px|alt=|link=]]'
-- 'sandbox-notice-blurb' --> 'This is the $1 for $2.'
-- 'sandbox-notice-diff-blurb' --> 'This is the $1 for $2 ($3).'
-- 'sandbox-notice-pagetype-template' --> '[[Wikipedia:Template test cases|template sandbox]] page'
-- 'sandbox-notice-pagetype-module' --> '[[Wikipedia:Template test cases|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'
-- 'module-sandbox-category' --> 'Module sandboxes'
-- 'other-sandbox-category' --> 'Sandboxes outside of template or module namespace'
--]=]
localtitle=env.title
localsandboxTitle=env.sandboxTitle
localtemplateTitle=env.templateTitle
localsubjectSpace=env.subjectSpace
ifnot(subjectSpaceandtitleandsandboxTitleandtemplateTitle
andmw.title.equals(title,sandboxTitle))then
returnnil
end
-- Build the table of arguments to pass to {{ombox}}. We need just two fields, "image" and "text".
localomargs={}
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)."
localtext=''
localpagetype,sandboxCat
ifsubjectSpace==10then
pagetype=message('sandbox-notice-pagetype-template')
sandboxCat=message('sandbox-category')
elseifsubjectSpace==828then
pagetype=message('sandbox-notice-pagetype-module')
sandboxCat=message('module-sandbox-category')
else
pagetype=message('sandbox-notice-pagetype-other')
sandboxCat=message('other-sandbox-category')
end
localtemplateLink=makeWikilink(templateTitle.prefixedText)
localcompareUrl=env.compareUrl
ifcompareUrlthen
localcompareDisplay=message('sandbox-notice-compare-link-display')
localcompareLink=makeUrlLink(compareUrl,compareDisplay)
text=text..message('sandbox-notice-diff-blurb',{pagetype,templateLink,compareLink})
else
text=text..message('sandbox-notice-blurb',{pagetype,templateLink})
end
-- Get the test cases page blurb if the page exists. This is something like
-- "See also the companion subpage for [[Template:Foo/testcases|test cases]]."
localtestcasesTitle=env.testcasesTitle
iftestcasesTitleandtestcasesTitle.existsthen
iftestcasesTitle.contentModel=="Scribunto"then
localtestcasesLinkDisplay=message('sandbox-notice-testcases-link-display')
localtestcasesRunLinkDisplay=message('sandbox-notice-testcases-run-link-display')
localtestcasesLink=makeWikilink(testcasesTitle.prefixedText,testcasesLinkDisplay)
localtestcasesRunLink=makeWikilink(testcasesTitle.talkPageTitle.prefixedText,testcasesRunLinkDisplay)
text=text..'<br />'..message('sandbox-notice-testcases-run-blurb',{testcasesLink,testcasesRunLink})
else
localtestcasesLinkDisplay=message('sandbox-notice-testcases-link-display')
localtestcasesLink=makeWikilink(testcasesTitle.prefixedText,testcasesLinkDisplay)
text=text..'<br />'..message('sandbox-notice-testcases-blurb',{testcasesLink})
end
end

-- Add the sandbox to the sandbox category.
omargs.text=text..makeCategoryLink(sandboxCat)

-- 'documentation-clear'
return'<div class= "'..message('clear')..' "></div>'
..require('Module:Message box').main('ombox',omargs)
end

functionp.protectionTemplate(env)
-- Generates the padlock icon in the top right.
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
-- Messages:
-- 'protection-template' --> 'pp-template'
-- 'protection-template-args' --> {docusage = 'yes'}
localprotectionLevels=env.protectionLevels
ifnotprotectionLevelsthen
returnnil
end
localeditProt=protectionLevels.editandprotectionLevels.edit[1]
localmoveProt=protectionLevels.moveandprotectionLevels.move[1]
ifeditProtthen
-- The page is edit-protected.
returnrequire('Module:Protection banner')._main{
message('protection-reason-edit'),small=true
}
elseifmoveProtandmoveProt~='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.
returnrequire('Module:Protection banner')._main{
action='move',small=true
}
else
returnnil
end
end

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

p.startBox=makeInvokeFunc('_startBox')

functionp._startBox(args,env)
--[[
-- This function generates the start box.
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- 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.
--]]
env=envorp.getEnvironment(args)
locallinks
localcontent=args.content
ifnotcontentorargs[1]then
-- No need to include the links if the documentation is on the template page itself.
locallinksData=p.makeStartBoxLinksData(args,env)
iflinksDatathen
links=p.renderStartBoxLinks(linksData)
end
end
-- Generate the start box html.
localdata=p.makeStartBoxData(args,env,links)
ifdatathen
returnp.renderStartBox(data)
else
-- User specified no heading.
returnnil
end
end

functionp.makeStartBoxLinksData(args,env)
--[[
-- Does initial processing of data to make the [view] [edit] [history] [purge] links.
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- Messages:
-- 'view-link-display' --> 'view'
-- 'edit-link-display' --> 'edit'
-- 'history-link-display' --> 'history'
-- 'purge-link-display' --> 'purge'
-- 'module-preload' --> 'Template:Documentation/preload-module-doc'
-- 'docpage-preload' --> 'Template:Documentation/preload'
-- 'create-link-display' --> 'create'
--]]
localsubjectSpace=env.subjectSpace
localtitle=env.title
localdocTitle=env.docTitle
ifnottitleornotdocTitlethen
returnnil
end
ifdocTitle.isRedirectthen
docTitle=docTitle.redirectTarget
end

-- Create link if /doc doesn't exist.
localpreload=args.preload
ifnotpreloadthen
ifsubjectSpace==828then-- Module namespace
preload=message('module-preload')
else
preload=message('docpage-preload')
end
end

return{
title=title,
docTitle=docTitle,
-- View, display, edit, and purge links if /doc exists.
viewLinkDisplay=message('view-link-display'),
editLinkDisplay=message('edit-link-display'),
historyLinkDisplay=message('history-link-display'),
purgeLinkDisplay=message('purge-link-display'),
preload=preload,
createLinkDisplay=message('create-link-display')
}
end

functionp.renderStartBoxLinks(data)
--[[
-- Generates the [view][edit][history][purge] or [create][purge] links from the data table.
-- @data - a table of data generated by p.makeStartBoxLinksData
--]]
localdocTitle=data.docTitle
-- yes, we do intend to purge the template page on which the documentation appears
localpurgeLink=makeWikilink("Special:Purge/"..data.title.prefixedText,data.purgeLinkDisplay)

ifdocTitle.existsthen
localviewLink=makeWikilink(docTitle.prefixedText,data.viewLinkDisplay)
localeditLink=makeWikilink("Special:EditPage/"..docTitle.prefixedText,data.editLinkDisplay)
localhistoryLink=makeWikilink("Special:PageHistory/"..docTitle.prefixedText,data.historyLinkDisplay)
return"&#91;"..viewLink.."&#93; &#91;"..editLink.."&#93; &#91;"..historyLink.."&#93; &#91;"..purgeLink.."&#93;"
else
localcreateLink=makeUrlLink(docTitle:canonicalUrl{action='edit',preload=data.preload},data.createLinkDisplay)
return"&#91;"..createLink.."&#93; &#91;"..purgeLink.."&#93;"
end
returnret
end

functionp.makeStartBoxData(args,env,links)
--[=[
-- Does initial processing of data to pass to the start-box render function, p.renderStartBox.
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
-- @links - a string containing the [view][edit][history][purge] links - could be nil if there's an error.
--
-- Messages:
-- 'documentation-icon-wikitext' --> '[[File:Test Template Info-Icon - Version (2).svg|50px|link=|alt=]]'
-- 'template-namespace-heading' --> 'Template documentation'
-- 'module-namespace-heading' --> 'Module documentation'
-- 'file-namespace-heading' --> 'Summary'
-- 'other-namespaces-heading' --> 'Documentation'
-- 'testcases-create-link-display' --> 'create'
--]=]
localsubjectSpace=env.subjectSpace
ifnotsubjectSpacethen
-- Default to an "other namespaces" namespace, so that we get at least some output
-- if an error occurs.
subjectSpace=2
end
localdata={}

-- Heading
localheading=args.heading-- Blank values are not removed.
ifheading==''then
-- Don't display the start box if the heading arg is defined but blank.
returnnil
end
ifheadingthen
data.heading=heading
elseifsubjectSpace==10then-- Template namespace
data.heading=message('documentation-icon-wikitext')..' '..message('template-namespace-heading')
elseifsubjectSpace==828then-- Module namespace
data.heading=message('documentation-icon-wikitext')..' '..message('module-namespace-heading')
elseifsubjectSpace==6then-- File namespace
data.heading=message('file-namespace-heading')
else
data.heading=message('other-namespaces-heading')
end

-- Heading CSS
localheadingStyle=args['heading-style']
ifheadingStylethen
data.headingStyleText=headingStyle
else
-- 'documentation-heading'
data.headingClass=message('main-div-heading-class')
end

-- Data for the [view][edit][history][purge] or [create] links.
iflinksthen
-- 'mw-editsection-like plainlinks'
data.linksClass=message('start-box-link-classes')
data.links=links
end

returndata
end

functionp.renderStartBox(data)
-- Renders the start box html.
-- @data - a table of data generated by p.makeStartBoxData.
localsbox=mw.html.create('div')
sbox
-- 'documentation-startbox'
:addClass(message('start-box-class'))
:newline()
:tag('span')
:addClass(data.headingClass)
:attr('id','documentation-heading')
:cssText(data.headingStyleText)
:wikitext(data.heading)
locallinks=data.links
iflinksthen
sbox:tag('span')
:addClass(data.linksClass)
:attr('id',data.linksId)
:wikitext(links)
end
returntostring(sbox)
end

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

p.content=makeInvokeFunc('_content')

functionp._content(args,env)
-- Displays the documentation contents
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
env=envorp.getEnvironment(args)
localdocTitle=env.docTitle
localcontent=args.content
ifnotcontentanddocTitleanddocTitle.existsthen
content=args._contentormw.getCurrentFrame():expandTemplate{title=docTitle.prefixedText}
end
-- The line breaks below are necessary so that "=== Headings ===" at the start and end
-- of docs are interpreted correctly.
return'\n'..(contentor'')..'\n'
end

p.contentTitle=makeInvokeFunc('_contentTitle')

functionp._contentTitle(args,env)
env=envorp.getEnvironment(args)
localdocTitle=env.docTitle
ifnotargs.contentanddocTitleanddocTitle.existsthen
returndocTitle.prefixedText
else
return''
end
end

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

p.endBox=makeInvokeFunc('_endBox')

functionp._endBox(args,env)
--[=[
-- This function generates the end box (also known as the link box).
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
--]=]

-- Get environment data.
env=envorp.getEnvironment(args)
localsubjectSpace=env.subjectSpace
localdocTitle=env.docTitle
ifnotsubjectSpaceornotdocTitlethen
returnnil
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.
locallinkBox=args['link box']
iflinkBox=='off'
ornot(
docTitle.exists
orsubjectSpace==2
orsubjectSpace==828
orsubjectSpace==10
)
then
returnnil
end

-- Assemble the link box.
localtext=''
iflinkBoxthen
text=text..linkBox
else
text=text..(p.makeDocPageBlurb(args,env)or'')-- "This documentation is transcluded from [[Foo]]."
ifsubjectSpace==2orsubjectSpace==10orsubjectSpace==828then
-- 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'')..'<br />'
ifnotargs.contentandnotargs[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"
end
end

localbox=mw.html.create('div')
-- 'documentation-metadata'
box:attr('role','note')
:addClass(message('end-box-class'))
-- 'plainlinks'
:addClass(message('end-box-plainlinks'))
:wikitext(text)
:done()

return'\n'..tostring(box)
end

functionp.makeDocPageBlurb(args,env)
--[=[
-- Makes the blurb "This documentation is transcluded from [[Template:Foo]] (edit, history)".
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- Messages:
-- 'edit-link-display' --> 'edit'
-- 'history-link-display' --> 'history'
-- 'transcluded-from-blurb' -->
-- 'The above [[Wikipedia:Template documentation|documentation]]
-- is [[Help:Transclusion|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 [[Wikipedia:Lua|Scribunto module]].'
--]=]
localdocTitle=env.docTitle
ifnotdocTitlethen
returnnil
end
ifdocTitle.existsthen
-- /doc exists; link to it.
localdocLink=makeWikilink(docTitle.prefixedText)
localeditDisplay=message('edit-link-display')
localeditLink=makeWikilink("Special:EditPage/"..docTitle.prefixedText,editDisplay)
localhistoryDisplay=message('history-link-display')
localhistoryLink=makeWikilink("Special:PageHistory/"..docTitle.prefixedText,historyDisplay)
returnmessage('transcluded-from-blurb',{docLink})
..' '
..makeToolbar(editLink,historyLink)
..'<br />'
elseifenv.subjectSpace==828then
-- /doc does not exist; ask to create it.
localcreateUrl=docTitle:canonicalUrl{action='edit',preload=message('module-preload')}
localcreateDisplay=message('create-link-display')
localcreateLink=makeUrlLink(createUrl,createDisplay)
returnmessage('create-module-doc-blurb',{createLink})
..'<br />'
end
end

functionp.makeExperimentBlurb(args,env)
--[[
-- Renders the text "Editors can experiment in this template's sandbox (edit | diff) and testcases (edit) pages."
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- 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.'
--]]
localsubjectSpace=env.subjectSpace
localtemplateTitle=env.templateTitle
localsandboxTitle=env.sandboxTitle
localtestcasesTitle=env.testcasesTitle
localtemplatePage=templateTitle.prefixedText
ifnotsubjectSpaceornottemplateTitleornotsandboxTitleornottestcasesTitlethen
returnnil
end
-- Make links.
localsandboxLinks,testcasesLinks
ifsandboxTitle.existsthen
localsandboxPage=sandboxTitle.prefixedText
localsandboxDisplay=message('sandbox-link-display')
localsandboxLink=makeWikilink(sandboxPage,sandboxDisplay)
localsandboxEditDisplay=message('sandbox-edit-link-display')
localsandboxEditLink=makeWikilink("Special:EditPage/"..sandboxPage,sandboxEditDisplay)
localcompareUrl=env.compareUrl
localcompareLink
ifcompareUrlthen
localcompareDisplay=message('compare-link-display')
compareLink=makeUrlLink(compareUrl,compareDisplay)
end
sandboxLinks=sandboxLink..' '..makeToolbar(sandboxEditLink,compareLink)
else
localsandboxPreload
ifsubjectSpace==828then
sandboxPreload=message('module-sandbox-preload')
else
sandboxPreload=message('template-sandbox-preload')
end
localsandboxCreateUrl=sandboxTitle:canonicalUrl{action='edit',preload=sandboxPreload}
localsandboxCreateDisplay=message('sandbox-create-link-display')
localsandboxCreateLink=makeUrlLink(sandboxCreateUrl,sandboxCreateDisplay)
localmirrorSummary=message('mirror-edit-summary',{makeWikilink(templatePage)})
localmirrorPreload=message('mirror-link-preload')
localmirrorUrl=sandboxTitle:canonicalUrl{action='edit',preload=mirrorPreload,summary=mirrorSummary}
ifsubjectSpace==828then
mirrorUrl=sandboxTitle:canonicalUrl{action='edit',preload=templateTitle.prefixedText,summary=mirrorSummary}
end
localmirrorDisplay=message('mirror-link-display')
localmirrorLink=makeUrlLink(mirrorUrl,mirrorDisplay)
sandboxLinks=message('sandbox-link-display')..' '..makeToolbar(sandboxCreateLink,mirrorLink)
end
iftestcasesTitle.existsthen
localtestcasesPage=testcasesTitle.prefixedText
localtestcasesDisplay=message('testcases-link-display')
localtestcasesLink=makeWikilink(testcasesPage,testcasesDisplay)
localtestcasesEditUrl=testcasesTitle:canonicalUrl{action='edit'}
localtestcasesEditDisplay=message('testcases-edit-link-display')
localtestcasesEditLink=makeWikilink("Special:EditPage/"..testcasesPage,testcasesEditDisplay)
-- for Modules, add testcases run link if exists
iftestcasesTitle.contentModel=="Scribunto"andtestcasesTitle.talkPageTitleandtestcasesTitle.talkPageTitle.existsthen
localtestcasesRunLinkDisplay=message('testcases-run-link-display')
localtestcasesRunLink=makeWikilink(testcasesTitle.talkPageTitle.prefixedText,testcasesRunLinkDisplay)
testcasesLinks=testcasesLink..' '..makeToolbar(testcasesEditLink,testcasesRunLink)
else
testcasesLinks=testcasesLink..' '..makeToolbar(testcasesEditLink)
end
else
localtestcasesPreload
ifsubjectSpace==828then
testcasesPreload=message('module-testcases-preload')
else
testcasesPreload=message('template-testcases-preload')
end
localtestcasesCreateUrl=testcasesTitle:canonicalUrl{action='edit',preload=testcasesPreload}
localtestcasesCreateDisplay=message('testcases-create-link-display')
localtestcasesCreateLink=makeUrlLink(testcasesCreateUrl,testcasesCreateDisplay)
testcasesLinks=message('testcases-link-display')..' '..makeToolbar(testcasesCreateLink)
end
localmessageName
ifsubjectSpace==828then
messageName='experiment-blurb-module'
else
messageName='experiment-blurb-template'
end
returnmessage(messageName,{sandboxLinks,testcasesLinks})
end

functionp.makeCategoriesBlurb(args,env)
--[[
-- Generates the text "Please add categories to the /doc subpage."
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
-- Messages:
-- 'doc-link-display' --> '/doc'
-- 'add-categories-blurb' --> 'Please add categories to the $1 subpage.'
--]]
localdocTitle=env.docTitle
ifnotdocTitlethen
returnnil
end
localdocPathLink=makeWikilink(docTitle.prefixedText,message('doc-link-display'))
returnmessage('add-categories-blurb',{docPathLink})
end

functionp.makeSubpagesBlurb(args,env)
--[[
-- Generates the "Subpages of this template" link.
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment

-- Messages:
-- 'template-pagetype' --> 'template'
-- 'module-pagetype' --> 'module'
-- 'default-pagetype' --> 'page'
-- 'subpages-link-display' --> 'Subpages of this $1'
--]]
localsubjectSpace=env.subjectSpace
localtemplateTitle=env.templateTitle
ifnotsubjectSpaceornottemplateTitlethen
returnnil
end
localpagetype
ifsubjectSpace==10then
pagetype=message('template-pagetype')
elseifsubjectSpace==828then
pagetype=message('module-pagetype')
else
pagetype=message('default-pagetype')
end
localsubpagesLink=makeWikilink(
'Special:PrefixIndex/'..templateTitle.prefixedText..'/',
message('subpages-link-display',{pagetype})
)
returnmessage('subpages-blurb',{subpagesLink})
end

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

functionp.addTrackingCategories(env)
--[[
-- Check if {{documentation}} is transcluded on a /doc or /testcases page.
-- @env - environment table containing title objects, etc., generated with p.getEnvironment

-- Messages:
-- 'display-strange-usage-category' --> true
-- 'doc-subpage' --> 'doc'
-- 'testcases-subpage' --> 'testcases'
-- 'strange-usage-category' --> 'Wikipedia pages with strange ((documentation)) usage'
--
-- /testcases pages in the module namespace are not categorised, as they may have
-- {{documentation}} transcluded automatically.
--]]
localtitle=env.title
localsubjectSpace=env.subjectSpace
ifnottitleornotsubjectSpacethen
returnnil
end
localsubpage=title.subpageText
ifmessage('display-strange-usage-category',nil,'boolean')
and(
subpage==message('doc-subpage')
orsubjectSpace~=828andsubpage==message('testcases-subpage')
)
then
returnmakeCategoryLink(message('strange-usage-category'))
end
return''
end

returnp