Template:Doc/doc: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(Created page with "<noinclude>Category:English{{doc|0}}</noinclude>__NOTOC__ The template <code style=padding:0>{{tl|doc}}</code> is designed to add a block of documentation to various pages...")
 
 
(32 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<noinclude>[[Category:English]]{{doc|0}}</noinclude>__NOTOC__
<noinclude>{{Doc/subpage}}</noinclude>
The template <code style=padding:0>{{tl|doc}}</code> is designed to add a block of documentation to various pages (mainly template pages). The subpages of a certain language will be loaded into the documentation block depending on the language of the user interface. In the case of English, the documentation will be taken from the <code style=padding:0>/doc</code> subpage. But in all other cases, the documentation will be taken from the subpage <code style=padding:0>/doc/<lang code></code>


==Tools==
<div style="display:flex;"><div>
The template <kbd>{{tl2|doc}}</kbd> is designed to add a block of documentation to various pages (mainly template pages). The subpages of a certain language will be loaded into the documentation block depending on the language of the user interface. In the case of English, the documentation will be taken from the {{Code|style=1|<kbd>/doc</kbd>}} subpage. But in all other cases, the documentation will be taken from the subpage {{Code|style=1|<kbd>/doc/<[[Template:Lang|lang code]]></kbd>}}
 
== Tools ==
The main tools are located on the top right, above the documentation block:
The main tools are located on the top right, above the documentation block:
*«Create» – opens the creation of the documentation page. Appears only if the documentation page does not exist.
* {{Code|style=2|Create}} – opens the creation of the documentation page. Appears only if the documentation page does not exist.
*«View» – opens the documentation page.
{{Note|If there are none of any documentations, the button will load a preload documentation, {{Code|[[Template:Doc/preload]]}} or {{Code|Template:Doc/preload/<[[Template:Lang|lang code]]>}} (if the UI language isn't in English and the translations of the preload page exist), as the content of the new page and open the editing page. If there is a English documentation, the button will preload the English documentation as the content.}}
*«Edit» – opens the editing of the documentation page.
* {{Code|style=2|View}} – opens the documentation page.
*«History» – opens the history of changes to the documentation page.
* {{Code|style=2|Edit}} – opens the editing of the documentation page.
{{note|If there are none of the above tools, then the text of the documentation was written using the {{param|content}} parameter.}}
* {{Code|style=2|History}} – opens the history of changes to the documentation page.
{{Note|If there are none of the above tools, then the text of the documentation was written using the {{Param|content}} parameter, or parameter {{Param|tools}} was set to 0.}}


Also, in the upper right corner there is a button marked with an ellipsis [ '''…''' ]. It expands/collapses additional tools:
Also, in the upper right corner there is a button marked with an ellipsis [ '''…''' ]. It expands/collapses additional tools:
*«Sandbox» – opens the creation of a subpage <code style=padding:0>/sandbox</code> and copies the code of the original page, or, if this page exists, simply opens it.
* {{Code|style=2|Sandbox}} – opens the creation of a subpage {{Code|style=1|<kbd>/sandbox</kbd>}} and copies the code of the original page, or, if this page exists, simply opens it.
*«Testcases» – opens the <code style=padding:0>/testcases</code> subpage. Useful for testing a template in different situations.
* {{Code|style=2|Testcases}} – opens the {{Code|style=1|<kbd>/testcases</kbd>}} subpage. Useful for testing a template in different situations.
*«Subpages» – opens [[Special:PrefixIndex]] and inserts the page name to search for all subpages.
* {{Code|style=2|Subpages}} – opens [[Special:PrefixIndex]] and inserts the page name to search for all subpages.
*«Purge» – opens a window with a message about purging the page.
* {{Code|style=2|Purge}} – opens a window with a message about purging the page.
 
== Language bar ==
On the top right, under the tools, there are flags that switch documentation to another language. Switching is implemented by inserting {{Code|style=1|1=<kbd>&uselang=<[[Template:Lang|lang code]]></kbd>}} into the page link, so if you click on another language, then along with the documentation, the interface language will change.
 
If there is no documentation in a certain language, the message “The <page> documentation page does not exist” will be displayed. if {{Param|pagespace}} or actual page space is {{code|User}}, then the message “The <user> did not provide information about himself on this language (<page>).” will be displayed instead. Also, after this message, documentation in English will be displayed, if it exists.
 
== Parameters ==
* {{Param|1}}: parameter for switching the template assignment:
** If you need a standard documentation block, do not enter anything in this parameter.
** 0 – will display the message “This is a documentation subpage for <page>”.
** 1 – will display the message “This is the sandbox subpage for <page>”.
** 2 – will display the message “This page is not a sandbox”.
** 3 – will display the message “This is the <page> info subpage”. Useful for user subpages.
** 4 – will display the message “This is a documentation subpage for use on multiple pages”. If the {{Param|list}} parameter is used, then the text will be: “This is a documentation subpage for use on multiple pages listed in <list page>”.
* {{Param|list}}: specifies a page or category that lists pages using a particular documentation page. Used only if parameter {{Param|1}} is set to 4.
* {{Param|docpage}}: the page that will be used as documentation.
* {{Param|DocParam1}} to {{Param|DocParam5}}: Optional parameters passed to the documentation page (the /doc subpage and supported by {{Param|docpage}}).
** If the documentation uses {{Param|DocParam1}}, then passing {{Param|DocParam1}} in the template transclusion (e.g. {{Code|<nowiki>{{Doc|DocParam1=Hello World!}}</nowiki>}}) will affect how the doc is rendered, good for documentation pages only needing a different value.
* {{Param|content</lang code>}}: content that will be used as documentation, instead of a separate page. When used, the main tools are hidden.
* {{Param|pagespace}}: the page space is determined automatically, but you can enter your own. The text in the header depends on this parameter:
** Template → “Template Documentation”
** File → “Summary”
** User → “About”
** In all other cases it will be “Documentation”
{{Note|if {{Param|pagespace}} or actual page space is “User”, then the text will be taken from the /about subpage, not /doc.}}
* {{Param|tools}}: controls which tool buttons should be displayed:
** 0 – no buttons.
** 1 – only buttons “Create”, “View”, “Edit” and “History”.
** In all other cases there will be all buttons
 
== Creating documentation ==
{{warning|If you want to add the symbol “&#124;” somewhere in the text (templates and other MediaWiki elements are not affected), use {{code|select=1|&&#35;124;}}.}}
To start creating documentation, click on the “Create” button on the top right. The button loads the preloaded document (or as a preloaded document if there is an English document). Then the text of the documentation itself is written. First there is a brief description, and then – depending on what the documentation is written for. If you want to add categories, just add them where the preload documentation indicated.
 
== Subpages ==
There are some subpages and sub-templates on {{tl2|Doc}}. They are created to make the things easier.
 
=== {{tl2|Doc/subpage}} ===
This template is the replacement of {{Code|1=<nowiki><noinclude>{{doc|0}}</noinclude></nowiki>|select=1}}. It can be instead of {{Code|1=<nowiki><noinclude>{{doc|0}}</noinclude></nowiki>|select=1}}.


==Language bar==
Its purpose is the same as {{tl2|Documentation subpage}}.
On the top right, under the tools, there are flags that switch documentation to another language. Switching is implemented by inserting <code style=padding:0>&uselang=<language code></code> into the page link, so if you click on another language, then along with the documentation, the interface language will change.


The language bar can be removed if you set {{param|nolang}} to 1.
It can avoid the problem that preload page won't load {{Code|1=<nowiki><noinclude>{{doc|0}}</noinclude></nowiki>|select=1}}.


If there is no documentation in a certain language, the message “The <page> documentation page does not exist” will be displayed, and the language flag will be highlighted in red.
=== {{tl2|Doc/Sandbox other}} ===
This template adds content separately to the main template and its subpages (documents). It is useful for adding categories.


==Parameters==
Its purpose is the same as {{tl2|Sandbox other}}.
*{{param|1}}: parameter for switching the template assignment:
**If you need a standard documentation block, do not enter anything in this parameter.
**0 – will display the message “This is a documentation subpage for <page>”.
**1 – will display the message “This is the sandbox subpage for <page>”.
**2 – will display the message “This page is not a sandbox”.
*{{param|docpage}}: the page that will be used as documentation.
*{{param|content</lang code>}}: content that will be used as documentation, instead of a separate page. When used, the main tools are hidden.
*{{param|pagespace}}: the page space is determined automatically, but you can enter your own. The text in the header depends on this parameter:
**Template → “Template Documentation”
**File → “Summary”
**In all other cases it will be “Documentation”
*{{param|nolang}}: removes the language bar if set to 1.
*{{param|examples}}: examples that can be copied and used on other pages go here. When used, the “Examples” button appears, on the left under the title of the documentation block.


==Creating documentation==
=== [[Template:Doc/preload]] ===
To start creating documentation, click on the “Create” button on the top right. At the very beginning of the documentation, add the template <code style=padding:0>{{tl|doc}}</code> and enter 0 in the parameter {{param|1}}. After that, you will see a message stating that this is a documentation subpage. And so that this message does not appear in the documentation block, it should be written in this way:
This is the preload page when you click the create button. You can add translations for it.


<code style=padding:0><nowiki><noinclude>{{doc|0}}</noinclude></nowiki></code>
=== {{tl2|Doc/PreviewBlock}} ===
'''Deprecated.''' Use {{tl2|Capsule}} instead.
</div>


Then the text of the documentation itself is written. First there is a brief description, and then – depending on what the documentation is written for.
<div>
{{warning|If you want to add the symbol “&#124;” somewhere in the text (templates and other MediaWiki elements are not affected), use <code>&&#35;124;</code>.}}
{{infobox template
| summary      = Transcludes a documentation subpage
| type        = Wrapper template
| creationdate = 22/08/2022<br><small>(22 August 2022)</small>
| other        = [[{{FULLBASEPAGENAME}}/subpage|/subpage]]<br>[[{{FULLBASEPAGENAME}}/Sandbox other|/Sandbox other]]
| translation  = Yes
| parser      = Yes
| var          = Yes
| float        = none
}}
</div></div>
{{Doc/Sandbox other|[[Category:English]][[Category:Templates]]}}

Latest revision as of 08:02, 8 May 2025

Edit-copy.png
This is a documentation subpage for Template:Doc.
Don't forget to purge the contents of the base page upon creating or editing this subpage.

The template {{doc}} is designed to add a block of documentation to various pages (mainly template pages). The subpages of a certain language will be loaded into the documentation block depending on the language of the user interface. In the case of English, the documentation will be taken from the /doc subpage. But in all other cases, the documentation will be taken from the subpage /doc/<lang code>

Tools

The main tools are located on the top right, above the documentation block:

  • Create – opens the creation of the documentation page. Appears only if the documentation page does not exist.
Note.pngNote:If there are none of any documentations, the button will load a preload documentation, Template:Doc/preload or Template:Doc/preload/<lang code> (if the UI language isn't in English and the translations of the preload page exist), as the content of the new page and open the editing page. If there is a English documentation, the button will preload the English documentation as the content.
  • View – opens the documentation page.
  • Edit – opens the editing of the documentation page.
  • History – opens the history of changes to the documentation page.
Note.pngNote:If there are none of the above tools, then the text of the documentation was written using the {{{content}}} parameter, or parameter {{{tools}}} was set to 0.

Also, in the upper right corner there is a button marked with an ellipsis [ … ]. It expands/collapses additional tools:

  • Sandbox – opens the creation of a subpage /sandbox and copies the code of the original page, or, if this page exists, simply opens it.
  • Testcases – opens the /testcases subpage. Useful for testing a template in different situations.
  • Subpages – opens Special:PrefixIndex and inserts the page name to search for all subpages.
  • Purge – opens a window with a message about purging the page.

Language bar

On the top right, under the tools, there are flags that switch documentation to another language. Switching is implemented by inserting &uselang=<lang code> into the page link, so if you click on another language, then along with the documentation, the interface language will change.

If there is no documentation in a certain language, the message “The <page> documentation page does not exist” will be displayed. if {{{pagespace}}} or actual page space is User, then the message “The <user> did not provide information about himself on this language (<page>).” will be displayed instead. Also, after this message, documentation in English will be displayed, if it exists.

Parameters

  • {{{1}}}: parameter for switching the template assignment:
    • If you need a standard documentation block, do not enter anything in this parameter.
    • 0 – will display the message “This is a documentation subpage for <page>”.
    • 1 – will display the message “This is the sandbox subpage for <page>”.
    • 2 – will display the message “This page is not a sandbox”.
    • 3 – will display the message “This is the <page> info subpage”. Useful for user subpages.
    • 4 – will display the message “This is a documentation subpage for use on multiple pages”. If the {{{list}}} parameter is used, then the text will be: “This is a documentation subpage for use on multiple pages listed in <list page>”.
  • {{{list}}}: specifies a page or category that lists pages using a particular documentation page. Used only if parameter {{{1}}} is set to 4.
  • {{{docpage}}}: the page that will be used as documentation.
  • {{{DocParam1}}} to {{{DocParam5}}}: Optional parameters passed to the documentation page (the /doc subpage and supported by {{{docpage}}}).
    • If the documentation uses {{{DocParam1}}}, then passing {{{DocParam1}}} in the template transclusion (e.g. {{Doc|DocParam1=Hello World!}}) will affect how the doc is rendered, good for documentation pages only needing a different value.
  • {{{content</lang code>}}}: content that will be used as documentation, instead of a separate page. When used, the main tools are hidden.
  • {{{pagespace}}}: the page space is determined automatically, but you can enter your own. The text in the header depends on this parameter:
    • Template → “Template Documentation”
    • File → “Summary”
    • User → “About”
    • In all other cases it will be “Documentation”
Note.pngNote:if {{{pagespace}}} or actual page space is “User”, then the text will be taken from the /about subpage, not /doc.
  • {{{tools}}}: controls which tool buttons should be displayed:
    • 0 – no buttons.
    • 1 – only buttons “Create”, “View”, “Edit” and “History”.
    • In all other cases there will be all buttons

Creating documentation

Warning.pngWarning:If you want to add the symbol “|” somewhere in the text (templates and other MediaWiki elements are not affected), use &#124;.

To start creating documentation, click on the “Create” button on the top right. The button loads the preloaded document (or as a preloaded document if there is an English document). Then the text of the documentation itself is written. First there is a brief description, and then – depending on what the documentation is written for. If you want to add categories, just add them where the preload documentation indicated.

Subpages

There are some subpages and sub-templates on {{Doc}}. They are created to make the things easier.

{{Doc/subpage}}

This template is the replacement of <noinclude>{{doc|0}}</noinclude>. It can be instead of <noinclude>{{doc|0}}</noinclude>.

Its purpose is the same as {{Documentation subpage}}.

It can avoid the problem that preload page won't load <noinclude>{{doc|0}}</noinclude>.

{{Doc/Sandbox other}}

This template adds content separately to the main template and its subpages (documents). It is useful for adding categories.

Its purpose is the same as {{Sandbox other}}.

Template:Doc/preload

This is the preload page when you click the create button. You can add translations for it.

{{Doc/PreviewBlock}}

Deprecated. Use {{Capsule}} instead.

Template:Doc
Logo-template.png
Summary
Transcludes a documentation subpage
Type
Wrapper template
Contributors
N/A
Creation date
22/08/2022
(22 August 2022)
Notes
N/A
Subpages
Documentation
Preload
Sandbox
Strings
Testcases
N/A
Revision information
Latest editor
N0one
Last edited
08/05/2025
20250508080213
Revision size
7262 bytes
7.262 kilobytes
0.007262 megabytes
Technical information
Page identifier
47853
Contains translations
Yes
Uses parser functions?
Yes
Uses variables?
Yes
Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Template:Doc/doc&oldid=475613"