Википедија

Википедија:Dokumentacija šablona

Šabloni su veoma moćna karakteristika Medijaviki softvera, ali novim korisnicima mogu da budu zbunjujući jer čak i iskusnim korisnicima oni kompleksniji mogu stvoriti probleme. Šabloni bi zato trebalo da imaju dokumentaciju kako bi se upotrebljivost poboljšala.

Dokumentacija šablona treba da sadržava objašnjenje šta šablon radi i kako ga koristiti. Treba da bude jednostavna u tolikoj meri da korisnik koji nema kompletnu predstavu o zamršenosti šablonske sintakse — što uključuje velik broj onih koji doprinose Vikipediji već duže vreme i imaju iskustva ali pažnju usmeravaju negde drugo (samo na pisanje članaka, na primer) — može da upotrebljava šablon ispravno. Ovo naročito bitno u slučaju šablona koji su široko korišćeni.

Treba uključivati uredi

Dokumentacija šablona treba da pokriva:

  • Osnovnu svrhu šablona: šta predstavlja i čini i ako nije odmah očigledno, zašto to treba odraditi. Ako postoje drugi šabloni sa sličnim imenima ili svrhama, dobro je pomenuti ih, kako bi se smanjila mogućnost korišćenja pogrešnog.
  • Parametre šablona: da li su numerisani, imenovani ili opcionalni, i ako jesu, koje su podrazumevane vrednosti i kakav efekat imaju. Ako parametar može uzeti samo ograničen skup vrijednosti ili je na bilo koji način ograničen, na primjer, ako može koristiti samo "da", "ne" ili broj, to treba jasno objasniti.
  • Primere korišćenja: navesti tačan Vikitekst koji može da bude korišćen i rezultat koji daje. Vikitekst može biti obuhvaćen u <code>...</code> šablonu, kako bi bio jasan i jednostavan za kopiranje (poput једноставан за копирање ). Ako se šablon može koristiti na nekoliko različitih načina, sa ili bez izbornih parametara, na primer, potrebno je obezbediti niz više određenih primera. Dobar način da se to učini je da se sam uzorak nekoliko puta unese u dokumentaciju (tj.da se ​​koriste konkretni primeri), svaki put sa različitim parametrima i da se ispišu parametri koji se koriste u svakom od tih slučaju. Sa šablonom:Šablon:Xpd se ovo može uraditi bez postavljanja šablona dvaput u Vikitekst (vrsta olakšice).
  • Srodne šablone: ako je šablon jedan od niza šablona, treba uključiti linkove koji vode ka njima - praktično, osigurajte svaki šablon u nizu treba biti povezan sa svakim drugim, jer to olakšava navigaciju u pretrazi. (Odvojeni šablon za navigaciju može biti koristan za ovu svrhu, možete pogledati Šablone zaštite).
  • Kategorije gde je to moguće (Unutrašnje Vikimedija linkove koji trebaju biti navedeni na Vikipodatke). Kao i dokumentacija, kategorije moraju biti navedene u <noinclude>...</noinclude> šablonu na šablonu ili unutar <includeonly>...</includeonly> oznake (ako se nalaze na stranici dokumentacije).

Dokumentacija šablona se često postavlja u podstranici samog šablona, zatim se prenosi na kraju stranice šablona. Ovo razdvaja često složene šablonske kodove dokumentacija, što ujedno olakšava uređivanje dokumentacije. Takođe, omogućuje zaštitu šablona tamo gde je potrebno i dozvoljava svakome da uredi dokumentaciju.

Dokumentacija bilo koje vrste na stranici šablona treba uvek da bude zatvorena sa <noinclude>...</noinclude> oznakom, tako da se ne pojavljuje kada se šablon koristi na drugoj stranici. Tekst na samoj stranici šablona dodaje na količini teksta koji se mora obraditi prilikom prikazivanja šablona, što je ograničeno na Vikipediji. Postavljanje dokumentacije u podstranicu izbegava ovaj problem i ovaj metod je predložen od strane programera VikiMedija-projekta.

Kako kreirati podstranicu za dokumentaciju? uredi

Podstranicu dokumentacije šablona treba imenovati i formatirati koristeći opšti obrazac za konzistentnost. Pretpostavimo da je vaš šablon imenovan Шаблон:X. Pogledati detalje na ili pokrenuti stranicu kopiranjem sledećeg standardnog Vikiteksta:

{{Documentation subpage}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[</nowiki>[[Wikipedia:Wikidata]]<nowiki>]]) -->
== Usage ==


<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>

U gornjoj liniji će se prikazati poruka koja objašnjava trenutnu stranicu i vezi do stranice šablona.

Ubaciti dokumentaciju iza gornje linije i kategorije pod odgovarajuću liniju komentara - ostavite komentar na mestu, tako da izgled bude sačuvan kada se stranica uredi u budućnosti. Srodni šabloni, stranica politike, projekti, i sl. mogu se povezati dodavanjem odjeljka "Vidi takođe".

Sačuvati podstranicu i vratiti se samom šablonu, Template:X u ovom primeru. Urediti šablon i dodati sledeće na kraju koda šablona 

[--last line of your template code--]<noinclude>
{{Documentation}}
<!--Please add this template's categories to the /doc subpage, not here - thanks!-->
</noinclude>

Ovo će uključiti {{documentation}} na dnu stranice šablona.

