Templat:Pendokumenan/doc

Ini merupakan templat {{Pendokumenan}} yang digunakan pada hampir setiap laman templat untuk mengandungi arahan dan maklumat yang didokumenkan bagi templat tersebut.

Untuk arahan terperinci bagaimana dan bila menggunakan templat ini, sila lihat Wikipedia:Pendokumenan templat.

Templat ini memaparkan kotak pendokumenan hijau seperti yang anda lihat sekarang dan secara automatik memuat kandungan dari sublaman /doc. Ianya boleh juga memuat kandungan dari tempat lain jika diarahkan sedemikian.

Templat ini bertujuan untuk mendokumenkan templat dan laman lain yang ditransklusikan kepada laman lain. Ia boleh digunakan dalam ruang nama templat dan kebanyakan ruang nama yang lain.

Penggunakan templat ini membolehkan templat untuk dilindungi di mana diperlukan, sementara membolehkan sesiapa sahaja untuk menyunting pendokumenan dan kategori.

Penggunaan

Biasanya templat ini digunakan tanpa sebarang parameter, diletakkan pada bahagian bawah templat atau laman yang didokumenkan, dalam bekas <noinclude>...</noinclude>:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan}}
<!-- Tambah kategori ke sublaman /doc dan interwiki di Wikidata, bukan di sini! -->
</noinclude>

Kemudiannya templat ini secara automatik memuat kandungan daripada sublaman /doc templat yang ianya digunakan.

Templat ini boleh juga memuat kandungan dari laman lain. Seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan |Templat:Laman lain/doc}}
</noinclude>

Ambil perhatian bahawa apabila memuat pendokumenan dari laman selain dari laman /doc tempat ianya menjadi sulit untuk mengendalikan kategori.

Kandungan boleh juga disuap secara langsung sebagai teks. Seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan
 | content =
(sebarang pendokumenan)
}}</noinclude>

Apabila parameter |content= digunakan, kotak doc biasanya tidak menunjukkan pautan [sunting] [singkir] di sudut atas kanan. Ambil perhatian bahawa jika laman /doc wujud, pautan kepadanya masih ditunjukkan dalam kotak pautan di bawah kotak doc.

Parameter |1= dan |content= boleh juga digabungkan, seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan |1=Templat:Sebarang laman/doc
| content =
{{Template:Sebarang laman/doc |parameter}}
}}</noinclude>

Kemudiannya namalaman yang disuapkan sebagai parameter 1 digunakan untuk pautan [sunting] [singkir] dan untuk pautan /doc dalam kotak pauan di bawah kotak doc. Tetapi parameter content digunakan untuk kandungan yang ditunjukkan dalam kotak doc. Kod di atas bermaksud kandungan ditransklusikan sebagai {{Templat:Sebarang laman/doc|parameter}}. Dalam contoh ini parameter juga disuapkan ke laman /doc yang sedang dimuatkan.

Jalan pintas

Taip {{subst:doc-code}} untuk memasukkan secara automatik tag, panggilan templat dan komen pembimbing.

Amalan terbaik

Kod hendaklah ditambah pada bahagian atas kod templat, dengan tiada jarak sebelum <noinclude> (yang mana menyebabkan jarak tambahan pada laman di mana templat

Ini merupakan templat {{Pendokumenan}} yang digunakan pada hampir setiap laman templat untuk mengandungi arahan dan maklumat yang didokumenkan bagi templat tersebut.

Untuk arahan terperinci bagaimana dan bila menggunakan templat ini, sila lihat Wikipedia:Pendokumenan templat.

Templat ini memaparkan kotak pendokumenan hijau seperti yang anda lihat sekarang dan secara automatik memuat kandungan dari sublaman /doc. Ianya boleh juga memuat kandungan dari tempat lain jika diarahkan sedemikian.

Templat ini bertujuan untuk mendokumenkan templat dan laman lain yang ditransklusikan kepada laman lain. Ia boleh digunakan dalam ruang nama templat dan kebanyakan ruang nama yang lain.

Penggunakan templat ini membolehkan templat untuk dilindungi di mana diperlukan, sementara membolehkan sesiapa sahaja untuk menyunting pendokumenan dan kategori.

Penggunaan

Biasanya templat ini digunakan tanpa sebarang parameter, diletakkan pada bahagian bawah templat atau laman yang didokumenkan, dalam bekas <noinclude>...</noinclude>:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan}}
<!-- Tambah kategori ke sublaman /doc dan interwiki di Wikidata, bukan di sini! -->
</noinclude>

