Template:Documentation:zh-cn/doc: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(Created page with "{{translate:zh-cn}} {{Distinguish:zh-cn|Template:Documentation subpage}} {{Documentation subpage:zh-cn}} {{Wikipedia port|modified=1|documentation=1}} <!---- Categories where...")
 
No edit summary
Line 1: Line 1:
{{translate:zh-cn}}
本模板由[[User:1416006136|大康]]翻译。本模板的功能文本翻译于2021年9月19日 (日) 14:03‎（中国标准时间），描述文本翻译于2022年1月15日。部分内容由机器翻译。
----
{{Distinguish:zh-cn|Template:Documentation subpage}}
{{Distinguish:zh-cn|Template:Documentation subpage}}
{{Documentation subpage:zh-cn}}
{{Documentation subpage:zh-cn}}
{{Wikipedia port|modified=1|documentation=1}}
{{Wikipedia port:zh-cn|modified=1|documentation=1}}


<!---- Categories where indicated at the bottom of this page, please ---->
<!---- Categories where indicated at the bottom of this page, please ---->


This is the {{tl|Documentation}} template used on almost every template page to contain that template's documented instructions and information.
这是几乎每个模板页面上使用的 {{tl|Documentation}} 模板，以包含该模板的文档说明和信息。


This template displays a gray documentation box like you are seeing now and automatically loads the content from a /doc subpage. It can also load the content from other places if instructed to.
该模板显示一个灰色的文档框，就像您现在看到的那样，并自动从 /doc 子页面加载内容。如果有指示，它还可以从其他地方加载内容。


This template is intended for documenting templates and other pages that are transcluded onto other pages. It can be used in the template namespace and most other namespaces.
此模板用于记录模板和嵌入到其他页面的其他页面。它可以在模板命名空间和大多数其他命名空间中使用。


Use of this template allows templates to be protected where necessary, while allowing anyone to edit the documentation and categories.
使用此模板可以在必要时保护模板，同时允许任何人编辑文档和类别。


===Usage===
===用法===
Normally this template is used without any parameters, placed at the bottom of the template or page being documented, within a {{tag|noinclude}} container:
通常这个模板在没有任何参数的情况下使用，放置在模板或页面的底部，在一个 {{tag|noinclude}} 容器中：


<source lang="xml+smarty">
<source lang="xml+smarty">
<!--Last line of your template code--><noinclude>
<!--模板代码的最后一行--><noinclude>
{{Documentation}}
{{Documentation:zh-cn}}
<!-- Add categories to the /doc subpage, not here -->
<!-- 将类别添加到 /doc 子页面，不在此处 -->
</noinclude>
</noinclude>
</source>
</source>


Then this template automatically loads the content from the /doc subpage of the template it is used on.
然后此模板会自动从使用它的模板的 /doc 子页面加载内容。


This template can also load the content from any other page. Like this:
此模板还可以从任何其他页面加载内容。像这样：


<source lang="xml+smarty">
<source lang="xml+smarty">
<!--Last line of your template code--><noinclude>
<!--模板代码的最后一行--><noinclude>
{{Documentation |Template:Other page/doc}}
{{Documentation:zh-cn |Template:(其他页面名称)/doc}}
</noinclude>
</noinclude>
</source>
</source>


Note that when loading the documentation from a page other than the local /doc page it becomes tricky to handle the categories.
请注意，当从本地 /doc 页面以外的页面加载文档时，处理类别变得很棘手。


The content can also be fed directly as text. Like this:
内容也可以直接作为文本提供。像这样：


<source lang="xml+smarty">
<source lang="xml+smarty">
<!--Last line of your template code--><noinclude>
<!--模板代码的最后一行--><noinclude>
{{Documentation
{{Documentation:zh-cn
  | content =
  | content =
(some documentation)
(一些文本)
}}</noinclude>
}}</noinclude>
</source>
</source>


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.
使用 {{para|content}} 参数时，文档框通常不会在右上角显示 [edit] [purge] 链接。请注意，如果 /doc 页面存在，指向它的链接仍会显示在 doc 框下方的链接框中。


Parameter {{para|1}} and the {{para|content}} parameter can also be combined, like this:
参数 {{para|1}} 和 {{para|content}} 参数也可以组合，如下所示：


