Template:Test case/doc

From Gentoo Wiki
Jump to: navigation, search
Note
This page is a template. It contains some standardized, often used text, which can be transcluded inside other pages.

As this template is widely used in our wiki, it may be protected in which case only staff members can change it. Use the discussion page to propose enhancements or fixes, or to voice your opinion.

This template is used to illustrate the proper (and maybe improper) usage of a template and its parameters on the template's /testcases subpage. It is a replacement for the {{Testcase}} template that avoids table wiki markup. (Illustrating template usage inside a table is problematic because the pipe character, |, tends to get interpreted as table markup in that context.)

If used to show incorrect usage, it's probably a good idea to collect those cases under a section heading like ===Incorrect===. (See, for example, the documentation of {{Package}}.)

Parameters

Parameter name Required? Default value Description
title Yes (n/a) Brief description of the testcase (e.g., "One anonymous parameter")
Anonymous parameter 1 Yes (n/a) Example wikicode (template call) inside a <nowiki> element.
Anonymous parameter 2 Yes (n/a) Same wikicode without <nowiki>.
Anonymous parameter 3 Yes (n/a) Same wikicode without <nowiki>, using "/sandbox" after the template name.
error No (n/a) Describes the error being illustrated in a test case showing incorrect usage.
code No (n/a) Can be set to pre to allow for multiline examples.
background-color No (n/a) Background color in the title bar (default explained below).
text-color No white Text color in the title bar.

While omitting the third anonymous parameter does not give an error, it would not allow editors to see how the sandbox version of the template compares to the main version. Please use all three parameters, even if there is currently no sandbox version of the template being documented.

The default value of background-color is usually #54487A, which matches the purple color scheme used throughout the wiki). However, if the parameter error is set to any string, then the default background color is #323, a purplish black, as seen in the testcases below.

The value of error is displayed in parentheses after title in the title bar, so it should be descriptive (not, for example, the word yes). If you have no better description of the error being illustrated, you can just use, for example, error=error.

Note
Avoid including links (or using templates that provide links) in the title parameter. The colors used by this template make such links very hard to see. (The background color can be changed using background, but this should be avoided for the sake of consistency. Note that the text-color parameter would not affect the color of a link.)

Usage

Typical:

{{Test case
|title=Descriptive title
|<nowiki>{{Template call}}</nowiki>
|        {{Template call}}
|{{Template/sandbox call}}
}}
{{Test case
|title=Descriptive title
|error=Brief description of error
|<nowiki>{{Template call}}</nowiki>
|        {{Template call}}
|{{Template/sandbox call}}
}}

All parameters:

{{Test case
|title=
|error=
|code=pre
|background-color=
|text-color=
|<nowiki>{{}}</nowiki>
|        {{}}
|{{/sandbox}}
}}

See the template's testcases:


Illustrating correct usage

These cases show how this template could be used to document proper use of the template {{Package}}.

The wikicode:

{{Test case
|title=One unnamed parameter
|<nowiki>{{Package|sys-apps/portage}}</nowiki>
|        {{Package|sys-apps/portage}}
|{{Package/sandbox|sys-apps/portage}}
}}

Results in:

One unnamed parameter
Wiki code
{{Package|sys-apps/portage}}
Main version
Sandbox version

Using the sandbox version (Test case/sandbox):

{{Test case/sandbox
|title=One unnamed parameter
|<nowiki>{{Package|sys-apps/portage}}</nowiki>
|        {{Package|sys-apps/portage}}
|{{Package/sandbox|sys-apps/portage}}
}}

Results in:

One unnamed parameter
Wiki code
{{Package|sys-apps/portage}}
Main version
Sandbox version

Illustrating incorrect usage

These cases show how this template could be used to document improper use of the template {{Package}}.

The wikicode:

{{Test case
|title=No parameter
|error=error message
|<nowiki>{{Package}}</nowiki>
|        {{Package}}
|{{Package/sandbox}}
}}

Results in:

No parameter (error message)
Wiki code
{{Package}}
Main version
{{Package template error}}
Parameter 1 not defined. For correct usage see Package template's documentation on the 1 parameter.
Sandbox version

Using the sandbox version (Test case/sandbox):

{{Test case/sandbox
|title=No parameter
|error=error message
|<nowiki>{{Package}}</nowiki>
|        {{Package}}
|{{Package/sandbox}}
}}

Results in:

No parameter (error message)
Wiki code
{{Package}}
Main version
{{Package template error}}
Parameter 1 not defined. For correct usage see Package template's documentation on the 1 parameter.
Sandbox version

Cases with multiline wikicode

Some templates are best illustrated with multiline sample wikicode (because that's how they are best used in practice). In such cases, the value of the first anonymous parameter will contain newlines. Here are some examples showing what this looks like. They show how the template {{InfoBox stack}} might be documented.

Notice how the newlines between the <nowiki> and </nowiki> tags have been turned into spaces in the resulting "Wiki code". This might be acceptable in some cases but not in others.

{{Clear}} is used here to fix formatting problems that arise when a test case involves right-floated content.

The wikicode:

{{Test case
|title=One unnamed parameter
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}

Results in:

One unnamed parameter
Wiki code
{{InfoBox stack | {{InfoBox homepage|http://www.samba.org|header=true}} }}
Main version
Resources
Sandbox version
Resources

Using the sandbox version (Test case/sandbox):

{{Test case/sandbox
|title=One unnamed parameter
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}

Results in:

One unnamed parameter
Wiki code
{{InfoBox stack | {{InfoBox homepage|http://www.samba.org|header=true}} }}
Main version
Resources
Sandbox version
Resources

Using code=pre

Newlines in the first anonymous parameter can be preserved if the code=pre is used, as in the following example that is otherwise identical to the previous one.

Notice that the resulting "Wiki code" is shown as a block of preformatted text (because the usual <code> element has been turned into a <pre> element). This is generally preferable to having the newlines replaced by spaces.

The wikicode:

{{Test case
|title=One unnamed parameter
|code=pre
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}

Results in:

One unnamed parameter
Wiki code
{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}
Main version
Resources
Sandbox version
Resources

Using the sandbox version (Test case/sandbox):

{{Test case/sandbox
|title=One unnamed parameter
|code=pre
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}

Results in:

One unnamed parameter
Wiki code
{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}
Main version
Resources
Sandbox version
Resources

See also