Kemudiannya templat ini secara automatik memuat kandungan daripada sublaman /doc templat yang ianya digunakan.

Templat ini boleh juga memuat kandungan dari laman lain. Seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan |Templat:Laman lain/doc}}
</noinclude>

Ambil perhatian bahawa apabila memuat pendokumenan dari laman selain dari laman /doc tempat ianya menjadi sulit untuk mengendalikan kategori.

Kandungan boleh juga disuap secara langsung sebagai teks. Seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan
 | content =
(sebarang pendokumenan)
}}</noinclude>

Apabila parameter |content= digunakan, kotak doc biasanya tidak menunjukkan pautan [sunting] [singkir] di sudut atas kanan. Ambil perhatian bahawa jika laman /doc wujud, pautan kepadanya masih ditunjukkan dalam kotak pautan di bawah kotak doc.

Parameter |1= dan |content= boleh juga digabungkan, seperti ini:

<!--Baris akhir kod templat anda--><noinclude>
{{Pendokumenan |1=Templat:Sebarang laman/doc
| content =
{{Template:Sebarang laman/doc |parameter}}
}}</noinclude>

Kemudiannya namalaman yang disuapkan sebagai parameter 1 digunakan untuk pautan [sunting] [singkir] dan untuk pautan /doc dalam kotak pauan di bawah kotak doc. Tetapi parameter content digunakan untuk kandungan yang ditunjukkan dalam kotak doc. Kod di atas bermaksud kandungan ditransklusikan sebagai {{Templat:Sebarang laman/doc|parameter}}. Dalam contoh ini parameter juga disuapkan ke laman /doc yang sedang dimuatkan.

Jalan pintas

Taip {{subst:doc-code}} untuk memasukkan secara automatik tag, panggilan templat dan komen pembimbing.

Amalan terbaik

Kod hendaklah ditambah pada bahagian atas kod templat, dengan tiada jarak sebelum <noinclude> (yang mana menyebabkan jarak tambahan pada laman di mana templat digunakan).

Kategori yang berkaitan dengan templat itu sendiri hendaklah ditambah ke bahagian bawah sublaman /doc, dalam tag <includeonly>...</includeonly>. Pautan interwiki yang berkaitan dengan templat hendaklah disenaraikan di Wikidata (selanjutnya di wp:Wikidata). Untuk kes yang lebih rumit, lihat Wikipedia:Pendokumenan templat#Kategori dan pautan interwiki.

Jika laman pendokumenan mengandungi tag <includeonly> atau <noinclude> sebagai sebahagian dari teks pendokumenan yang boleh dilihat, gantikan "<" dengan "<".

Pengepala

Apabila dalam ruang nama Templat, templatdigunakan).

Kategori yang berkaitan dengan templat itu sendiri hendaklah ditambah ke bahagian bawah sublaman /doc, dalam tag <includeonly>...</includeonly>. Pautan interwiki yang berkaitan dengan templat hendaklah disenaraikan di Wikidata (selanjutnya di wp:Wikidata). Untuk kes yang lebih rumit, lihat Wikipedia:Pendokumenan templat#Kategori dan pautan interwiki.

Jika laman pendokumenan mengandungi tag <includeonly> atau <noinclude> sebagai sebahagian dari teks pendokumenan yang boleh dilihat, gantikan "<" dengan "<".

Pengepala

Apabila dalam ruang nama Templat, templat ini menunjukkan pengepala ini:

Pendokumenan templat

Dalam kebanyakan ruang nama yang lain, seperti "Wikipedia:", ia menunjukkan pengepala ini:

Pendokumenan

Tetapi apabila dalam laman Fail (imej) ia menunjukkan pengepala ini:

Ringkasan

Parameter heading boleh digunakan untuk menetapkan pengepala kepada sesuatu yang lain. Seperti ini:

{{Pendokumenan |heading=Pendokumenan kotakinfo}}