<source lang="xml+smarty">
<source lang="xml+smarty">
<!--Last line of your template code--><noinclude>
<!--模板代码的最后一行--><noinclude>
{{Documentation |1=Template:Any page/doc
{{Documentation:zh-cn |1=Template:Any page/doc
| content =
| content =
{{Template:Any page/doc |parameters}}
{{Template:(任一页面)/doc |parameters}}
}}</noinclude>
}}</noinclude>
</source>
</source>


Then the pagename fed as parameter 1 is used for the [edit] [purge] links and for the /doc link in the link box below the doc box. But the '''content''' parameter is used for the content shown in the doc box. The above code means that the content is transcluded as {{tnull|Template:Any page/doc{{!}}parameters}}. In this example a parameter is also fed to the /doc page being loaded.
然后作为参数 1 提供的页面名称用于 [edit] [purge] 链接和文档框下方链接框中的 /doc 链接。但是 '''content''' 参数用于文档框中显示的内容。上述代码表示内容被嵌入为{{tnull|Template:(任一页面)/doc{{!}}parameters}}。在这个例子中，一个参数也被提供给正在加载的 /doc 页面。


=== Shortcut ===
=== 小技巧 ===
To automatically insert the noinclude tags, the template call and the guiding comment, use this [[Wikipedia:Substitution|substitution]] code:<br>
要自动插入 noinclude 标记、模板调用和指导性注释，请使用以下[[Wikipedia:Substitution|代替]]代码：<br>


:<code><nowiki>{{subst:doc-code}}</nowiki></code>
:<code><nowiki>{{subst:doc-code}}</nowiki></code>


===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).
代码应该添加在模板代码的底部，{{Tag|noinclude|o}} 之前没有空格（这会导致使用模板的页面上有额外的空间）。


Categories that apply to the template itself should be added to the bottom of the /doc subpage, inside {{Tag|includeonly}} tags.
适用于模板本身的类别应添加到 /doc 子页面底部的 {{Tag|includeonly}} 标签内。


If the documentation page contains {{tag|includeonly|o}} or {{tag|noinclude|o}} tags as part of the visible documentation text, replace the "<code>&lt;</code>" with "<code>&amp;lt;</code>" or use [[Template:tag]].
如果文档页面包含 {{tag|includeonly|o}} 或 {{tag|noinclude|o}} 标记作为可见文档文本的一部分，请将“<code><</code>”替换为“<code> &lt;</code>" 或使用 [[Template:tag]]。


===Heading===
===标题===
When in the Template namespace, this template shows this heading:
在模板命名空间中，此模板显示以下标题：
:[[File:Curly_brackets_white.png|44px|link=]] '''Template documentation'''
:[[File:Curly_brackets_white.png|44px|link=]] '''模板文档'''


In most other namespaces, such as "Wikipedia:", it shows this heading:
在大多数其他名称空间中，例如“Wikipedia:”，它显示以下标题：
:'''Documentation'''
:'''文档'''


But when on File (image) pages it shows this heading:
但是当在文件（图像）页面上时，它会显示这个标题：
:'''Summary'''
:'''摘要'''


The '''heading''' parameter can be used to set the heading to something else. Like this:
'''heading''' 参数可用于将标题设置为其他内容。像这样：


:<code><nowiki>{{Documentation |heading=Infobox documentation}}</nowiki></code>
:<code><nowiki>{{Documentation:zh-cn |heading=信息框文档}}</nowiki></code>


If the '''heading''' parameter is empty but defined, no heading is shown and no [edit] [purge] links are shown. Like this:
如果 '''heading''' 参数为空但已定义，则不显示标题并且不显示 [edit] [purge] 链接。像这样：


:<code><nowiki>{{Documentation |heading=}}</nowiki></code>
:<code><nowiki>{{Documentation:zh-cn |heading=}}</nowiki></code>


The '''heading-style''' parameter can be fed optional CSS values. Without quotation marks <code>" "</code> but with the ending semicolons <code>;</code>. For example:
'''heading-style''' 参数可以提供可选的 CSS 值。不带引号 <code>" "</code> 但带有结尾分号 <code>;</code>。例如：
:<code>heading-style=font-size:150%;color:red;</code>
:<code>heading-style=font-size:150%;color:red;</code>


