Template:Script doc auto

From OniGalore
Jump to navigation Jump to search

Script doc auto is a clever system composed of this template page, two subpages (/core and /core2), and the built-in MediaWiki page Clearyourcache, designed to automatically lead the reader to documentation for code pages (.css and .js pages) on the wiki. The idea behind the design is that you never have to place this template anywhere; the Clearyourcache page, which is already hardcoded to appear on code pages, will transclude this template if the namespace is MediaWiki. (Code pages can also appear in the User namespace, but we don't need to encourage documentation for personalized code, so we screen for just the MediaWiki namespace.)

The template uses ParserFunctions' string functions to look at the name of the page and search for sister pages and docs pages, and display a link to them in a message box above the code. For instance, the page MediaWiki:Common.css will link to its sister page, MediaWiki:Common.js, as well as the docs page. If there is no docs page, you will be given a redlink for making one. (The template is basically enforcing a system whereby a .js or .css page is documented on a page with the same address as the code page, minus the suffix.)

Why go through all this trouble? On an ordinary page, including a template page, you would simply put the documentation right on the page inside <noinclude> tags or transclude it from a /doc page, but that's not possible on a code page. This system gets around the limitation by piggy-backing on the existing "Clear your cache" header message in the MediaWiki software.

P.S.: A hidden ability of this template is that, if you desire, you can transclude it manually somewhere and pass it a "page=pagename" parameter, and it will run the same checks and present the same messages, but for the page that you supplied the name of, not the page the template is on.