维基百科:模板文档

本页為操作指南，用於介紹中文维基百科社群的一些实现和操作方式。
本文只是論述，不屬於方針或指引。如果本指南與方針或指引起衝突或不一致，請以方針或指引的條文為準。

WP:DOC

模板文件是一種機制，用來將模板說明文件從模板原始碼中安全地分離成為說明文件頁面。這能夠使得模板本身處於完全保護狀態下，而說明部分保持未保護狀態，讓每個人仍然可以編輯模板說明文件。

能夠解決什麼問題？

維基人經常喜歡在模板頁面裡加上使用說明（例如：template:cite news）。這些敘述文字可以用包含在維基原始碼<noinclude>...</noinclude>的方式寫在模板裡。然而，這種作法會有一些缺點：

在 <noinclude>...</noinclude> 中的文字在被其他页面嵌入前显示會被加算到「展開前的大小 pre-expand include size」，其大小有上限（參見Wikipedia:模板限制）。
有一些模板，因為被大量的頁面所引用而受到完全的保護。這時候編輯說明內容變得極為不方便，非管理員必須提出修改的要求，而管理員得去代為修改。
一個頁面的「預先包含 pre-included」和「展開後 post-expanded」的大小設有上限。更糟的情況是，模板裡包含了另一個模板，其「預先展開 pre-expanded」大小因此倍增而發生衝突。（參見Wikipedia:模板限制）。
如果在编辑模板时，要使用维基百科的“查找和替换”批量替换模板内容的话，可能会使说明内容也受到波及。

本說明頁面進一步闡釋對策和技巧，用以滿足需要更新瀏覽器暫存記憶的人（or most commonly, learn from the first exposure! 解說文件是必須的，特別是為了停留在陡峭的維基學習曲線上的新加入編輯者。），以及增進效益使建構頁面變得更快、與擺脫伺服器處理（更新）時的讀取。（我們都希望頁面能夠更快地被載入！）

總括來說，有個雙重辦法可以將解說和使用方法置於一個「解說模板」，以取代<noinclude>...</noinclude>區塊所圍住的工具模板（若妥善運用的話，可以涵蓋數個相關的工具型模板），so easy on the processor and, thus，我們仍然可以擁有解說蛋糕並且更快速地享用它！

這個方法同時具有兩個明顯的附加效果：

當廣受利用的模板更新時，能將伺服器重新讀取的資料量降到最小。
受保護的穩定模板，可以增添解說、分類等內容，而不用干擾到主要用途。

使用方法

假設有一個模板 Template:X ，在 template X 的模板原始碼底下加入以下的標示：

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

<!-- 請將模板的分類放在 /doc 子頁面 -->

</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 模板的頁面不需要仰賴文件頁面，所以不會為了重度使用模板而擴大工作請求（m:Help:job queue）。
文件的編輯不會對模板本身和引用的頁面造成任何危害。對於文件頁面的破壞，不會擴及到引用 X 模板的頁面上。
即使模板受到完全保護，每個人仍然能夠編輯模板說明文件。分類可以簡單地增加在 X/doc 子頁面。

註釋

蒂姆·斯塔林（Tim Starling）寫到：「若解說文件過大或是更新頻繁，我建議你將它移動到子頁面。如此一來你可以將它引用到 <noinclude> 區段和討論頁之中。」 [1]

範例

{{Tnavbar}}（被保護），{{Tnavbar/doc}}（未保護）