Help:Template documentation

From The Scuba Wiki

This help page is about documenting templates. General Template help can be found at Help:Template.

There are several ways to document what a template is supposed to do:

1. In some cases it is obvious on the template page itself without special provisions.
2. It can be explained in <noinclude>text</noinclude> tags.

   This method allows for such things as adding the template to a template category.

3. Detailed documentation can be put on the template talk page.

   This method is typically mixed with the noinclude-strategy on the template page, with a reference to the talk page, and perhaps a summary.

On the template page

The template page serves two purposes: defining the way it works when included in another page, and producing a rendered page providing information. The parts not in noinclude tags define the template for the system. The parts of the wikitext not in includeonly tags are rendered on the template page. With the two types of tag pairs the template page can be used for both definition and documentation.

A typical template page could contain:

<includeonly><!--template name-->definition content, possibly a tag for a category of pages that include the template</includeonly><noinclude><nowiki>definition content, possibly formatted, annotated, summarized</nowiki>further explanation, tags for template categories (using the sortkey {{PAGENAME}})</noinclude>

The template name within comment tags is useful in the case of substitution.

For example, for template:t ( talk edit history links ):

<includeonly>start-{{{1|pqr}}}-end</includeonly><noinclude><nowiki>start-{{{1|pqr}}}-end</nowiki>[[Category:Demo template]]</noinclude>

This renders as:

start-{{{1|pqr}}}-end

while without tags part of the information about the content would not be displayed:

start-pqr-end

Alternatively the part of the definition content which is rendered without loss of information (in particular plain text) is not put in either type of tags, so that it does not have to be duplicated:

start-<includeonly>{{{1|pqr}}}</includeonly><noinclude><nowiki>{{{1|pqr}}}</nowiki>[[Category:Demo template]]</noinclude>-end

again rendered as:

start-{{{1|pqr}}}-end

Applying substitution without parameter produces this as wikitext. It can be displayed by subsequently putting nowiki tags around it.

Table

If a template produces a table it is useful if the template page shows the table structure instead of the wikitext to make it. For that purpose the table syntax is not put in either type of tags, and the table elements, where needed, each have a noinclude and an includeonly part.

Rendering

As shown above, in straightforward rendering of definition content, information is lost in the case of a parameter with a default value: only that value is rendered. Other cases where information is lost include:

• #expr applied to an expression with a parameter gives "Expression error: unrecognised punctuation character "{"".
• a variable is rendered as its value.

The parameter default mechanism can also be used to document what a parameter typically does:

• An undefined {{{1}}} is rendered as {{{1}}}, clearly indicating that the template expects to get a first parameter.
• An undefined {{{1|}}} displays nothing, that's probably the desired effect, but not helpful for a self-documentating template.
• Maybe it's possible to indicate the function of an expected parameter, e.g. {{{1|image}}} for templates doing something with images.

Typically, examples in the noinclude-part include or substitute the template. Note that changes in the working of the template (i.e. changes outside the noinclude-part) are not yet effective in these examples in preview and, in the case of substitution, in "show changes".

Category

Some templates are designed to add pages to a given category. Sometimes it's good enough if the template page itself is also shown in that category. Generally that's not the case. Templates adding pages to a category then use:

...end of code<includeonly>[[Category:target]]
</includeonly><noinclude>
documentation and/or link to talk page
[[Category:tempcat|{{PAGENAME}}]]
</noinclude>

Here target means a category for pages using the template, and tempcat is a category for similar templates. This method could be also used for interlanguage links in a template.

A small improvement seen on some templates replaces [[Category:target]] by {{{category|[[Category:target]]}}}. Normally the dummy parameter {{{category}}} is undefined (unused), and then the template adds pages to category target as before. Setting category= (empty value) allows to disable this feature on lists of templates. Otherwise template lists with examples would be added to the various target categories of templates explained by example.

Template talk page

In addition, the template talk page can be used to explain the template and its parameters. Preferably examples are given of template calls (put them in nowiki tags) and the results (put the template call without nowiki tags in the wikitext). In complicated cases, substitution can be very helpful in the explanation to demonstrate the working.

The talk page of course still offers to discuss the template after its documentation.

Templates for documentation

A template can help producing ".. gives .." without duplicating code. For example, using template:evd ( talk edit history links ), {{evd|t2|a|b}} gives:

"{{t2|a|b}}" gives "parameter 1 is "a", parameter 2 is "b"" [1]

However, the possibilities for passing wikitext code as parameter value are limited: a parameter value without nowiki tags cannot be used as unexpanded string, while one with nowiki tags cannot be expanded. See also mw:Extension:ExpandAfter#Example: nowiki.

See also

• w:Wikipedia:Template doc page pattern
• template:doctl ( talk edit history links )
• en:template:doctl ( talk edit history links )

Links to other help pages

Help contents

Meta | Wikinews | Wikipedia | Wikiquote | Wiktionary | commons: | mw: | b: | s: | mw:Manual | google

Versions of this help page (for other languages see below)

Meta | Wikinews | Wikipediahttp://en.wikipedia.org/Help:Template_documentation | Wikiquote | Wiktionary

What links here on Meta or from Meta | Wikipedia | MediaWiki

Reading

Go | Search | Stop words | URL | Namespace | Page name | Section

Backlinks | Link | Piped link | Interwiki link | Redirect | Category | Image page

Logging in and preferences

Logging in | Preferences | User style

Editing

Advanced editing | Editing FAQ | Edit toolbar | Export | Import | Shortcuts

Tracking changes

Recent changes (enhanced) | Related changes | Watching pages | Diff

Page history | Edit summary | User contributions | Minor edit | Patrolled edit

Style & formatting

Wikitext examples | Reference card | HTML in wikitext | List | Table | Sorting | Colors

Special input and output

Inputbox | Special characters | Displaying a formula | Images (uploads) | EasyTimeline

Advanced functioning

Template | Advanced templates | Parser function | ParserFunctions | Parameter default

Variable | Magic word | System message | Substitution | Array | Calculation

Page management

Starting a new page | Renaming (moving) a page | Protecting pages | Deleting a page

Special pages

Talk page | Testing | Sandbox | CentralNotice

Template:-