|
|
Line 1: |
Line 1: |
| {{User:QDP2012/pages}} | | {{User:QDP2012/pages}} |
| . | | . |
− | ----
| |
− | ----
| |
− | {{Templates-List/pages}}<br/>
| |
− | __TOC__
| |
− | ==Template Documentation==
| |
− | *Templates are documented either in the template itself (when the template is short and simple), or in a "/doc" sub-page. The "/doc" sub-page link will be found at the bottom of the template, and will be the template's name with "/doc" appended to it (without quotes). Example: [[:Template:Cat_State]]'s documentation is located at: [[:Template:Cat_State/doc]]
| |
− |
| |
− | ==Templates List==
| |
− | *Template-names have been chosen with the purpose of them sorting alphabetically in such a way that templates with similar purposes will naturally sort together in the list.
| |
− |
| |
− | ==What to Consider When Creating or Documenting a Template==
| |
− | ===Template Name Selection===
| |
− | *Template Names should:
| |
− | **be short and concise, not long and verbose. Abbreviations are often appropriate.
| |
− | **clearly reflect the type and purpose of the template.
| |
− | **be chosen so that when the names are sorted, templates of the same type and those with similar-purpose are listed together.
| |
− | **begin with a broader description and end with a more specific description
| |
− | *Examples:
| |
− | {| {{table}} width="100%"
| |
− | |- bgcolor="lightgrey" |
| |
− | ! Template Name<br/>Example!! Name Segment !! Explanation
| |
− | |-
| |
− | | rowspan="4" | '''Cat_StateFireSvcsFreq''' || Cat || the template is a categories-template (is used to create a category)
| |
− | |-
| |
− | || State || the template is related to state-specific categories
| |
− | |-
| |
− | || FireSvcs || the template is related to state-specific fire-services categories
| |
− | |-
| |
− | || Freq || the template is related to state-specific fire-services categories that list frequencies.
| |
− | |-
| |
− | | rowspan="3" | '''Infobox_TRS_MultiState''' ||Infobox || the template is an InfoBox-template (displays an InfoBox)
| |
− | |-
| |
− | || TRS || the template is an InfoBox-template for a Trunked Radio System
| |
− | |-
| |
− | || MultiState || the template is an InfoBox-template for a Trunked Radio System that spans more than one state
| |
− | |-
| |
− | | rowspan="2" | '''Tracker_DMR''' || Tracker || the template is a Tracker-template (displays warnings about certain TRS types)
| |
− | |-
| |
− | || DMR || this Tracker-template relates to DMR/MOTOTRBO systems
| |
− | |-
| |
− | | rowspan="2" | '''USFSinCA''' || USFS || relates to the United States Forest Service
| |
− | |-
| |
− | || inCA || relates to the United States Forest Service in California
| |
− | |-
| |
− | | rowspan="2" | '''INPH_SAFET_Pages''' ||INPH_SAFET || relates to the Indiana Project Hoosier SAFE-T article(s)
| |
− | |-
| |
− | |Pages || lists the Indiana Project Hoosier SAFE-T pages.
| |
− | |}
| |
− |
| |
− | ===Template Documentation Style===
| |
− | *Template Documentation style will vary based upon Template-Type.
| |
− | **A "Text..." template which uses no parameters, and only displays boilerplate text, probably will only require brief documentation at the bottom of the template itself.
| |
− | **An "InfoBox..." template which uses several parameters, will likely deserve a separate "/doc" sub-page so that the template's documentation does not clutter and oversize the template itself.
| |
− | *Style Examples and "How to" instructions are near the end of this page.
| |
− |
| |
− | ===Template Documentation Content===
| |
− | *What to include in the template documentation:
| |
− | {| {{table}} width="100%"
| |
− | |- bgcolor="lightgrey" |
| |
− | ! colspan="2" | Attribute !! Details
| |
− | |-
| |
− | | colspan="2" | '''Template's Name''' || (case sensitive)
| |
− | |-
| |
− | | colspan="2" | '''Template's Type''' ||
| |
− | *general-use,
| |
− | *categories-related (if so, specify which),
| |
− | *set-of-pages-related (if so, specify which)
| |
− | *etc.
| |
− | |-
| |
− | | colspan="2" | '''Template's Purpose''' || give a clear but concise explanation
| |
− | |-
| |
− | | colspan="2" | '''What is expected to invoke this template?''' ||
| |
− | * another template, category, or article?
| |
− | **which one(s) specifically if known?
| |
− | |-
| |
− | | colspan="2" | '''What should not invoke this template?''' ||
| |
− | *another template, category, or article?
| |
− | **which one(s) specifically if known?
| |
− | **And, why, if reason is not apparent.
| |
− | |-
| |
− | | colspan="2" | '''Template's Parameters''' || if any are used
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Parameter Name''''' || (case-sensitive)
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Parameter Description''''' || provide a description if Parameter Name is unclear because it is anonymous, numbered, or specified but abbreviated
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Expected Value(s)''''' ||
| |
− | this includes:
| |
− | *unspecified,
| |
− | *specified with no value,
| |
− | *and specific expected values
| |
− | **list the specific values
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Default Value''''' ||list the default value, if the default-value feature is used
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Required'''''? || if a parameter-value is required, indicate so clearly.
| |
− | |-
| |
− | | bgcolor="lightgrey" | ||'''''Notes'''''||
| |
− | *Does this parameter '''''override or hide''''' another parameter's value. If so, explain.
| |
− | *Can this parameter be '''''overridden or hidden''''' by another parameter's value. If so, explain.
| |
− | *If this template is invoked by other templates, does the behavior of this template vary based upon which other template invokes this one? If so, explain in concise detail.
| |
− | **Example: Does another template cause this template to hide certain text, while a different template causes this template to display that same text?
| |
− | |-
| |
− | | colspan="2" | '''Examples of how to invoke the template.''' || Each example should be displayed so that it may be copy-pasted by another Wiki-editor who wants to invoke the template in that manner.
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template is invoked with only the required values provided, and relying on default values (This is likely to be the simplest way to invoke this template.)
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique; either show the verbatim result, or describe it in sufficient detail
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template is invoked with appropriate combinations of required values and specified values that override the default values
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique; either show the verbatim result, or describe it in sufficient detail
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template is invoked with the most complex or complete use of parameters.
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique; either show the verbatim result, or describe it in sufficient detail
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template can be invoked to produce unexpected but useful results
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique; either show the verbatim result, or describe it in sufficient detail
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Example(s) of how...''''' || ...the template should not be invoked if the situation is an easy error to make.
| |
− | |-
| |
− | | bgcolor="lightgrey" | || '''''Results...''''' || ...of the above technique; either show the verbatim result, or describe it in sufficient detail
| |
− | |}
| |
− |
| |
− | ==How to Document a Short Simple Template==
| |
− | *In the template, while in edit mode, go to the bottom of the template, after the template-definition, and place the documentation between "noinclude" tags, as illustrated below, (and then save the template):
| |
− | **Example:[[:Template:Forum]]
| |
− | ...(''end of the template-definition.'')'''<nowiki><noinclude>
| |
− | ----
| |
− | Please note: These notes and the line above do not display when this template is invoked.
| |
− | <br/><br/>
| |
− |
| |
− | ...place documentation here...</noinclude></nowiki>'''
| |
− |
| |
− | ==How to Document a Template using a "/doc" Sub-Page==
| |
− | *In the template, while in edit mode, go to the bottom of the template, after the template-definition, and place the following Wiki-code between "noinclude" tags, as illustrated below, (and then save the template):
| |
− | **Example: [[:Template:Cat_State/doc]]
| |
− | **Other "/doc" pages listed in [[:Category:Documentation]] can be used as examples for specific types of templates.
| |
− | ***Templates themselves usually will not be assigned the "[[:Category:Documentation]]" category.
| |
− | ***Templates' "/doc" sub-pages should be assigned the "[[:Category:Documentation]]" category.
| |
− |
| |
− | ...(''end of the template-definition.'')'''<nowiki><noinclude>
| |
− |
| |
− | ==Template Documentation==
| |
− | *Please navigate to [[:Template:{{PAGENAME}}/doc]] for documentation about this template.</noinclude></nowiki>
| |
− |
| |
− | *After saving the template with the above documentation link, then scroll to the bottom of the template (not in edit mode), and click on the "/doc" link to create the "/doc" page.
| |
− |
| |
− | *When the "/doc" page opens in edit mode, please use something similar to the following section-structure as you build the documentation page.
| |
− | **Parenthetical indicators below should be replaced with actual descriptions.
| |
− |
| |
− | ==Documentation Sub-page for Template:(template_name)==
| |
− | ===Scope of Use===
| |
− | ====Purpose====
| |
− | *'''<nowiki>[[:</nowiki>Template:(template_name)<nowiki>]]</nowiki>''' should be used to build ... (explain here what this template builds, creates, or displays)
| |
− | *'''<nowiki>[[:</nowiki>Template:(template_name)<nowiki>]]</nowiki>''' is designed to be a ("general-use" or "categories" or "set-of-related-pages")-template that... (describe this template's purpose with respect to commonality and/or uniformity of on-screen text, of categories assigned, of navigation-related links, of external resource links, etc.)
| |
− |
| |
− | ====Directly Invoked By====
| |
− | *'''<nowiki>[[:</nowiki>Template:(template_name)<nowiki>]]</nowiki>''' should be directly invoked only by...(describe which specific articles, categories, and/or templates should invoke this template).
| |
− |
| |
− | ====Not Intended For====
| |
− | *'''<nowiki>[[:</nowiki>Template:(template_name)<nowiki>]]</nowiki>''' should not be directly invoked by...(describe which specific articles, categories, and/or templates should not invoke this template).
| |
− |
| |
− | ===Paramaters===
| |
− | *Specified values will override default values.
| |
− | *Specified values and Default values are all case-sensitive.
| |
− |
| |
− | {| {{table}} width="100%"
| |
− | |- bgcolor="lightgrey" |
| |
− | ! Parameter Name !! Parameter Description !! Expected Value(s) !! Default Value !! Notes
| |
− | |-
| |
− | | '''(first parameter)'''<br/><br/>(list only one parameter per table-row) || (parameter description if parameter name is not clear; otherwise leave table-cell blank) ||
| |
− | *unspecified or
| |
− | *specified with no value or
| |
− | *specified value(s) (without quotes)
| |
− | **"value 1"
| |
− | **"value 2"
| |
− | **etc.
| |
− | ||
| |
− | *list the default value, if one is used; otherwise leave table-cell blank
| |
− | || {{color|red|A value is Required}} (clearly indicate whether a value is required; use red font sparingly)<br/><br/>(list other notes here regarding this row'sparameter)
| |
− | |-
| |
− | | '''(second parameter)''' || || || ||
| |
− | |-
| |
− | | '''(add additional row for each additional parameter)''' || || || ||
| |
− | |}
| |
− |
| |
− | ===Examples===
| |
− | *The horizontal lines below separate examples for clarity and do not appear when template is invoked.
| |
− | ----
| |
− | ----
| |
− | ====How to invoke this template for ...(idea 1)====
| |
− | *<nowiki>{{template_name|required parameters and values}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− |
| |
− | ====How to invoke this template for ...(idea 2)====
| |
− | *<nowiki>{{template_name|required parameters and different values}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− |
| |
− | ====How to invoke this template for ...(idea 3)====
| |
− | *<nowiki>{{template_name|required parameters and values that override defaults}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− |
| |
− | ====How to invoke this template for ...(idea 4)====
| |
− | *<nowiki>{{template_name|all parameters and values in more complex or advanced configuration}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− |
| |
− | ====How to invoke this template for ...(idea 5)====
| |
− | *<nowiki>{{template_name|parameters and values that produce unexpected but useful result}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− | ====How to avoid common error(s) while invoking this template for ...(idea 6)====
| |
− | *<nowiki>{{template_name|parameters and values to show how not to invoke this template}}</nowiki>
| |
− | ----
| |
− | =====Result=====
| |
− | .(either show the verbatim result, or describe it in sufficient detail)
| |
− | ----
| |
− | ----
| |
− |
| |
− |
| |
− |
| |
− |
| |
− |
| |
− |
| |
− |
| |
− | Return to: <nowiki>[[:Template:template_name]]</nowiki>
| |
− |
| |
− | <nowiki>[[Category:Documentation]]</nowiki>
| |
− |
| |
− | ==End of Documentation Sub-Page Structure Example==
| |
− | .
| |
− |
| |
− |
| |
− |
| |
− |
| |
− |
| |
− | {{Templates-List/pages}}<br/>
| |
− |
| |
− | [[Category:Documentation]]
| |