Роҳнамо:Ҳуҷҷатгузории шаблонҳо ва модулҳо

Шаблонҳо ва модулҳо хусусиятҳои хеле пурқуввати MediaWiki мебошанд, аммо метавонанд барои корбарони нав иштибоҳ оваранд ва ҳатто корбарони ботаҷриба дар фаҳмидани маъно мушкилӣ дошта бошанд. аз мураккабтар. Аз ин рӯ, онҳо бояд бо ҳуҷҷатҳо ҳамроҳ карда шаванд, то қобили истифода бошанд.

Ҳуҷҷатҳо бояд фаҳмонанд, ки қолаб ё модул чӣ кор мекунад ва чӣ тавр истифода бурдани он. Барои қолабҳо, аз ҷумла, он бояд ба қадри кофӣ содда бошад, ки корбаре, ки дар бораи нозукиҳои синтаксиси қолаб маълумот надорад, ки аз он бисёр саҳмгузорони ботаҷрибае, ки диққати худро ба ҷои дигар равона мекунанд, дар бар мегирад, метавонад онро дуруст истифода барад. Ин махсусан дар мавриди қолабҳои хеле васеъ истифодашаванда дуруст аст.

Чӣ бояд дохил карда шавад

Ҳуҷҷатҳо бояд дар бар гиранд:

• Категорияҳо, дар ҳолати имконпазир. Инҳо бояд дар дохили контейнери Шаблон:nowrap бошанд. Модулҳоро ба ҷуз аз тариқи саҳифаи ҳуҷҷатгузорӣ гурӯҳбандӣ кардан мумкин нест, аз ин рӯ ин барои онҳо махсусан муҳим аст. Ҳар як модул бояд саҳифаи ҳуҷҷатгузорӣ бо категория дошта бошад, ҳатто агар шумо ягон ҳуҷҷати дигарро нанависед (ҳоло). Бисёр категорияҳо мавҷуданд, барои дидани онҳо ба Category:Templates ва Category:Modules нигаред.
• Ҳадафи асосии қолаб ё модул: он чӣ кор мекунад ва агар он фавран маълум набошад, чаро он бояд анҷом дода шавад. Агар қолибҳо ё модулҳои дигаре бо номҳо ё ҳадафҳои шабеҳ вуҷуд дошта бошанд, хуб аст, ки онҳоро зикр кунед, то эҳтимолияти истифодаи нодурусти онро кам кунед.
• Параметрҳои-и қолаб ё модул: оё онҳо рақамгузорӣ шудаанд, номгузорӣ шудаанд ё ихтиёрӣ ва агар ин тавр бошад, арзишҳои пешфарз чист ва онҳо чӣ гуна таъсир доранд. Агар параметр танҳо маҷмӯи маҳдуди арзишҳоро қабул карда тавонад ё бо ягон роҳ маҳдуд бошад, масалан, агар он танҳо "ҳа", "не" ё рақамро истифода бурда тавонад, ин бояд возеҳ шарҳ дода шавад.
• Намунаҳои истифодабарии қолаб: викиматни дақиқеро, ки бояд истифода шавад ва натиҷаеро, ки он тавлид мекунад, муайян кунед. Викиматнро метавон дар як контейнери Шаблон:nowrap иҳота кард, то он равшан ва нусхабардории осо, ба монанди: ин. Агар қолабро бо чанд роҳ, бо параметрҳои ихтиёрӣ ё бидуни параметрҳо истифода бурдан мумкин бошад, масалан, як қатор мисолҳоро пешниҳод кунед. Роҳи хуби ин кор ин аст, ки худи қолабро чанд маротиба ба ҳуҷҷатгузорӣ дохил кунед (яъне истифода бурдани мисолҳои зинда), ҳар дафъа бо параметрҳои гуногун ва номбар кардани параметрҳои дар ҳар як ҳолат истифодашаванда.
• Шаблонҳо ё модулҳои алоқаманд: агар қолаб ё модул як қисми маҷмӯа бошад, ки ба ҳадафи умумӣ хизмат мекунад, истинодҳоро ба инҳо дохил кунед - алахусус, боварӣ ҳосил кунед, ки ҳар яки силсила аз ҳар яки дигар алоқаманд аст , зеро ин паймоишро осон мекунад.

