维基百科:模板文档

(重定向自Wikipedia: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,我們仍然可以擁有解說蛋糕並且更快速地享用它!

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

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

使用方法

假設有一個模板 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]

範例

參見