===Link box===
===链接框===
Below the big doc box is a small link box that shows some meta-data about the documentation. The link box shows different things depending on what parameters are fed to this template, and in which namespace it is used. In some cases the link box is not shown at all.
大文档框下方是一个小链接框，显示有关文档的一些元数据。链接框根据提供给该模板的参数以及在哪个名称空间中使用它来显示不同的内容。在某些情况下，链接框根本不显示。


To hide the link box, add the parameter
要隐藏链接框，请添加参数
: {{para|link box|off}}.
: {{para|link box|off}}.


You can also insert customised text into the link box, by setting the {{para|link box}} parameter. For example:
您还可以通过设置 {{para|link box}} 参数将自定义文本插入到链接框中。例如：
<pre style="width:auto; overflow:scroll">
<pre style="width:auto; overflow:scroll">
   |link box=This documentation is automatically generated by [[Template:Country showdata]]
   |link box=本文档由 [[Template:Country showdata]] 自动生成
</pre>
</pre>


===Automatic functions===
===自动功能===
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 [create] links.
如果文档页面不存在，[create] 链接会包含一个 [[mw:Manual:Creating pages with preloaded text|preload]] 页面，以便单击它将使用基本文档页面格式预先填写编辑表单。预加载文本也用于 /sandbox 和 /testcases [create] 链接。


When this template is on a /sandbox subpage it automatically adds the {{tl|Template sandbox notice}}.
当此模板位于 /sandbox 子页面时，它会自动添加 {{tl|Template sandbox notice}}。


===Subject namespaces vs. talk namespaces===
===Subject 命名空间与 Talk 命名空间===
Terminology: ''Subject namespaces'' are the opposite of ''talk namespaces''. For instance "Template:" is the subject space of "Template talk:".
术语：“Subject 名称空间”与“Talk 名称空间”相反。例如“Template:”是“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:
此模板通常放置在 Subject 名称空间中，位于 {{tag|noinclude|o}} 标记内。但在某些情况下，此模板需要出现在讨论页上：


* 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.
* 在 Mediawiki 命名空间中，因为 {{tag|noinclude|o}} 通常在系统消息中不起作用，并且出于性能原因需要保持 Mediawiki 命名空间的清洁。


When placed on talk pages, this template usually is placed near the top of the page and without {{tag|noinclude}} tags.
当放置在讨论页面上时，此模板通常放置在页面顶部附近并且没有 {{tag|noinclude}} 标签。


