Wikipedia:Sjabloondokumentasie

Sjablone is 'n kragtige kenmerk van MediaWiki, maar dit kan verwarrend wees vir nuwe bydraers en selfs gesoute bydraers kan dit moeilik vind om die meer ingewikkelde sjablone te verstaan. Dit moet dus van dokumentasie vergesel word om die sjabloon se bruikbaarheid te verbeter.

Sjabloondokumentasie moet verduidelik wat die sjabloon doen en hoe om dit te gebruik. Dit moet eenvoudig genoeg wees sodat 'n bydraer wat nie in diepte kennis van die binnewerkings van sjabloonsintaks het nie – wat heelwat ervare bydraers insluit wie se fokus elders lê – dit na behore kan gebruik. Dit is veral die geval met sjablone wat algemeen gebruik word.

Wat om in te sluit

Sjabloondokumentasie behoort die volgende in te sluit:

• Die basiese doel van die sjabloon: wat dit doen en indien dit nie onmiddellik duidelik is nie, hoekom dit gedoen moet word. Indien daar ander sjablone bestaan met soortgelyke name of doeleindes, sal dit 'n goeie idee wees om hulle te lys en sodoende die kans te verminder dat die verkeerde sjabloon gebruik word. Sluit belangrike beperkings in, soos die gebrek aan Navigasiekas-sigbaarheid op die Mobiele webwerf, as 'n sjabloon slegs gebruik moet word vir sekere lande of in sekere tye, of ander dinge wat bydraers kennis van moet neem alvorens hulle besluit om die sjabloon te gebruik.
• Die sjabloon se parameters: of hulle genommer is, name het of opsioneel is, en indien wel, wat die verstekwaardes is en watter uitwerking dit het. Indien 'n parameter slegs 'n beperkte stel waardes aanvaar of op enige manier beperk is, byvoorbeeld, indien dit net "ja", "nee", of 'n getal aanvaar, moet dit duidelik genoem word.
• Voorbeelde vir gebruik: spesifiseer die presiese wikitext wat gebruik behoort te word asook die resultate wat dit sal lewer. Die wikitext kan omsluit wees in <code>...</code>-merkers om dit duideliker te maak en makliker om te kopieer. Indien die sjabloon byvoorbeeld op verskillende maniere gebruik kan word, met of sonder opsionele parameters, verskaf 'n reeks voorbeelde. 'n Goeie metode hiervoor is om die sjabloon self 'n paar keer in die dokumentasie te gebruik (transklusie), met verskillende parameters in elke geval. Lys dan ook die parameters in elke geval. Met Sjabloon:Xpd kan dit gedoen word sonder om die sjabloon twee keer in die wikitext te plaas.
• Sjabloondata: Sien Wikipedia:TemplateData/Handleiding.
• Verwante sjablone: indien die sjabloon een van 'n reeks sjablone is, sluit skakels tot die reeks in – verseker ook dat elke sjabloon in die reeks skakels van mekaar insluit om navigasie te vergemaklik. ('n Aparte navigasiesjabloon kan handig te pas kom in so 'n geval, sien: Sjabloon:Beskermingsjablone).
• Kategorieë waar van toepassing (InterWikimedia-skakels moet gelys word by Wikidata – meer inligting verkrygbaar by Wikipedia:Wikidata). Soos met die dokumentasie, moet kategorieë gelys word binne <noinclude>...</noinclude>-merkers in 'n sjabloon, of binne <includeonly>...</includeonly>-merkers in 'n dokumentasieblad. Verskeie sjabloonkategorieë is beskikbaar, sien: Kategorie:Sjablone om deur hulle te snuffel.

Die Engelse Wikipedia is 'n bron van sjablone vir honderde ander Wikipedia's en susterprojekte. Baie maal is sjablone ten volle selfstandig, so die proses is eenvoudig: die inhoud word net so oor gekopieer na die nuwe sjabloonblad op die ander wiki, en alles werk. By meer komplekse sjablone kan die sjabloon egter moontlik 'n module inroep, ander sjablone intrek (transklusie), slegs werk indien gepaar is met 'n aparte sjabloon of spesifieke CSS- of Javascript-kode benodig om te werk. In sulke gevalle is dit nuttig om 'n kort lys van sjablone of kode, wat deur die spesifieke sjabloon benodig word, aan die einde van die dokumentasie in te sluit.

Waar om dit te plaas

Sjabloondokumentasie word meermale in 'n subblad van die sjabloon self geplaas, wat dan ingetrek word aan die einde van die sjabloonblad. Dit skei die gewoonlik komplekse sjabloonkode van die dokumentasie en maak die dokumentasie sodoende makliker om te redigeer. Dit laat ook die sjablone toe om waar nodig beskerm te word, terwyl enige een die dokumentasie kan redigeer. Die metode word soms na verwys as die "sjabloon-doc-bladpatroon".

Enige soort dokumentasie op 'n sjabloonblad (insluitend Sjabloondata) moet altyd omsluit word deur <noinclude>...</noinclude>-merkers, sodat dit nie vertoon word as die sjabloon op 'n ander bladsy gebruik word nie. Teks op die sjabloonblad dra ook by tot die hoeveelheid teks wat verwerk moet word as die sjabloon vertoon word, en vir beter werkverrigting ingeperk behoort te word. Deur die dokumentasie op 'n subblad te plaas word die probleem vermy (MediaWiki-ontwikkelaars beveel dit juis vir die rede aan).

Hoe om 'n dokumentasiesubblad te skep

Sjabloondokumentasiesubblaaie behoort, vir konsekwentheid, genoem en geformateer te word deur die volgende algemene patroon te gebruik.

Veronderstel jou sjabloon word Sjabloon:X genoem. Skep 'n subblad met die naam Sjabloon:X/doc. Sien die besonderhede by {{Dokumentasie subblad}} of begin 'n nuwe bladsy deur die volgende standaard wikitext te kopieer en plak:

{{Dokumentasie subblad}}
<!-- Plaas asseblief kategorieë, waar aangedui, aan die onderkant van hierdie blad en interwiki's by Wikidata (see [[Wikipedia:Wikidata]]) -->
Vervang: Wat is die doel van hierdie sjabloon/module? Waar kan dit gebruik word? Hoekom moet dit gebruik word?

== Parameters ==
Vervang: Verskaf 'n lys van die moontlike parameters met 'n verduideliking vir die gebruik daarvan Die onderstaande is slegs voorbeelde.
Lys van alle parameters:

<pre>
{{voorbeeld
| par1  = x / y / z
| par2 = niks / [[Beeld:enige beeld.svg|40px]]
| ...
}}
</pre>

'''par1'''
:Kies uit x, y of z.

'''par2'''
: Verskaf skakel na beeld of niks.


== Gebruik ==
Vervang: Verskaf goeie voorbeelde vir die gebruik van die sjabloon met al die moontlike gevalle. Onderstaande is slegs voorbeelde.

'''Eenvoudige voorbeeld'''
<pre>
{{Voorbeeld}}
</pre> lewer:

{{Voorbeeld}}
</br>
</br>
== Sjabloondata ==
Vervang: Maak 'n lys vir inligting wat in die visuele redigeerder moet verskyn.Let wel hierdie is vir gebruik in die Visuele redigeerder. Dit verskaf behoorlike benaming en beskrywings vir die gebruiker vir 'n sjabloon. Die onderstaande genereer tans nog in Engels.

<templatedata>
{
	"description": "Voorbeeldsjabloon wat 'n klein kassie skep wat noem dat dit 'n voorbeeld is.",
	"params": {}
}
</templatedata>

== Sien ook ==
Vervang: Lys ander sjablone en artikels wat verwant is aan hierdie sjabloon. Onderstaande is slegs voorbeelde.

{{sj|Voorbeeld}}, 'n Sjabloon wat dien as voorbeeld vir die skep van sjablone.


<include<includeonly></includeonly>only>{{Sandput ander||
<!-- Kategorieë onder hierdie reël asseblief; interwiki's by Wikidata -->
[[Kategorie:Sjablone]]
}}</include<includeonly></includeonly>only>

Die boonste reël sal 'n boodskap vertoon wat die huidige bladsy omskryf en 'n skakel na die sjabloonblad gee.

Plaas die dokumentasie na die boonste reël en kategorieë onder die gepaste kommentaarreël – los die kommentaar in plek sodat die uitleg behoue bly indien die bladsy in die toekoms geredigeer word. Verwante sjablone, beleidsblad, projekte en so meer kan gekoppel word deur 'n "Sien ook" afdeling in te sluit.

Stoor die subblad en keer terug na die sjabloon self, Sjabloon:X, in die voorbeeld. Redigeer die sjabloon en heg die volgende aan, aan die einde van die sjabloonkode:

[--laaste reël van jou sjabloonkode--]<noinclude>
{{Dokumentasie}}
<!--Plaas asseblief hierdie sjabloon se kategorieë by die /doc-subblad, nie hier nie!-->
</noinclude>

Dit sal {{dokumentasie}} aan die onderkant van die sjabloonblad oorbring.

Belangrik: Verseker dat die inleiding <noinclude> onmiddellik na die laaste karakter van die sjabloonkode of -teks begin en nie op 'n nuwe reël nie, ook nie met tussenkomende spasies nie. Anders sal ekstra spasie onder die sjabloon ingevoeg word met gebruik daarvan en dit is nie wenslik nie.

Indien die sjabloon reeds beskerm word, vra 'n administrateur om dit te doen of vra 'n redigering aan op die sjabloon se besprekingsblad. As dokumentasie en kategorieë reeds in 'n afdeling bestaan, omsluit in <noinclude>...</noinclude>-merkers, skuif hulle na die dokumentasiesubblad (waar hulle omsluit moet word in <includeonly>...</includeonly>-merkers), aangesien dit beter is om nie dokumentasie te verdeel tussen twee aparte bladsye nie.

Indien kode eers op die sjabloonblad geplaas word, kan voordeel getrek word uit die vooraflaai-kenmerk om 'n reeds gevulde doc-blad as raamwerk te kry; as die dokumentasie blad nog nie bestaan nie, kan geklik word op die skep-skakel wat die inhoud van Sjabloon:Dokumentasie/vooraflaai vooraf in die redigeringskas van die /doc-subblad sal laai.

Daar kan gekies word om die besprekingsblad van die /doc-subblad te herlei na die besprekingsblad van die sjabloon self. Daardeur sal alle besprekings rakende die sjabloon en sy dokumentasie op dieselfde besprekingsblad verskyn. Byvoorbeeld, herlei Sjabloonbespreking:X/doc na Sjabloonbespreking:X.

Blanko

Om 'n blanko sjabloon te genereer wat gekopieer kan word vanaf die dokumentasie en op 'n ander bladsy geplak kan word gebruik:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Voorbeelde

Om 'n voorbeeld van die sjabloon te genereer, gevul met sy eie eienskapname, gebruik:

