View source for Template:Dfn/doc

{{Documentation subpage}}
<!-- Categories and interwikis go at the bottom of this page. -->

==Usage==
This template applies the [[HTML element#Phrase elements|HTML phrase element]] <code>&lt;dfn&gt;</code> around the text given as the first parameter, the <var>term</var>, and, if the optional second <var>definition</var> parameter is present, applies a dotted underline (a common style throughout the Web for indicating a term with a definition feature) and a definition pop-up "[[tool tip]]" when cursor focus is on the term.

Without the second parameter, it does not do anything user-facing, and is just a form of meta-data that can be detected and acted upon by internal and external software (statistics-gathering bots, rich Web 2.0 applications, etc.), and can provide valuable contextual information to editors.

It is used as a meta-template by some other templates. When used by itself, its most common purpose would be around a term '''boldfaced''' in an article and immediately defined there such as a key piece of terminology introduced after the lead section.  [[WP:NOT#DICT|Wikipedia is not a dictionary]], so this template should not be used to draw metadata attention to everyday words, and is best suited in spots where there is a short definition or clarification of jargon that is important in the context.

(Tech detail: By using an internal {{tag|span}} with its own independent <code>title</code> attribute for tool tip fun, it sets this up in a way that does not violate the HTML 5 specification on the handing of the <code>title</code> attribute of {{tag|dfn|o}}, which is the exact term defined, not its definition.)

===Purpose and application===
This markup indicates that the text is the ''defining instance'' of that term (word, phrase, name, etc.) on the page in which it appears. Thus it should be used only once per term per page.

[[WP:NOT#DICT|Wikipedia is not a dictionary]], so this template should not be used to provide definitions for everyday words at all, and is best suited for short definition or clarification of jargon that is important in the context but unlikely to be fully understood by all of our general readership.  The template can be adapted to most directly editable cases in which the <code>&lt;dfn&gt;</code> element would be useful.

Because the <var>definition</var> parameter's content is [[WP:ACCESSIBILITY|not readily accessible]] to users of most if not all [[screen reader]] software, text-only browsers, mobile phone browsers, etc., the second parameter should never be used to provide information vital to understanding the article subject, only convenient or augmenting for those who can access it; vital information belongs in the main article prose.

This template should not be used for marking up [[MOS:GLOSSARIES|glossary]] entries or links to them; see {{tl|term}} and {{tl|glossary link}} instead, respectively. Likewise, this template should not be used to mark up the bold-faced article subject in the lead; [it is anticipated that] another template, [name forthcoming, probably Template:Subject], is [to be created to be] used for this purpose, including the needed bold-facing and [perhaps] other markup and metadata features.

This is [[Semantic HTML|semantic markup]], not simply presentational style, and has a particular, pre-defined meaning; do not misuse this template just to get its display effects. If the content being marked up is not suitable for the <code>&lt;dfn&gt;</code> element as defined by the W3C HTML specifications, then you should not use this template.

===Parameters===
There are two basic parameters, the mandatory first parameter, the <var>term</var>, and the optional second one, the <var>definition</var>:
:{{tlx|dfn|<var>term</var>}}
:{{tlx|dfn|<var>term</var>|<var>definition</var>}}

If the <var>definition</var> parameter is supplied and the reader's browser supports the functionality, moving browser focus to the term (e.g., hovering the mouse cursor over it, or in some browsers using keyboard navigation to tab to it) will change the cursor to the "help" version (usually a question mark) and bring up the definition text in a pop-up tool tip (or some other interface, as provided by the browser in question).  Without a second parameter, no such underlining and tool tip effects occur.

It is safest to explicitly number them, but this is only absolutely required if the content contains an equals sign somewhere:
:{{bxt|{{tnull|dfn|1{{=}}<var>term</var>|2{{=}}<var>definition</var>}}}}
:{{bxt|{{tnull|dfn|<var>term</var>|2{{=}}<var>definition</var>}}}} &ndash; this works if only the <var>definition</var> has a "=" in it.
:{{!bxt|{{tnull|dfn|1{{=}}<var>term</var>|<var>definition</var>}}}} &ndash; this fails; if parameter 1 is numbered, so must be parameter 2

If no <var>definition</var> is provided, the template is invisible:
:{{tnull|dfn|ecdysis|moulting of the exoskeleton}}&nbsp; results in:&nbsp; {{dfn|ecdysis|moulting of the exoskeleton}}
:<code><nowiki>{{dfn|ecdysis}}, the moulting of the exoskeleton</nowiki></code>&nbsp; results in:&nbsp; {{dfn|ecdysis}}, the moulting of the exoskeleton
:<code><nowiki>[[Ecdysis|{{dfn|ecdysis}}]]</nowiki></code>&nbsp; results in:&nbsp; [[Ecdysis|{{dfn|ecdysis}}]]

The "invisible" second and third cases won't be noticed by casual readers, but can still be detected and acted upon by internal and external software (statistics-gathering bots, rich Web 2.0 applications, etc.), and can provide valuable contextual information to editors.

The <var>definition</var> parameter is most commonly omitted when the text following the term provides the defining content inline in the prose, or when the term is linked to an explanation elsewhere, as shown above. A common case of this is when an article provides a bold-faced term and an explanation of it, often at the start of a paragraph or section, indicating a significant side-topic in the article, subordinate to the main article subject boldfaced in the lead.
====Other optional parameters====

*{{para|title|<var>exact, plaintext term being defined</var>}} &ndash; used a) when the content in the first parameter (term) contains any wikimarkup or HTML; or b) when the term being defined is actually slightly different from (i.e. more precise than) the marked up content; the true term being defined goes in this parameter. Any double-quotation mark (<code>"</code>) must be escaped, as <code>&amp;quot;</code>.<br />Real-world example: showing imprecise term in text and its precise official name as the {{para|title}}, with escaped quotation marks: {{tnull|dfn|Mac OS X Lion|title{{=}}Mac OS X 10.7 &amp;quot;Lion&amp;quot;}}, which results in: {{dfn|Mac OS X Lion|title=Mac OS X 10.7 &quot;Lion&quot;}} (hover over it to see that tooltip is different from base content)<br />
*{{para|id|<var>an_ID</var>}} &ndash; an ID (no spaces, must begin with alphabetic letter) for #linking and possibly other purposes
*{{para|style|<var>arbitrary:css;</var>}} &ndash; CSS directives for custom-styling the instance
*{{para|class|<var>css_class</var>}} &ndash; a CSS class or classes (separated by spaces not commas if more than one)

===Problem characters===
If there would be a "<code>=</code>" (equals sign) in the <var>term</var>, either a) <strong>both</strong> unnamed parameters if present must explicitly be numbered:
:{{tlx|dfn|1{{=}}E{{=}}MC<sup>2</sup>|2{{=}}Mass–energy equivalence}} which results in:&nbsp; {{dfn|1=E=MC<sup>2</sup>|2=Mass–energy equivalence}}<!--It SHOULD be the case that only the first parameter need be named, but this is not true for some reason with this template; test case code {{dfn|1=term|definition}} results in an epic FAIL.-->
or b) the character itself can be escaped as the HTML [[character entity reference]] code <code>&amp;#61;</code> or the {{tlx|1==}} template:
:{{tlx|dfn|E&amp;#61;MC<sup>2</sup>|Mass–energy equivalence}} which results in:&nbsp; {{dfn|E&#61;MC<sup>2</sup>|Mass-energy equivalence}}
:{{tlx|dfn|E<nowiki>{{=}}</nowiki>MC<sup>2</sup>|Mass–energy equivalence|title{{=}}E{{=}}MC&sup2;}} which results in:&nbsp;{{dfn|E{{=}}MC<sup>2</sup>|Mass–energy equivalence|title=E=MC&sup2;}}

No other characters are known to be problematic in the <var>term</var>.

For technical reasons, the second parameter ({{para|2}}, the <var>definition</var>) is more "brittle".  The equals sign (<code>=</code>) <strong>must</strong> be escaped by one of the techniques just mentioned, {{em|and}} the standard keyboard (straight, not curly) double-quotation mark (<code>"</code>) <strong>must</strong> also be escaped, no matter what, as <code>&amp;quot;</code> or <code>&amp;#34;</code>. This double-quote <strong>must</strong> also be escaped the same way in the {{para|title}} parameter:
:{{tlx|dfn|1{{=}}ACT UP's slogan|2{{=}}&amp;quot;Silence {{=}} Death&amp;quot;}} which results in:&nbsp; {{dfn|1=ACT UP's slogan|2=&quot;Silence = Death&quot;}}
:{{tlx|dfn|ACT UP's slogan|&amp;quot;Silence <nowiki>{{=}}</nowiki> Death&amp;quot;}} which results in:&nbsp; {{dfn|ACT UP's slogan|&quot;Silence {{=}} Death&quot;}}
:{{tlx|dfn|ACT UP's slogan|&amp;quot;Silence &amp;#61; Death&amp;quot;}} which results in:&nbsp; {{dfn|ACT UP's slogan|&quot;Silence &#61; Death&quot;}}
:{{tlx|dfn|"Teenage Wasteland"<nowiki>{{sic}}</nowiki>|title{{=}}&amp;quot;Baba O'Riley&amp;quot;}} which results in:&nbsp; {{dfn|"Teenage Wasteland"{{sic}}|title=&quot;Baba O'Riley&quot;}}

=== Links and markup ===
Linking and wikimarkup should be done {{em|outside}} the template when possible:
* Right: <code>{{bxt|<nowiki>'''[[Foo|{{dfn|Foo}}]]'''</nowiki>}}</code>
* Wrong: <code>{{!bxt|<nowiki>{{dfn|'''[[Foo]]'''}}</nowiki>}}</code>

The <var>term</var> content in the first parameter {{em|can}} be marked up with wikimarkup or HTML, at the <code>inline</code> level, such as italics, superscript other text-formatting code (versus <code>block</code>-level elements, such as paragraphs, tables, block quotations, and so on), if absolutely necessary. {{em|If this is done, the {{para|title}} parameter {{strong|must}} contain the un-marked-up, plaintext term.}} Example: The displayed text (first parameter) uses superscript markup, for accessibility reasons, while the real plaintext in the title parameter uses a Unicode character entity (doesn't count as wikimarkup) for a superscripted 2, which is actually more correct but may not display properly on older systems:
:<code><nowiki>{{dfn|1=E=MC<sup>2</sup>|title=E=MC&amp;sup2;}}</nowiki></code>
yields:
:{{dfn|1=E=MC<sup>2</sup>|title=E=MC&sup2;}}
while this:
:<code><nowiki>{{dfn|1=E=MC<sup>2</sup>|2=Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC&amp;sup2;}}</nowiki></code>
gives:
:{{dfn|1=E=MC<sup>2</sup>|2=Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC&sup2;}}
Note that in the first case, the mouse hover tooltip is the Unicode version of the <var>term</var>, as given in the {{para|title}}, while in the latter it is the <var>definition</var> given in the {{para|2}} parameter.

Linked version:
:<code>[<nowiki />[Mass–energy equivalence|{{tnull|dfn|1{{=}}E{{=}}MC<sup>2</sup>|2{{=}}Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title{{=}}E{{=}}MC&amp;sup2;}}]<nowiki />]</code>
gives:
:[[Mass–energy equivalence|{{dfn|1=E=MC<sup>2</sup>|2=Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC&sup2;}}]]
It still has a dotted underline indicating a tooltip, but is also a bluelink. Mouse hovering shows both the tooltip and, in the status bar, the target URL, in browsers that support these features.

Link inside the {{tnull|dfn}}:
:{{tnull|dfn|1{{=}}[<nowiki />[Mass–energy equivalence{{!}}E{{=}}MC<sup>2</sup>]<nowiki />]|2{{=}}Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title{{=}}E{{=}}MC&amp;sup2;}}
results in:
:{{dfn|1=[[Mass–energy equivalence|E=MC<sup>2</sup>]]|2=Mass&ndash;energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC&sup2;}}
This doesn't mess up the page, but the <var>definition</var> fails and there's no tooltip cursor, meanwhile the markup is hard for other editors to understand anyway so it is {{strongbad|deprecated}}.

Links, HTML, wikimarkup, and other markup <strong>cannot</strong> be applied to content in the {{para|2}} (<var>definition</var>) parameter, nor in a {{para|title}} parameter, only plain text and character entity references ("&-codes", like <code>&amp;quot;</code>).

=== Anchors and id ===

Example where an {{tl|anchor}} is added. Because <code>2=</code> is missing, no text appears when the mouse hovers over the newly defined term "<code>open set</code>".

:<code><nowiki>An {{em|{{dfn|1=open set|id=dfn-anchorname open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#dfn-anchorname open set|open set]].</nowiki></code>

results in:

:An {{em|{{dfn|1=open set|id=dfn-anchorname open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#dfn-anchorname open set|open set]].

Contrast to the alternative that uses the {{tl|visible anchor}} template:

:<code><nowiki>An {{em|{{visible anchor|open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#open set|open set]].</nowiki></code>

which results in:

:An {{em|{{visible anchor|open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#open set|open set]].

Note that clicking on the "[[#open set|open set]]" link results in the text being highlighted.

== See also ==
* {{tl|dfni}} is a wrapper for {{tl|dfn}} that applies italics for [[MOS:TECHNICAL]] uses
* Related to {{tl|glossary link}}, a variant for use with [[MOS:GLOSSARIES|stand-alone and embedded glossaries]]
* {{tl|abbr}}
* {{tl|tooltip}}
* Not to be confused with {{tl|defn}} (but see the related glossary templates {{tl|glossary}}, {{tl|glossary end}} and especially {{tl|term}}; the last of these also makes use of the <code>dfn</code> HTML element)

<includeonly>{{Sandbox other||
<!-- Categories and interwikis go here: -->
[[Category:Wikipedia XHTML tag-replacing templates|{{PAGENAME}}]]
[[Category:Semantic markup templates|{{PAGENAME}}]]
}}</includeonly>