The /doc, /sandbox and /testcases pages should normally be in the subject namespace, except in the namespaces that do not have the MediaWiki [[meta:Help: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.
/doc、/sandbox 和 /testcases 页面通常应位于主题命名空间中，但未启用 MediaWiki [[meta:Help:Link#Subpage features|子页面功能]]的命名空间除外：Main、File、Mediawiki和类别。 （但目前我们只显示来自 User、User talk、Template 和 Template talk 命名空间的 /sandbox 和 /testcases 链接。）还有一大堆其他技术原因，为什么 /doc 页面必须存储在讨论页面下（但只有那些）命名空间。


This template automatically points its [create] links for the /doc, /sandbox and /testcases to the right namespace.
该模板自动将其 /doc、/sandbox 和 /testcases 的 [create] 链接指向正确的命名空间。


===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:Quote}}, the template will behave exactly as if it were on the page [[Template:Quote]], including showing the documentation from [[Template:Quote/doc]], linking to [[Template:Quote/sandbox]], etc. This parameter is useful for testing.
您可以使用 {{para|page}} 参数模拟给定页面的输出。例如，如果您使用代码 {{para|page|Template:Quote}}，模板的行为将与页面 [[Template:Quote]] 完全相同，包括显示来自 [[Template:Quote/doc]] 的文档，链接到 [[Template:Quote/sandbox]] 等。此参数对测试很有用。


===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.
该模板调用 {{tl|documentation/start box2}} 和 {{tl|documentation/end box2}} 依次调用 {{tl|documentation/start box}} 和 {{tl|documentation/end box}}。 /start 框（和 /end 框）包含大部分代码，而此模板和 /start box2（和 /end box2）进行参数预处理。


The preload page for the /doc [create] link is [[Template:Documentation/preload]]. The preload pages for the /sandbox and /testcases [create] links are [[Template:Documentation/preload-sandbox]] and [[Template:Documentation/preload-testcases]]. The preload page for the /sandbox [mirror] link is [[Template:Documentation/mirror]].
/doc [create] 链接的预加载页面是 [[Template:Documentation/preload]]。 /sandbox 和 /testcases [create] 链接的预加载页面是 [[Template:Documentation/preload-sandbox]] 和 [[Template:Documentation/preload-testcases]]。 /sandbox [mirror] 链接的预加载页面是 [[Template:Documentation/mirror]]。


====Full syntax====
====完整语法====
<pre>
<pre>
{{Documentation}}
{{Documentation:zh-cn}}


{{Documentation
{{Documentation
Line 138: Line 139:
}}
}}


{{Documentation
{{Documentation:zh-cn
| [path to documentation page]
| [path to documentation page]
| heading-style =  
| heading-style =  
Line 146: Line 147:
</pre>
</pre>


===See also===
===另请参阅===
* {{tl|Documentation subpage}}, a notice placed at the top of a /doc subpage explaining its role and including a link to the page it documents.
* {{tl|Documentation subpage:zh-cn}}，放置在 /doc 子页面顶部的通知，解释其角色并包括指向它记录的页面的链接。


<includeonly>{{When pagename is |/sandbox= |/testcases= |other=
<includeonly>{{When pagename is |/sandbox= |/testcases= |other=
<!---- Categories below this line, please ---->
<!---- 请在此行以下的类别写入 ---->
[[Category:Template documentation| ]]
[[Category:Template documentation| ]]
[[Category:Template namespace templates]]
[[Category:Template namespace templates]]
}}</includeonly>
}}</includeonly>

Revision as of 10:49, 14 January 2022

本模板由大康翻译。本模板的功能文本翻译于2021年9月19日 (日) 14:03‎（中国标准时间），描述文本翻译于2022年1月15日。部分内容由机器翻译。

不要混淆Template:Documentation subpage。

Template:Documentation subpage:zh-cn

这个模板是从维基百科移植过来的一个模板，并且修改过。它最初位于 Template:Documentation:zh-cn/doc。此模板的原始作者显示在模板的编辑历史页面。
该模板的文档也移植自 Wikipedia，最初来自 Template:Documentation:zh-cn/doc/doc。文档的原始作者显示在文档的编辑历史页面。
Wikipedia 的文本可在 Creative Commons Attribution-ShareAlike 3.0 Unported License 下获得。


这是几乎每个模板页面上使用的 {{Documentation}} 模板，以包含该模板的文档说明和信息。

该模板显示一个灰色的文档框，就像您现在看到的那样，并自动从 /doc 子页面加载内容。如果有指示，它还可以从其他地方加载内容。

此模板用于记录模板和嵌入到其他页面的其他页面。它可以在模板命名空间和大多数其他命名空间中使用。

使用此模板可以在必要时保护模板，同时允许任何人编辑文档和类别。

用法

通常这个模板在没有任何参数的情况下使用，放置在模板或页面的底部，在一个 <noinclude>...</noinclude> 容器中： 

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn}}
<!-- 将类别添加到 /doc 子页面，不在此处 -->
</noinclude>

然后此模板会自动从使用它的模板的 /doc 子页面加载内容。

此模板还可以从任何其他页面加载内容。像这样： 

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn |Template:(其他页面名称)/doc}}
</noinclude>

请注意，当从本地 /doc 页面以外的页面加载文档时，处理类别变得很棘手。

内容也可以直接作为文本提供。像这样： 

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn
 | content =
(一些文本)
}}</noinclude>

使用 |content= 参数时，文档框通常不会在右上角显示 [edit] [purge] 链接。请注意，如果 /doc 页面存在，指向它的链接仍会显示在 doc 框下方的链接框中。

参数 |1= 和 |content= 参数也可以组合，如下所示： 

<!--模板代码的最后一行--><noinclude>
{{Documentation:zh-cn |1=Template:Any page/doc
| content =
{{Template:(任一页面)/doc |parameters}}
}}</noinclude>

然后作为参数 1 提供的页面名称用于 [edit] [purge] 链接和文档框下方链接框中的 /doc 链接。但是 content 参数用于文档框中显示的内容。上述代码表示内容被嵌入为Template:Tnull。在这个例子中，一个参数也被提供给正在加载的 /doc 页面。

小技巧

要自动插入 noinclude 标记、模板调用和指导性注释，请使用以下代替代码：

{{subst:doc-code}}

最佳做法

