Line 1: |
Line 1: |
− | {{documentation subpage}} | + | {{Documentation subpage}} |
| + | {{lua|Module:Documentation}} |
| <!-- PLEASE ADD CATEGORIES AT THE BOTTOM OF THIS PAGE AND INTERWIKIS IN WIKIDATA --> | | <!-- PLEASE ADD CATEGORIES AT THE BOTTOM OF THIS PAGE AND INTERWIKIS IN WIKIDATA --> |
| + | {{shortcut|WP:TDOC|T:DOC}} |
| | | |
− | This is the {{tl|documentation}} template. | + | This is the {{Tl|Documentation}} template. |
| | | |
| For most of the instructions about how and when to use this template, see [[Wikipedia:Template documentation]]. | | For most of the instructions about how and when to use this template, see [[Wikipedia:Template documentation]]. |
Line 11: |
Line 13: |
| | | |
| Use of this template allows templates to be [[Wikipedia:Protection policy|protected]] where necessary, while allowing anyone to edit the documentation and categories. | | Use of this template allows templates to be [[Wikipedia:Protection policy|protected]] where necessary, while allowing anyone to edit the documentation and categories. |
| + | |
| === Usage === | | === Usage === |
| | | |
Line 17: |
Line 20: |
| <pre> | | <pre> |
| <!--Last line of your template code--><noinclude> | | <!--Last line of your template code--><noinclude> |
− | | + | {{Documentation}} |
− | {{documentation}} | |
| <!-- Add categories to the /doc subpage and interwikis in Wikidata, not here! --> | | <!-- Add categories to the /doc subpage and interwikis in Wikidata, not here! --> |
| </noinclude> | | </noinclude> |
Line 29: |
Line 31: |
| <pre> | | <pre> |
| <!--Last line of your template code--><noinclude> | | <!--Last line of your template code--><noinclude> |
− | | + | {{Documentation |Template:Other page/doc}} |
− | {{documentation |Template:Other page/doc}} | |
| </noinclude> | | </noinclude> |
| </pre> | | </pre> |
| | | |
− | Note that when loading the documentation from another page than the local /doc page it becomes tricky to handle the categories and interwiki links. | + | Note that when loading the documentation from a page other than the local /doc page it becomes tricky to handle the categories and interwiki links. |
| | | |
| The content can also be fed directly as text. Like this: | | The content can also be fed directly as text. Like this: |
Line 40: |
Line 41: |
| <pre> | | <pre> |
| <!--Last line of your template code--><noinclude> | | <!--Last line of your template code--><noinclude> |
− | | + | {{Documentation |content= |
− | {{documentation |content= | |
| Some documentation text. | | Some documentation text. |
| }} | | }} |
Line 49: |
Line 49: |
| When the {{para|content}} parameter is used, the doc box normally does not show the [edit] [purge] links in the top right corner. Note that if the /doc page exists a link to it is still shown in the link box below the doc box. | | When the {{para|content}} parameter is used, the doc box normally does not show the [edit] [purge] links in the top right corner. Note that if the /doc page exists a link to it is still shown in the link box below the doc box. |
| | | |
− | Parameter {{para|1}} and the {{para|content}} parameter can also be combined, like this: | + | Parameter {{Para|1}} and the {{Para|content}} parameter can also be combined, like this: |
| | | |
| <pre> | | <pre> |
| <!--Last line of your template code--><noinclude> | | <!--Last line of your template code--><noinclude> |
− | | + | {{Documentation |
− | {{documentation | |
| |1=Template:Any page/doc | | |1=Template:Any page/doc |
| |content= | | |content= |
Line 66: |
Line 65: |
| === Best practice === | | === Best practice === |
| | | |
− | The code should be added at the bottom of the template code, with no space before {{tag|noinclude|o}} (which would cause extra space on pages where the template is used). | + | The code should be added at the bottom of the template code, with no space before {{Tag|noinclude|o}} (which would cause extra space on pages where the template is used). |
| | | |
− | Categories and interwiki links that apply to the template itself should be added to the bottom of the /doc subpage, inside {{tag|includeonly}} tags. For more complex cases, see [[Wikipedia:Template documentation#Categories and interwiki links]]. | + | Categories and interwiki links that apply to the template itself should be added to the bottom of the /doc subpage, inside {{Tag|includeonly}} tags. For more complex cases, see [[Wikipedia:Template documentation#Categories and interwiki links]]. |
| | | |
− | If the documentation page contains {{tag|includeonly|o}} or {{tag|noinclude|o}} tags as part of the visible documentation text, replace the "<code><</code>" with "<code>&lt;</code>". | + | If the documentation page contains {{Tag|includeonly|o}} or {{Tag|noinclude|o}} tags as part of the visible documentation text, replace the "<code><</code>" with "<code>&lt;</code>". |
| | | |
| === The heading === | | === The heading === |
Line 85: |
Line 84: |
| The '''heading''' parameter can be used to set the heading to something else. Like this: | | The '''heading''' parameter can be used to set the heading to something else. Like this: |
| | | |
− | :<code><nowiki>{{documentation |heading=Infobox documentation}}</nowiki></code> | + | :<code><nowiki>{{Documentation |heading=Infobox documentation}}</nowiki></code> |
| | | |
| If the '''heading''' parameter is empty but defined, no heading is shown and no [edit] [purge] links are shown. Like this: | | If the '''heading''' parameter is empty but defined, no heading is shown and no [edit] [purge] links are shown. Like this: |
| | | |
− | :<code><nowiki>{{documentation |heading=}}</nowiki></code> | + | :<code><nowiki>{{Documentation |heading=}}</nowiki></code> |
| | | |
| The '''heading-style''' parameter can be fed optional [[Cascading Style Sheets|CSS]] values. Without quotation marks <code>" "</code> but with the ending semicolons <code>;</code>. For example: | | The '''heading-style''' parameter can be fed optional [[Cascading Style Sheets|CSS]] values. Without quotation marks <code>" "</code> but with the ending semicolons <code>;</code>. For example: |
Line 100: |
Line 99: |
| To hide the link box, add the parameter {{para|link box|off}}. | | To hide the link box, add the parameter {{para|link box|off}}. |
| | | |
− | You can also insert customised text in the link box, by defining the {{para|link box}} parameter. For example: | + | You can also insert customised text in the link box, by defining the {{Para|link box}} parameter. For example: |
− | {{para|link box|This documentation is automatically generated by [<nowiki />[Template:Country showdata]]}} | + | {{Para|link box|This documentation is automatically generated by [<nowiki />[Template:Country showdata]]}} |
| | | |
| === Automatic functions === | | === Automatic functions === |
Line 107: |
Line 106: |
| If the documentation page does not exist, the [create] link includes a [[mw:Manual:Creating pages with preloaded text|preload]] page so that clicking it will pre-fill the edit form with the basic documentation page format. Preload text is also used for the /sandbox and /testcases <small>(create)</small> links. | | If the documentation page does not exist, the [create] link includes a [[mw:Manual:Creating pages with preloaded text|preload]] page so that clicking it will pre-fill the edit form with the basic documentation page format. Preload text is also used for the /sandbox and /testcases <small>(create)</small> links. |
| | | |
− | When this template is on a protected template page it now automatically adds {{tl|pp-template}} which shows the grey or red padlock in the top right corner. So no need to manually add {{tlf|pp-template}} to templates that use {{tl|documentation}}. | + | When this template is on a protected template page it now automatically adds {{tl|pp-template}} which shows the grey or red padlock in the top right corner. So no need to manually add {{tlf|pp-template}} to templates that use {{Tl|Documentation}}. |
| | | |
− | When this template is on a /sandbox subpage it automatically adds the {{tl|template sandbox notice}}. If that sandbox is not a subpage of the live template, then the {{para|livepage}} parameter can be used to correctly link back to that template. | + | When this template is on a /sandbox subpage it automatically adds the {{Tl|Template sandbox notice}}. |
| | | |
| === Subject namespaces vs. talk namespaces === | | === Subject namespaces vs. talk namespaces === |
Line 115: |
Line 114: |
| Terminology: ''Subject namespaces'' are the opposite of ''talk namespaces''. For instance "Template:" is the subject space of "Template talk:". | | Terminology: ''Subject namespaces'' are the opposite of ''talk namespaces''. For instance "Template:" is the subject space of "Template talk:". |
| | | |
− | This template is usually placed in a subject namespace, within {{tag|noinclude|o}} tags. But in some cases this template needs to be on the talk page: | + | This template is usually placed in a subject namespace, within {{Tag|noinclude|o}} tags. But in some cases this template needs to be on the talk page: |
− | | |
− | * For preload pages (usually in Template or Wikipedia namespaces), since they cannot use {{tag|noinclude|o}}. See for instance, [[Template talk:AfC preload]] and [[Template talk:RfD subpage starter]]. Such talk pages can be marked with {{tl|talkdoc}}.
| |
| | | |
− | * In the Mediawiki namespace, since {{tag|noinclude|o}} often does not work in system messagesm and since the Mediawiki namespace needs to be kept clean for performance reasons. | + | * In the Mediawiki namespace, since {{tag|noinclude|o}} often does not work in system messages, and since the Mediawiki namespace needs to be kept clean for performance reasons. |
| | | |
− | When placed on talk pages, this template usually is placed near the top of the page and without {{tag|noinclude}} tags. | + | When placed on talk pages, this template usually is placed near the top of the page and without {{Tag|noinclude}} tags. |
| | | |
| The /doc, /sandbox and /testcases pages should normally be in the subject namespace, except in the namespaces that do not have the MediaWiki [[meta:Link#Subpage feature|subpage feature]] enabled: Main, File, Mediawiki and Category. (But currently we only show the /sandbox and /testcases links from User, User talk, Template and Template talk namespaces.) There are also a whole bunch of other technical reasons why the /doc page must be stored under the talk page for those (but only those) namespaces. | | The /doc, /sandbox and /testcases pages should normally be in the subject namespace, except in the namespaces that do not have the MediaWiki [[meta:Link#Subpage feature|subpage feature]] enabled: Main, File, Mediawiki and Category. (But currently we only show the /sandbox and /testcases links from User, User talk, Template and Template talk namespaces.) There are also a whole bunch of other technical reasons why the /doc page must be stored under the talk page for those (but only those) namespaces. |
| | | |
| This template automatically points its <small>[create]</small> links for the /doc, /sandbox and /testcases to the right namespace. | | This template automatically points its <small>[create]</small> links for the /doc, /sandbox and /testcases to the right namespace. |
| + | |
| + | === Testing === |
| + | |
| + | You can simulate the output for a given page by using the {{para|page}} parameter. For example, if you use the code {{para|page|Template:Edit protected}}, the template will behave exactly as if it were on the page [[Template:Edit protected]], including showing the documentation from [[Template:Edit protected/doc]], linking to [[Template:Edit protected/sandbox]], etc. This parameter is useful for testing, and is used extensively on the [[Module:Documentation/testcases|module test cases page]]. |
| | | |
| === Technical details === | | === Technical details === |
| | | |
− | This template calls {{tl|documentation/start box2}} and {{tl|documentation/end box2}} which in turn call {{tl|documentation/start box}} and {{tl|documentation/end box}}. The /start box (and /end box) hold most of the code, while this template and /start box2 (and /end box2) do parameter preprocessing. | + | This template calls {{Tl|Documentation/start box2}} and {{Tl|Documentation/end box2}} which in turn call {{Tl|Documentation/start box}} and {{tl|documentation/end box}}. The /start box (and /end box) hold most of the code, while this template and /start box2 (and /end box2) do parameter preprocessing. |
| | | |
− | The preload page for the /doc <small>[create]</small> link is [[Template:Documentation/preload]], but in File namespace it is [[Template:Documentation/preload-filespace]]. The preload pages for the /sandbox and /testcases <small>[create]</small> links are [[Template:Documentation/preload-sandbox]] and [[Template:Documentation/preload-testcases]]. | + | The preload page for the /doc <small>[create]</small> link is [[Template:Documentation/preload]]. The preload pages for the /sandbox and /testcases <small>[create]</small> links are [[Template:Documentation/preload-sandbox]] and [[Template:Documentation/preload-testcases]]. |
| | | |
| For more technical details see the [[Template talk:Documentation|talk page]]. | | For more technical details see the [[Template talk:Documentation|talk page]]. |
Line 137: |
Line 138: |
| === See also === | | === See also === |
| | | |
− | <!-- {{documentation/see also}} -->
| + | * {{Tl|Documentation}} – Placed on templates and other pages to document them. |
− | * {{tl|documentation}} – Placed on templates and other pages to document them. | + | * {{Tl|Documentation subpage}} – Used at the top of /doc subpages to explain what they are and to link back to the page they document. |
− | * {{tl|documentation subpage}} – Used at the top of /doc subpages to explain what they are and to link back to the page they document. | + | * {{Tl|Documentation/color scheme}} - color scheme for related background colors (green border, etc.) |
− | * {{tl|barnstar documentation}} – Variant specifically for [[WP:BARNSTAR|barnstar]] templates | + | * {{Tl|Barnstar documentation}} – Variant specifically for [[WP:BARNSTAR|barnstar]] templates |
| * [[Wikipedia:Template documentation]] – The how-to guide about template documentation. | | * [[Wikipedia:Template documentation]] – The how-to guide about template documentation. |
| * [[Wikipedia:Template test cases]] – How to use /sandbox and /testcases subpages and more about template testing. | | * [[Wikipedia:Template test cases]] – How to use /sandbox and /testcases subpages and more about template testing. |
| | | |
| <includeonly> | | <includeonly> |
− | <!-- CATEGORIES AND INTERWIKIS HERE, THANKS --> | + | <!-- ADD CATEGORIES HERE, THANKS --> |
| [[Category:Template documentation]] | | [[Category:Template documentation]] |
| [[Category:Wikipedia formatting and function templates]] | | [[Category:Wikipedia formatting and function templates]] |
| </includeonly> | | </includeonly> |