Važno: Uverite se da otvaranje <noinclude> počinje odmah nakon poslednjeg znaka koda šablona ili teksta, a ne na novoj liniji, niti s bilo kojim interventnim prostorom. U suprotnom, dodatni prostor će biti umetnut ispod šablona kada se koristi, što obično nije poželjno.

Ako je šablon već zaštićen, zatražite od administratora da to učini umesto vas ili zatražite izmenu pomoću {{edit protected}} na stranici za razgovor. Ako dokumentacija i kategorije već postoje u odeljku, koji se nalazi unutar šablona <noinclude>...</noinclude>, premestite ih u podstranicu dokumentacije (gde bi trebalo da se nalaze u <includeonly>...</includeonly>), jer je najbolje da dokumentacija nije podeljena na dve odvojene stranice.

Ako se kod prvo stavi na stranicu šablona, može se iskoristiti mogućnost ponovnog učitavanja da bi se dobio unapred popunjen skelet stranice dokumenta; ako stranica dokumentacije još ne postoji, klikom na link za uređivanje na stranici šablona učitat ćete sadržaj šablona u polju za uređivanje.

Ako ipak želite da preusmerite stranicu za razgovor na to učinite na dok. podstranici na stranu za razgovor samog šablona. Onda će svi razgovori koji se odnose na šablon i njegova dokumentacija završiti na istoj stranici. Na primer, preusmeri Template talk:X/docu Template talk:X.

Prazan šablon uredi

Da biste generisali prazan šablon, koji se zatim može kopirati iz dokumentacije i zalijepiti na drugu stranicu, upotrijebite:

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

Primeri uredi

Da biste generisali parametar šablona, popunjen sopstvenim imenima svojstava, koristite:

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

Kategorije i unutrašnji linkovi uredi

  • Da biste postavili sam šablon u kategoriju, dodajte [[Category:Category name]] na podstranici dokumentacije.
  • Da biste kreirali interviki vezu za sam obrazac, idite na Vikipodatke i pratite uputstva za dodavanje veza na stranice.
  • Da biste podstranicu dokumentacije stavili u kategoriju, dodajte kod [[Category:Category name]]sekcije na podstranici dokumenta.
  • Da bi šablon postavio članak u kategoriju (kada članak već sadrži šablon), dodajte [[Category:Category name]] na stranici šablona. Tačan položaj unutar šifre šablona može uticati na način izvršavanja koda kategorije.

/Stranica pesak i /test slučajeva uredi

Pre nego što napravite promene u šablonu, dobro je da prvo prepišete kod šablona u stranici pesak, pokrenete testove slučajeva, pošto bi šablon mogao biti vidljiv na hiljadama ili čak milionima stranica. Ako kreirate podstranice koje se nazivaju tačno /stranica pesak, /test slučajeva u šablon onda zeleno polje {{documentation}}na šablonu automatski detektuje ovo i prikazuje veze do tih stranica u zaglavlju.

Nekoliko šablona, jedna stranica dokumentacije uredi

When several templates work together or are very similar then it is often clearer and easier to maintain one single documentation page that documents them together. The simplest way to do this is to make a full documentation page at one of the templates, and then make "" from the other templates. See, for instance, {{wrap}}.

.Kada nekoliko šablona rade zajedno ili su veoma slični onda je često jasnije i lakše održavati jednu stranicu sa dokumentacijom koja ih dokumentuje zajedno. Najjednostavniji način da to uradite je da napravite stranicu sa kompletnom dokumentacijom na nekom od šablona, a zatim napravite botove braćače iz drugih šablona. Na primer,

Kada dokumentacija nije potrebna uredi

Kada se prikaže šablon, on će se povezati na stranicu koja može poslužiti kao dokumentacija, onda je odvojena dokumentacija suvišna i ne treba je kreirati. Na primer, stub šablona koji će, kada se prikaže, povezati sa Vikipedijom:Wikipedia:Stub. Ovo je veoma retko, ali nekada može biti od pomoći.

Saveti i trikovi uredi

Evo nekoliko saveta za olakšavanje pisanja dokumentacije

  • Kansei 12 mogu se umetnuti pisanjem {{japanske godine|1800}}. Pogledajte {{tlp|Japanese year|1800}} za slične šablone.
  • HTML oznake kao {{tag}}mogu se lako umetnuti sa <tag>...</tag>. Ovaj primer je napisan kao <ref group="note">...</ref>
  • Znak jednakosti = može biti unesen kodom {{=}} Na primer, [traži se izvor] je napravljen od stranice {{tlp|Citation needed|date{{=}}07. 2019.}}. Izbegavajte ekvivalentnu notaciju & # 61; jer drugim urednicima neće biti lako čitati.
  • Ne zaboravite oznaku [[<nowiki />example]] postaje [[пример]], i [<nowiki />http://sr.wikipedia.org bez linka]
  • Za vezu do kategorije koristite [[:Kategorija:{{{1}}}]]. Na primer, {{cat}} postaje kategorija: šabloni sa netačnom sintaksom parametara.
  • Da biste suzbili kategorizaciju stranica /stranica pesak i /test slučajeva šablona (ako postoje), koristite ovaj kod pri dnu podstranice dokumentacije. Linkovi na šablone:
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||{{#ifeq:{{SUBPAGENAME}}|testcases||
<!--Categories below here, please; interwikis to Wikidata.-->

}}}}</includeonly>

Vidi još uredi


Preuzeto iz „https://sr.wikipedia.org/w/index.php?title=Википедија:Документација_шаблона&oldid=26665202”