代码应该添加在模板代码的底部，<noinclude> 之前没有空格（这会导致使用模板的页面上有额外的空间）。

适用于模板本身的类别应添加到 /doc 子页面底部的 <includeonly>...</includeonly> 标签内。

如果文档页面包含 <includeonly> 或 <noinclude> 标记作为可见文档文本的一部分，请将“<”替换为“ <" 或使用 Template:tag。

标题

在模板命名空间中，此模板显示以下标题：

Curly brackets white.png 模板文档

在大多数其他名称空间中，例如“Wikipedia:”，它显示以下标题：

文档

但是当在文件（图像）页面上时，它会显示这个标题：

摘要

heading 参数可用于将标题设置为其他内容。像这样：

{{Documentation:zh-cn |heading=信息框文档}}

如果 heading 参数为空但已定义，则不显示标题并且不显示 [edit] [purge] 链接。像这样：

{{Documentation:zh-cn |heading=}}

heading-style 参数可以提供可选的 CSS 值。不带引号 " " 但带有结尾分号 ;。例如：

heading-style=font-size:150%;color:red;

链接框

大文档框下方是一个小链接框，显示有关文档的一些元数据。链接框根据提供给该模板的参数以及在哪个名称空间中使用它来显示不同的内容。在某些情况下，链接框根本不显示。

要隐藏链接框，请添加参数

|link box=off.

您还可以通过设置 |link box= 参数将自定义文本插入到链接框中。例如： 

  |link box=本文档由 [[Template:Country showdata]] 自动生成

自动功能

如果文档页面不存在，[create] 链接会包含一个 preload 页面，以便单击它将使用基本文档页面格式预先填写编辑表单。预加载文本也用于 /sandbox 和 /testcases [create] 链接。

当此模板位于 /sandbox 子页面时，它会自动添加 {{Template sandbox notice}}。

Subject 命名空间与 Talk 命名空间

术语：“Subject 名称空间”与“Talk 名称空间”相反。例如“Template:”是“Template talk:”的主题空间。

此模板通常放置在 Subject 名称空间中，位于 <noinclude> 标记内。但在某些情况下，此模板需要出现在讨论页上：

  • 在 Mediawiki 命名空间中，因为 <noinclude> 通常在系统消息中不起作用，并且出于性能原因需要保持 Mediawiki 命名空间的清洁。

当放置在讨论页面上时，此模板通常放置在页面顶部附近并且没有 <noinclude>...</noinclude> 标签。

/doc、/sandbox 和 /testcases 页面通常应位于主题命名空间中，但未启用 MediaWiki 子页面功能的命名空间除外：Main、File、Mediawiki和类别。 （但目前我们只显示来自 User、User talk、Template 和 Template talk 命名空间的 /sandbox 和 /testcases 链接。）还有一大堆其他技术原因，为什么 /doc 页面必须存储在讨论页面下（但只有那些）命名空间。

该模板自动将其 /doc、/sandbox 和 /testcases 的 [create] 链接指向正确的命名空间。

测试

您可以使用 |page= 参数模拟给定页面的输出。例如，如果您使用代码 |page=Template:Quote，模板的行为将与页面 Template:Quote 完全相同，包括显示来自 Template:Quote/doc 的文档，链接到 Template:Quote/sandbox 等。此参数对测试很有用。

技术细节

该模板调用 {{documentation/start box2}} 和 {{documentation/end box2}} 依次调用 {{documentation/start box}} 和 {{documentation/end box}}。 /start 框（和 /end 框）包含大部分代码，而此模板和 /start box2（和 /end box2）进行参数预处理。

/doc [create] 链接的预加载页面是 Template:Documentation/preload。 /sandbox 和 /testcases [create] 链接的预加载页面是 Template:Documentation/preload-sandbox 和 Template:Documentation/preload-testcases。 /sandbox [mirror] 链接的预加载页面是 Template:Documentation/mirror。

完整语法

{{Documentation:zh-cn}}

{{Documentation
 | content =
}}

{{Documentation:zh-cn
| [path to documentation page]
| heading-style = 
| heading = 
| link box = 
}}

另请参阅

  • {{Documentation subpage:zh-cn}}，放置在 /doc 子页面顶部的通知，解释其角色并包括指向它记录的页面的链接。


Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Template:Documentation:zh-cn/doc&oldid=251695"