Ҳуҷҷатҳо дар зерсаҳифаи шаблон ё худи модул бо номи /documentation ҷойгир карда мешаванд. Модулҳо ба таври худкор ин саҳифаро ба саҳифаи асосии модул интиқол медиҳанд. Шаблонҳо ин корро намекунанд, бинобар ин шумо бояд барои ин кор қолаби {{documentation}}-ро истифода баред. Ин рамзи шаблонҳои аксаран мураккабро аз ҳуҷҷатҳо ҷудо мекунад ва таҳрир кардани ҳуҷҷатҳоро осон мекунад. Он инчунин имкон медиҳад, ки қолабҳо дар ҳолати зарурӣ муҳофизат карда шаванд ва дар ҳоле ки ба касе имкон медиҳад, ки ҳуҷҷатҳо ва категорияҳоро таҳрир кунад. Матн дар саҳифаи қолаб ба миқдори матне, ки ҳангоми намоиши қолаб бояд коркард шавад, илова мекунад, ки бо сабабҳои иҷроиш маҳдуд аст. Ҷойгиркунии ҳуҷҷатҳо дар зерсаҳифа аз ин пешгирӣ мекунад (ба ин сабаб таҳиягарони MediaWiki онро тавсия мекунанд доранд).

Чӣ тавр зерсаҳифаи ҳуҷҷатгузорӣ эҷод кардан мумкин аст

Зерсаҳифаҳои ҳуҷҷатгузорӣ бояд бо истифода аз намунаи умумии зерин барои мувофиқат номгузорӣ ва формат карда шаванд.

Фарз мекунем, ки қолаби шумо Template:X ном дорад ё модули шумо Module:X ном дорад. Зерсаҳифаеро бо номи Template:X/documentation ё Module:X/documentation эҷод кунед. Тафсилотро дар зер саҳифаи {{documentation}} бубинед ё викиматни зеринро ҳамчун оғози ҳуҷҷатгузории худ нусхабардорӣ кунед:

{{documentation subpage}}
<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->

== Usage ==

<includeonly><!-- CATEGORIES AND INTERWIKIS HERE, THANKS -->

</includeonly>

Сатри боло паёмеро нишон медиҳад, ки саҳифаи ҷорӣ ва истинод ба саҳифаи асосии шаблон ё модулро шарҳ медиҳад.

Ҳуҷҷатҳоро пас аз сатри боло ва категорияҳо ва интервикиҳоро дар зери хати шарҳи мувофиқ ҷойгир кунед - шарҳро дар ҷои худ гузоред, то ки тарҳ ҳангоми таҳрири саҳифа дар оянда нигоҳ дошта шавад. Пас зерсаҳифаро захира кунед.

Маълумоти иловагӣ барои шаблонҳо

Дар мавриди қолаб, шумо инчунин бояд зерсаҳифаи ҳуҷҷатҳоро ба худи шаблон илова кунед. Дар ин мисол ба саҳифаи асосии шаблон, Template:X баргардед. Шаблонро таҳрир кунед ва дар охири рамзи шаблон матни зеринро илова кунед:

[--last line of your template code--]<noinclude>{{documentation}}</noinclude>

Ин {{documentation}}-ро дар поёни саҳифаи шаблон фаро мегирад.

Муҳим: Боварӣ ҳосил кунед, ки кушодани <noinclude> дар ҳамон сатр бо аломати охирини код ё матни шаблон оғоз мешавад ва не дар хати нав. Дар акси ҳол, ҳангоми истифода аз қолаб фазои иловагӣ ворид карда мешавад, ки одатан намехоҳад.

