Help:模板文档

本页使用了标题或全文手工转换,现处于不转换模式
帮助页面

模板文档页模式是一种机制,用来将模板帮助文档从模板源代码中安全地分离成为帮助文档页面。这能够使得模板本身处于完全保护状态下,而说明部分保持未保护状态,让每个人仍然可以编辑模板帮助文档。

能够解决什么问题?

求闻编者经常喜欢在模板页面里加上使用说明(例如:template:cite news)。这些叙述文字可以用包含在维基源代码<noinclude>...</noinclude>的方式写在模板里。然而,这种作法会有一些缺点:

  • 在 <noinclude>...</noinclude> 中的文字会被加算到“展开前的大小 pre-expand include size”,其大小有上限(参见模板限制)。
  • 有一些模板,因为被大量的页面所引用而受到完全的保护。这时候编辑说明内容变得极为不方便,非管理员必须提出修改的要求,而管理员得去代为修改。
  • 一个页面的“预先包含 pre-included”和“展开后 post-expanded”的大小设有上限。更糟的情况是,模板里包含了另一个模板,其“预先展开 pre-expanded”大小因此倍增而发生冲突。(参见模板限制)。

总括来说,有个双重办法可以将解说和使用方法置于一个“解说模板”,以取代<noinclude>...</noinclude>区块所围住的工具模板(若妥善运用的话,可以涵盖数个相关的工具型模板),这个方法同时具有两个明显的附加效果:

  1. 当广受利用的模板更新时,能将服务器重新读取的资料量降到最小。
  2. 受保护的稳定模板,可以增添解说、分类等内容,而不用干扰到主要用途。

使用方法

假设有一个模板Template:X ,在Template:X的模板源代码底下加入以下的标示:

[--模板的最后一行文字--]<noinclude>
{{Documentation}}
</noinclude>

保存后,单击模板文档中的“创建”按钮,即可以对 Template:X/doc 进行编辑模板说明。如果该文档模板没有建立,以下的源代码会自动产生:(参见Template:Documentation/preload

{{NoteTA
|G1 = MediaWiki
}}
{{Documentation subpage}}
<!-- 在本行下编辑模板说明 -->
== 概要 ==

== 参数及使用方法 ==

== 范例 ==

== 注意事项 ==

== 重定向 ==

== 模板编辑说明 ==

== 参见 ==

<includeonly>{{Sandbox other||
<!-- 本行下加入模板的分类 -->

}}</includeonly>

在上方指示的註釋行下分別填寫模板說明和分類。

注意

請確保<noinclude>的開頭,接在模板原始碼或文字的最後一列後方,不要新起一列。否則,一個多餘的新列會被插入到包含 X 模板的頁面中,往往該頁面不需要這個新列。
此外,子頁面的標題請必定要使用"/doc"的型式。
'X/doc'文件頁面的分類應該只有Category:模板說明文件,請調整原始碼讓屬於模板的分類只存在於模板主頁面。
你可以將 /doc 子頁面的討論頁重定向到模板本身的討論頁,那麼最後所有有關模板及其文件頁的討論就會在同一討論頁上,舉個例,將 Template talk:X/doc 重定向到 Template talk:X。

現在這個模板可以被完全保護了。因為它的'X/doc'文件頁面並沒有被保護,所以任何人可以編輯該文件頁面。然而,注意連鎖保護模板會使得文件頁面也被保護。

分类链接

  • 要将模板本身置于一个分类中,请在 doc 子页面上的 <includeonly>...</includeonly> 段落中添加代码 [[Category:分类名]]
  • 要将 doc 子页面置于一个分类中,请在 doc 子页面上的 <noinclude>...</noinclude> 段落中添加代码 [[Category:分类名]]
  • 要让该模板将条目置于一个分类中(当该条目使用该模板时),请在模板页上的 <includeonly>...</includeonly> 段落中添加代码 [[Category:分类名]]

優點

  • 編輯的 X/doc 頁面只會傳遞展示到該模板頁面上,而不會被包含在 X 模板裡。引用 X 模板的頁面不需要仰賴文件頁面,所以不會為了重度使用模板而擴大工作請求(参见mw:Help:Job queue)。
  • 文件的編輯不會對模板本身和引用的頁面造成任何危害。對於文件頁面的破壞,不會擴及到引用 X 模板的頁面上。
  • 即使模板受到完全保護,每個人仍然能夠編輯模板說明文件。分類可以簡單地增加在 X/doc 子頁面。

參見