Jika parameter heading kosong tetapi ditakrifkan, tiada pengepala ditunjukkan dan tiada pautan [sunting] [singkir[ ditunjukkan. Seperti ini:

{{Pendokumenan |heading=}}

Parameter heading-style boleh disuapkan nilai CSS pilihan. Tanpa tanda petikan " " tetapi dengan titik koma penamat ;. Seperti contoh:

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

Kotak pautan

Di bawah kotak doc besar ialah kotak pautan kecil yang menunjukkan beberapa metadata tentang pendokumenan. Kotak pautan tersebut menunjukkan perkara yang berbeza bergantung kepada parameter apa yang disuapkan ke templat ini, dan dalam ruang nama mana ianya digunakan. Dalam beberapa kes kotak pautan tidak ditunjukkan sama sekali.

Untuk menyembunyikan kotak pautan, tambah parameter

|link box=off.

Anda boleh juga menambah teks tersuai ke dalam kotak pautan, dengan menetapkan parameter |link box=. Seperti contoh:

  |link box=Pendokumenan ini dijana secara automatik oleh [[Templat:Datatunjuk negara]]

Fungsi automatik

Sekiranya laman pendokumenan tidak wujud, pautan [cipta] memasukkan laman pramuat supaya mengkliknya akan pra-isi borang sunting dengan format laman pendokumenan asas. Teks pramuat juga digunakan untuk pautan [cipta] /kotakpasir dan /kes ujian.

Apabila templat ini ialah pada laman templat dilindungi ianya sekarang menambah {{dp-templat}}, yang menunjukkan mangga kelabu atau merah pada sudut atas kanan. Jadinya tidak perlu menambah secara manual {{dp-templat}} untuk templat yang menggunakan {{Pendokumenan}}.

Apabila templat ini ialah pada sublaman /kotakpasir ianya menambah secara automatik {tl|Notis kotakpasir templat}}.

Ruang nama subjek lwn ruang nama perbincangan

Istilah: Ruang nama subjek adalah berlawan dengan ruang nama perbincangan. Contoh "Templat:" ialah ruang subjek untuk "Perbincangan templat:".

Templat ini biasanya diletakkan dalam ruang nama subjek, dalam tag <noinclude>. Tetapi dalam beberapa kes templat ini perlu ada pada laman perbincangan:

• Dalam ruang nama Mediawiki, memandangkan <noinclude> selalunya tidak berfungsi dalam pesanan sistem, dan memandangkan ruang nama Mediawiki perlu sentiasa bersih atas sebab prestasi.

Apabila diletakkan pada laman perbincangan, templat ini biasanya diletakkan hampir kepada bahagian atas laman dan tanpa tag <noinclude>...</noinclude>.

Laman-laman /doc, /kotakpasir dan /kes ujian hendaklah biasanya dalam ruang nama subjek, kecuali dalam ruang nama yang tidak mempunyai ciri sublaman MediaWiki didayakan: Utama, Fail, Mediawiki dan Kategori. (Tetapi buat masa ini kami hanya menunjukkan pautan-pautan /doc dan /kes ujian daripada ruang nama Pengguna, Perbincangan pengguna, Templat dan Perbincangan templat.) Terdapat juga sebab-sebab teknikal yang lain kenapa laman /doc mesti disimpan di bawah laman perbincangan untuk ruang nama berkenaan (tetapi hanya yang berkenaan).

Templat ini menunjukkan secara automatik pautan [cipta] sendiri untuk /doc, /kotakpasir dan /kes ujian ke ruang nama yang betul.

Pengujian

Anda boleh mensimulasikan output untuk laman yang diberikan dengan menggunakan parameter |page=. Seperti contoh, jika anda menggunakan kod |page=Templat:Suntingan dilindungi, templat akan berkelakuan sama seperti seolah-olah ianya berada pada laman Templat:Suntingan dilindungi, termasuk menunjukkan borang pendokumenan Templat:Suntingan dilindungi/doc, dipautkan ke Templat:Suntingan dilindungi/kotakpasir, dll. Parameter ini berguna untuk menguji dan digunakan secara meluas pada laman kes ujian module.

Butiran teknikal

Laman pramuat untuk pautan [cipta] /doc ialah Templat:Pendokumenan/pramuat. Laman-laman pramuat untuk pautan-pautan [cipta] /kotakpasir dan /kes ujian adalah Templat:Pendokumenan/pramuat kotak pasir dan Templat:Pendokumenan/pramuat kes-kes ujian.

Untuk butiran lanjut, lihat laman perbincangan.

Sintaks penuh

{{Pendokumenan}}

{{Pendokumenan
 | content =
}}

{{Pendokumenan
| [laluan ke laman pendokumenan]
| heading-style = 
| heading = 
| link box = 
}}

Lihat juga

• {{Sublaman pendokumenan}}, notis yang diletakkan pada bahagian atas sublaman /doc yang menerangkan peranannya dan termasuk pautan ke lamanyang ia dokumenkan.
• Wikipedia:Pendokumenan templat ialah panduan bagaimana-untuk bagi pendokumenan templat.