Help:Template documentation/ja

From Meta, a Wikimedia project coordination wiki
Jump to navigation Jump to search
This page is a translated version of the page Help:Template documentation and the translation is 2% complete.
MediaWiki ハンドブック: 目次読者編集者中間管理者システム管理者 +/-

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

There are different 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>...</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.

The include-part of the template page defines the way it works when transcluded or substituted, while the non-includeonly parts produce the page itself.

A typical template page could contain:

<includeonly><!--テンプレート名-->
definition content, possibly a tag for a category of pages that include the template</includeonly><noinclude>
<nowiki><translate nowrap><!--T:14--> definition content, possibly formatted, annotated, summarized</translate></nowiki>

explanation, examples, and tags for template categories (using the sortkey {{PAGENAME}})
</noinclude>

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

For example, for Template:T:

<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-documenting 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:template category|{{PAGENAME}}]]
</noinclude>

Here target means a category for pages using the template, and template cat 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: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.

Examples

Expansion demo templates can be used for live examples.

If a template contains a variable it can be useful if it has been written such that the value of the variable can be overridden by a parameter value, to demonstrate the effect of various values, using e.g.:

  • {{{namespace|{{NAMESPACE}}}}}
  • {{{pagename|{{PAGENAME}}}}}
  • {{{currentdow|{{CURRENTDOW}}}}}

This applies especially in the case of branching depending on the value of the variable.

See also


メディアウィキ・ユーザーズガイド - ヘルプ・ページ全部

一般的な利用法: 表示 | 検索 | 検索に使用できない単語 | URL | 名前空間 | ページ名 | セクション | リンク | リンク元 | パイプ付きリンク | 言語間リンク | リダイレクト | 変数 | カテゴリ | 画像ページ | 特別ページ
ログイン及びユーザー設定: ログイン | オプション | 外装の詳細設定
起稿・編集: ページの編集 | 新規ページの作成 | 画像/ファイル | 特殊文字 | 数式の書き方 | 表の作り方 | EasyTimeline | テンプレート | リダイレクト | ページの移動 | 編集用ショートカット | トークページ | 公開前のテスト | 関連ページの更新状況
改定追跡: 最近更新したページ | 拡張された最近更新したページ | リンク先の更新状況 | ウォッチリスト | 差分 | 履歴 | 要約欄 | ユーザの投稿記録 | 細部の編集 | 編集のパトロール

他プロジェクト: Wikibooks | Wikicommons | Wikinews | Wikipedia | Wikiquote | Wikisource | Wiktionary - Edit このテンプレートを編集

言語: