Wikipedia:Sjabloondokumentasie: Verskil tussen weergawes

Content deleted Content added
Wawiel (besprekings | bydraes)
k bywerking
Wawiel (besprekings | bydraes)
k redigering
Lyn 1:
{{Wikipedia-gebruiksgids|WP:SDOK}}
 
[[Hulp:Sjabloon|Sjablone]] is 'n kragtige kenmerk van [[MediaWiki]], maar dit kan verwarrend wees vir nuwe gebruikersbydraers en selfs gesoute gebruikersbydraers 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 gebruikerbydraer 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 wydalgemeen 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 tydstippein sekere tye, of ander dinge wat redigeerdersbydraers kennis van moet neem alvorens hulle besluit om die sjabloon te gebruik.
* Die sjabloon se '''[[Hulp:Sjabloon#Parameters|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 vanvir gebruik''' : spesifiseer die presiese wikitext wat gebruik behoort te word asook die resultate wat dit sal lewer. Die wikitext kan omsluit wees in {{tag|code}} -etikette om dit duideliker te maak en <code>makliker om te kopieer</code>. Indien die sjabloon byvoorbeeld op heelwat 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 keergeval. Met [[Sjabloon:Xpd]] kan dit gedoen word sonder om die sjabloon se roep 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&nbsp; – 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]]).
* '''[[Wikipedia:Kategorisering|Kategorieë]]''' waar van toepassing ([[Hulp:Interwikimedia-skakels|InterWikimedia-skakels]] moet gelys word by [[d:|Wikidata]] – meer inligting verkrygbaar by [[Wikipedia:Wikidata]]). Soos met die dokumentasie, moet kategorieë gelys word binne {{tag|noinclude}}-etikette in 'n sjabloon, of binne {{tag|includeonly}}-etikette in 'n dokumentasiebladsydokumentasieblad. 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 sjabloonbladsysjabloonblad op die ander wiki, en alles werk. By meer komplekse sjablone egter 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 diesulke gevalle is dit nuttig om 'n kort lys van sjablone of kode, wat hierdiedeur eendie spesifieke sjabloon benodig word, aan die einde van die dokumentasie in te sluit.
 
== Waar om dit te plaas ==
Sjabloondokumentasie word meermale in 'n [[Wikipedia:SubbladsyeSubblaaie|subbladsysubblad]] van die sjabloon self geplaas, wat dan [[Wikipedia:Transklusie|ingetrek]] word aan die einde van die sjabloonbladsysjabloonblad. 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 [[Wikipedia:Beskermingsbeleid|beskerm]] te word, terwyl enige een die dokumentasie kan redigeer. Die metode word soms na verwys as die "sjabloon-doc-bladsypatroonbladpatroon".
 
Enige soort dokumentasie op 'n sjabloonbladsysjabloonblad (insluitend [[Wikipedia:TemplateData|Sjabloondata]]) moet altyd omsluit word deur {{tag|noinclude}}-etikette, sodat dit nie vertoon word as die sjabloon op 'n ander bladsy gebruik word nie. Teks op die sjabloonbladsysjabloonblad dra ook by tot die hoeveelheid teks wat verwerk moet word as die sjabloon vertoon word, en vir beter werkverrigting [[Wikipedia:Sjabloonperke|ingeperk]] behoort te word. Deur die dokumentasie op 'n subbladsysubblad te plaas word die probleem vermy (MediaWiki-ontwikkelaars het dit juis vir die rede <span class="plainlinks">[http://en.wikipedia.org/w/index.php?title=Wikipedia:Village_pump_(technical)&amp;diff=prev&amp;oldid=69888944 aanbeveel]</span>).
 
== Hoe om 'n dokumentasiesubbladsydokumentasiesubblad te skep ==
SjabloondokumentasiesubbladsyeSjabloondokumentasiesubblaaie behoort, vir konsekwentheid, genoem en geformateer te word deur die volgende algemene patroon te gebruik.
 
Veronderstel jou sjabloon word <code>Sjabloon:X</code> genoem. Skep 'n subbladsysubblad met die naam <code>Sjabloon:X/doc</code>. Sien die besonderhede by {{sj|Dokumentasie subblad}} of begin 'n nuwe bladsy deur die volgende standaard wikitext te kopieer en plak:
<!---------------------------------------------------------------------------------------
Neem kennis: Die onderstaande kodeblok is gepoieer en geplak vanaf [[Sjabloon:Dokumentasie/vooraflaai]];
Lyn 88:
</source>
 
Die boonste reël sal 'n boodskap vertoon wat die huidige bladsy omskryf en 'n skakel na die sjabloonbladsysjabloonblad gee.
 
Plaas die dokumentasie na die boonste reël en kategorieë onder die gepaste kommentaarreël&nbsp;– los die kommentaar in plek, sodat die uitleg behoue bly indien die bladsy in die toekoms geredigeer word. Verwante sjablone, beleidsbladsybeleidsblad, projekte en so meer kan gekoppel word deur 'n "Sien ook" afdeling in te sluit.
 
Stoor die subbladsysubblad en keer terug na die sjabloon self, <code>Sjabloon:X</code>, in die voorbeeld. Redigeer die sjabloon en heg die volgende aan aan die einde van die sjabloonkode:
 
{{Kleur|black|[--laaste reël van jou sjabloonkode--]}}<nowiki><noinclude>
{{Dokumentasie}}
<!--Plaas asseblief hierdie sjabloon se kategorieë by die /doc-subbladsysubblad, nie hier nie!-->
</noinclude></nowiki>
 
Dit sal aan die onderkant van die sjabloonbladsysjabloonblad weergegee {{sj|dokumentasie}} word.
 
'''Belangrik''' : Verseker dat die inleiding {{tag|noinclude|o}} 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 as dit gebruik word en dit is nie wenslik nie.
 
Indien die sjabloon reeds beskerm word, vra 'n [[Wikipedia:Administrators|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 {{tag|noinclude}}-etikette, skuif hulle na die dokumentasiesubbladsydokumentasiesubblad (waar hulle omsluit moet word in {{tag|includeonly}}-etikette), aangesien dit beter is om nie dokumentasie te verdeel tussen twee aparte bladsye nie.
 
Indien kode eers op die sjabloonbladsysjabloonblad geplaas word, kan voordeel getrek word uit die [[mw:Extension:InputBox#Parameters|vooraflaai]]-kenmerk om 'n reeds gevulde doc-bladsyblad met 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-subbladsysubblad sal laai.
 
Jy kan kies om die besprekingsblad van die /doc-subbladsysubblad 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 <code>Sjabloonbespreking:X/doc</code> na <code>Sjabloonbespreking:X</code>.
 
== Blanko ==
Lyn 122:
 
== Kategorieë en interwiki-skakels ==
* '''Om die sjabloon self in 'n kategorie te plaas''' , plaas die <code><nowiki>[[Kategorie:Kategorienaam]]</nowiki></code>-kode binne 'n {{tag|includeonly}}-afdeling op die ''doc'' -subbladsysubblad.
* '''Om 'n interwiki-skakel vir die sjabloon self te skep''' , gaan na [[Wikipedia:Wikidata|Wikidata]] en volg die instruksies vir die byvoeg van skakels op bladsye.
* '''Om die ''doc'' -subbladsyinsubblad in 'n kategorie te plaas''' , voeg die <code><nowiki>[[Kategorie:Kategorienaam]]</nowiki></code>-kode binne 'n {{tag|noinclude}}-afdeling op die ''doc'' -subbladsysubblad.
* '''Om die sjabloon 'n artikel in 'n kategorie te laat plaas''' (wanneer die artikel die sjabloon insluit), voeg die <code><nowiki>[[Kategorie:Kategorienaam]]</nowiki></code>-kode binne 'n {{tag|includeonly}}-afdeling op die sjabloonbladsysjabloonblady in. Presiese plasing binne die sjabloonkode kan 'n invloed hê op hoe die kode uitgevoer word.
<!-- -->
<!-- ==Example==
See the heavily-used [[Template:cite web]] for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, [[Template:cite web/doc]] is unprotected and can still be edited.
--><!-- The preceding section appears out dated at this time. I left it here so as to hold a place for an updated example. Template:cite web now uses lua. Lua is a programming language now available via the Scribunto MediaWiki extension. -->
 
== /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 moontlike op duisende ander blaaie gebruik word. Indien jy subbladsyesubblaaie skep wat spesifiek "'''/sandput''' " en "'''/toetsgevalle''' " genoem word sal 'n groen <code><nowiki>{{Dokumentasie}}</nowiki></code>-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 dokumentasiebladsydokumentasieblad ==
Wanneer verskeie sjablone saam werk of baie eenders is, is dit soms duideliker en eenvoudiger om een dokumentasiebladsydokumentasieblad te onderhou wat die sjablone saam dokumenteer. Die eenvoudigste metode om dit te bewerkstellig is om 'n volledige dokumentasiebladsydokumentasieblad vir een van die sjablone te skep, en dan "sagte aansture" vanaf die ander sjablone te maak. Sien byvoorbeeld, {{sj|wrap}}.
 
== {{Anker|Indien geen dokumentasie nodig is nie}} Indien geen dokumentasie nodig is nie ==
<!-- ThisHierde Anchorankermerk taghet servesten todoel provideom a'n permanentpermanente targetteiken forte incomingverskaf sectionvir linksinkomende afdelingskakels. PleaseMoet dodit notnie moveuit itdie outafdelingopskrif ofskuif the section headingnie, evenal thoughontwrig itdit disruptsdie editontwikkeling summaryvan generationredigeringsamevatting (youdie canredigeringsamevatting manuallykan fixmet thedie edithand summaryreggestel beforeword youvoordat savedie yourbywerkings changesgestoor word). PleaseMoet dodit notnie modifywysig itnie, evenselfs ifalword youdie modifyafdelingopskrif the section titlegewysig. ItDit is always bestaltyd tobeter anchorom an'n oldou sectionafdelingopskrif headerwat thatverander hashet beente changedanker sosodat thatdie linksskakels todaarheen itnie won&#39;tgebreek beword brokennie. SeeSien [[TemplateSjabloon:AnchorAnker]] forvir detailsbesonderhede. (This text: [[Template:Anchor comment]]) -->
Wanneer 'n sjabloon soos hier vertoon, met 'n bladsy sal skakel wat as dokumentasie kan dien, is aparte dokumentasie oorbodig en hoef nie geskep te word nie. Sien byvoorbeeld 'n saadjiesjabloon wat, indien vertoon word, sal koppel aan [[Wikipedia:Saadjie]]. Dit is egter 'n skaars geval.
 
Line 145 ⟶ 142:
* Skakels na sjablone soos {{sjp|Taalaanduiding|fr|Frans}} kan ingevoeg word deur {{sjp|sjp|Taalaanduiding|fr|Frans}} te skryf. Sien {{sj|sjp}} vir soortgelyke sjablone.
* HTML-etikette soos {{tag|ref|params=group{{=}}"note"}} kan maklik ingevoeg word met {{sj|tag}}. Hierdie voorbeeld is geskryf as {{sjp|tag|ref|params{{=}}group{{=}}"note"}}
* Isgelykaantekens '''=''' kan ingevoeg word met {{sjn|{{=}}}}. Byvoorbeeld, {{sjp|Vertaalvanaf|taalafk{{=}}en|}} word gemaak deur {{sjp|sjp|Vertaalvanaf|taalafk{{<nowiki />=}}en}}. Vermy die gelykstaande notasie &amp;#61; wat moeilik is vir ander redigeerders om te lees.
* Moenie die enkele {{tag|nowiki|s}}-etiket vergeet nie. [[<nowiki />{{tag|nowiki|s}}voorbeeld]] word [[<nowiki />voorbeeld]], en [<nowiki></nowiki>{{tag|nowiki|s}}http://af.wikipedia.org geen skakel] is [<nowiki></nowiki>http://af.wikipedia.org geen skakel]. Sien [[WP:NOWIKI]] vir die besonderhede.
* Vir 'n skakel na 'n kategorie, gebruik {{sj|kat}}. Byvoorbeeld, {{sjp|kat|Sjablone}} word {{kat|Sjablone}}.
* Om kategorisering van die /sandput- en /toetsgevalle-bladsyeblaaie van 'n sjabloon te onderdruk (indien hulle bestaan), plaas hierdie kode onderaan die dokumentasiesubbladsydokumentasiesubblad:
<source lang="xml+smarty" style="overflow:auto;">
<includeonly>{{Sandput ander||
Line 157 ⟶ 154:
 
== Sien ook ==
* {{sj|Dokumentasie}} – Bring die dokumentasie oor na die sjabloonbladsysjabloonblad, verskaf sien-, redigeer- en geskiedensskakels vir die dokumentasie.
* {{sj|Dokumentasie subblad}} – Verduidelik dat wat volg is dokumentasie, en skakel ook met die dokumentasiebladsydokumentasieblad.
* [[m:Help:Template#Noinclude, includeonly, and onlyinclude|{{tag|noinclude|o}} en {{tag|includeonly|o}}]]
* {{sj|Verbeter dokumentasie}}