({{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Kategorieë en interwiki-skakels

• Om die sjabloon self in 'n kategorie te plaas, plaas die [[Kategorie:Kategorienaam]]-kode binne 'n <includeonly>...</includeonly>-afdeling op die doc-subblad.
• Om 'n interwiki-skakel vir die sjabloon self te skep, gaan na Wikidata en volg die instruksies vir die byvoeg van skakels op bladsye.
• Om die doc-subblad in 'n kategorie te plaas, voeg die [[Kategorie:Kategorienaam]]-kode binne 'n <noinclude>...</noinclude>-afdeling op die doc-subblad.
• Om die sjabloon 'n artikel in 'n kategorie te laat plaas (wanneer die artikel die sjabloon insluit), voeg die [[Kategorie:Kategorienaam]]-kode binne 'n <includeonly>...</includeonly>-afdeling op die sjabloonblady in. Presiese plasing binne die sjabloonkode kan 'n invloed hê op hoe die kode uitgevoer word.

/sandput en /toetsgevalle

Alvorens veranderinge aan 'n sjabloon aangebring word, sal dit voordelig wees om eers die sjabloonkode na 'n sandput te kopieer en 'n paar toetsgevalle teen dit te laat loop, aangesien die sjabloon moontlik op duisende ander blaaie gebruik word. Indien jy subblaaie skep wat spesifiek "/sandput" en "/toetsgevalle" genoem word sal 'n groen {{Dokumentasie}}-kassie op die sjabloon dit outomaties bespeur en die skakels na hierdie bladsye in sy opskrif weergee. Sien Wikipedia:Sjabloonsandput en -toetsgevalle vir meer inligting.

Verskeie sjablone, een dokumentasieblad

Wanneer verskeie sjablone saam werk of baie eenders is, is dit soms duideliker en eenvoudiger om een dokumentasieblad te onderhou wat die sjablone saam dokumenteer. Die eenvoudigste metode om dit te bewerkstellig is om 'n volledige dokumentasieblad vir een van die sjablone te skep, en dan "sagte aansture" vanaf die ander sjablone te maak. Sien byvoorbeeld, {{wrap}}.

Indien geen dokumentasie nodig is nie

Wanneer 'n sjabloon soos hier vertoon, met 'n bladsy sal skakel wat as dokumentasie kan dien, is aparte dokumentasie oorbodig en hoef dit nie geskep te word nie. Sien byvoorbeeld 'n saadjiesjabloon wat, indien vertoon word, sal koppel aan Wikipedia:Saadjie. Dit is egter 'n skaars geval.

Nuttige wenke

Hier volg 'n paar wenke om die skryf van dokumentasie te vergemaklik:

• Skakels na sjablone soos {{Taalaanduiding|fr|Frans}} kan ingevoeg word deur {{sjp|Taalaanduiding|fr|Frans}} te skryf. Sien {{sjp}} vir soortgelyke sjablone.
• HTML-merkers soos <ref group="note">...</ref> kan maklik ingevoeg word met {{tag}}. Hierdie voorbeeld is geskryf as {{tag|ref|params=group="note"}}
• Isgelykaantekens = kan ingevoeg word met {{=}}. Byvoorbeeld, {{Vertaalvanaf|taalafk=en|}} word gemaak deur {{sjp|Vertaalvanaf|taalafk{{=}}en}}. Vermy die gelykstaande notasie = wat moeilik is vir ander redigeerders om te lees.
• Moenie die enkele <nowiki />-merker vergeet nie. [[<nowiki />voorbeeld]] word [[voorbeeld]], en [<nowiki />http://af.wikipedia.org geen skakel] is [http://af.wikipedia.org geen skakel]. Sien WP:NOWIKI vir die besonderhede.
• Vir 'n skakel na 'n kategorie, gebruik {{kat}}. Byvoorbeeld, {{kat|Sjablone}} word Kategorie:Sjablone.
• Om kategorisering van die /sandput- en /toetsgevalle-blaaie van 'n sjabloon te onderdruk (indien hulle bestaan), plaas hierdie kode onderaan die dokumentasiesubblad:

<includeonly>{{Sandput ander||
<!-- Kategorieë onder hierdie reël asseblief; interwiki's by Wikidata -->

}}</includeonly>

Sien ook

• {{Dokumentasie}} – Bring die dokumentasie oor na die sjabloonblad, verskaf sien-, redigeer- en geskiedensskakels vir die dokumentasie.
• {{Dokumentasie subblad}} – Verduidelik dat wat volg is dokumentasie, en skakel ook met die dokumentasieblad.
• <noinclude> en <includeonly>
• {{Verbeter dokumentasie}}
• Wikipedia:Hoërisiko-sjablone
• Wikipedia:Sjabloonsandput en -toetsgevalle

Hierdie artikel is in sy geheel of gedeeltelik vanuit die Engelse Wikipedia vertaal.