Агар қолаб аллакай ҳифз шуда бошад, аз администратор хоҳиш кунед, ки ин корро анҷом диҳад ё дар саҳифаи баҳси қолаб таҳрирро дархост кунед. Агар ҳуҷҷатҳо, категорияҳо ва истинодҳои байнивики аллакай дар бахше мавҷуд бошанд, ки дар дохили контейнери Шаблон:nowrap замима шудаанд, онҳоро интиқол диҳед. ба зерсаҳифаи ҳуҷҷатгузорӣ ворид кунед, зеро беҳтар аст, ки ҳуҷҷатҳоро ба ду саҳифаи алоҳида тақсим накунед.

Дар хотир доред, ки агар дар саҳифаи шаблон аввал қолаби {{documentation}} гузошта шавад, кас метавонад аз хусусияти пешборкунии баҳра барад, то скелети саҳифаи пешакии ҳуҷҷатро ба даст орад; агар саҳифаи ҳуҷҷатгузорӣ ҳанӯз вуҷуд надошта бошад, зеркунии истиноди таҳрир дар саҳифаи шаблон мундариҷаи Шаблон:documentation/preload-ро ба қуттии таҳрири зерсаҳифаи /documentation пешакӣ бор мекунад.

Категорияҳо ва истинодҳои байнивики

• Барои ҷойгир кардани худи шаблон ё модул ба категория, рамзи [[Категория:Номи категория]] -ро дар дохили <includeonly>...</includeonly> дар зерсаҳифаи documentation.

• Барои сохтани пайванди байнивики барои худи шаблон ё модул, рамзи [[Languagecode:Шаблон номи]] -ро дар дохили < илова кунед. nowiki></nowiki> дар зерсаҳифаи ҳуҷҷатҳо.

• Барои ҷойгир кардани зерсаҳифаи ҳуҷҷат ба категория, рамзи [[Категория:Номи категория]]-ро дар дохили илова кунед. <noinclude>...</noinclude> дар зерсаҳифаи ҳуҷҷатҳо.

• Барои ҷойгир кардани қолаб мақоларо ба категорияи (вақте ки мақола шаблонро дар бар мегирад), илова кунед [[Категория:Номи категория]] рамзи дохили як бахши <includeonly>...</includeonly> дар саҳифаи шаблон. Барои модулҳо муодили он аст, ки рамзи категория ҳамчун қисми викиматни баргардонидашуда "баргардонида шавад".

Мисол

Барои намунаи ҳуҷҷатҳои муфассали қолабҳо ба Шаблон:tr-noun-и хеле истифодашаванда нигаред. Дар хотир доред, ки худи қолаб ҳифз шудааст, аммо зерсаҳифаи ҳуҷҷатгузорӣ Шаблон:en-noun/documentation ҳифзнашуда аст ва ҳоло ҳам метавонад таҳрир карда шавад.

Якчанд шаблон, як саҳифаи ҳуҷҷатгузорӣ

Вақте ки якчанд қолабҳо якҷоя кор мекунанд ё ба ҳам монанданд, нигоҳ доштани як саҳифаи ягонаи ҳуҷҷатгузорӣ, ки онҳоро якҷоя ҳуҷҷат мекунад, аксар вақт равшантар ва осонтар аст. Роҳи соддатарини ин кор ин аст, ки дар яке аз қолабҳо як саҳифаи пурраи ҳуҷҷатгузорӣ созед ва сипас аз саҳифаҳои ҳуҷҷатгузории қолибҳои дигар "баҳисобгирӣ" кунед. Барои намунаи ин принсип Шаблон:nl-conj-wk ва Шаблон:nl-conj-st нигаред.

Ҳамчунин нигаред

• {{documentation}} – Ҳуҷҷатҳоро дар саҳифаи шаблон фаро мегирад ва намоиши ҳуҷҷатҳо, таҳрир ва истинодҳои таърихро таъмин мекунад
• {{documentation subpage}} – Мефаҳмонад, ки он чизест, ки дар поён ҳуҷҷатгузорӣ аст ва ба саҳифаи ҳуҷҷатшуда истинод мекунад
• Шаблон:wikitag ва Шаблон:wikitag