Template:Category handler/doc: Difference between revisions

Line 27:

Typically, this template is used as part of another template, so use something like <code><nowiki>debug={{{debug|}}}</nowiki></code>, so that <code><nowiki>debug=1</nowiki></code> can be added to an instance of that template.

== Category suppression ==

== Category suppression rules and use-cases ==

By default, this metatemplate allows categories within the following namespaces: main, file, mediawiki, template, category, and module. Templates placed ~~within~~ those namespaces will not categorize those pages.

By default, this metatemplate allows categories within the following namespaces: main, file, mediawiki, template, category, and module. Templates placed outside of those namespaces will not categorize those pages. Additionally, pages with the suffix /doc or /sandbox will not be categorized.

This metatemplate is meant primarily for templates used within those namespaces. Use of this metatemplate is not required for templates with basic categorizing rules, or templates meant to be placed within other namespaces such as the user namespace.

This metatemplate is meant primarily for templates used within those namespaces. Use of this metatemplate is not required for templates with basic categorizing rules, or templates meant to be placed within other namespaces such as the user namespace. Additionally, specialized templates meant for categorizing /doc pages are unable to work with this template.

~~Alternatively, this~~ template can be adjusted to allow or disallow suppression in different namespaces. The example below allows a template to add categories a page within the user namespace, but not templates or modules. Namespaces are delimited using either newlines or semicolons.

=== Changing suppressed namespaces ===

This template can be adjusted to allow or disallow suppression in different namespaces. The example below allows a template to add categories a page within the user namespace, but not templates or modules. Namespaces are delimited using either newlines or semicolons.

<code><nowiki>{{category handler | allowed_ns = user | suppressed_ns = template; module}}</nowiki></code>

~~Additionally~~, ~~this metatemplate suppresses categories if the~~ page ~~has the following suffixes (subpages): doc or sandbox~~. ~~This prevents~~ templates ~~from categorizing test or documentation pages, but not if the~~ /doc page is transcluded~~. This means categorizing templates~~ that ~~categorize other templates will the~~ template's ~~main~~ page, ~~but not their~~ /~~doc subpages. However, if~~ a ~~categorizing~~ template's ~~documentation is demonstrating its own use~~, ~~this isn't enough, so~~ adding <code><nowiki>~~debug~~=1</nowiki></code> ~~is required~~ to ~~keep categorizing templates~~ from ~~erroneously~~ categorizing ~~themselves~~.

=== Use-case: templates that categorize templates ===

Templates are sometimes added to template documentation, such as [[Template:Todo]], which categorizes that page under a specific todo-task. Typically, such templates are added to a template's /doc page to be transcluded onto that template's page, instead of within the <code><nowiki><noinclude></noinclude></nowiki></code> block of a template's page.

For example, adding <code><nowiki>{{Todo|inline=1|add documentation}}</nowiki></code> to a template's documentation adds that template to [[:Category:Todo:add documentation]], but a naive implementation of that template will also categorize that template's /doc subpage.

<pre>

{{#if: {{{inline|}}} | {{Mbox

| type = notice

| icon = Icon-Todo.png

| text = '''Todo:''' {{#if: {{{1|}}}| {{{1}}} }}

{{#if: {{{comment|}}}}}

}}

{{#if: {{{1|}}} | [[Category:Todo:{{trim|{{{1}}}}}]] | [[Category:Todo]] }}

</pre>

If placed on a template called SomeTemplate, the todo-category will contain these pages:

* Template:SomeTemplate (template page)

* Template:SomeTemplate/doc (template's documentation)

Since this template suppresses categories on /doc subpages, this template to Template:Todo prevents it from categorizing the documentation page, meaning only Template:SomeTemplate is categorized.