Template:Glossary/doc: Difference between revisions
RogueScholar (talk | contribs) (Import template documentation from enwiki and extensively rewrite to make applicable to editors on Kodi Wiki) |
RogueScholar (talk | contribs) (Add full syntax counterpart to basic usage example) |
||
(One intermediate revision by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Documentation subpage}} | {{Documentation subpage}} | ||
== Usage == | == Usage == | ||
The {{ | The '''{{Tlx|Glossary}}''' template is used with '''{{Tlx|Glossary end}}''' to explicitly bracket a glossary or glossary-like description list (also called a definition list or association list). This is a good practice anywhere lists are used for defining large numbers of technical terms. Together, the template pair invoke the {{Tag|dl|o}} ''description list'' HTML5 element. | ||
Incidentally, they also prevent the MediaWiki parser engine from creating redundant definition list code ({{Tag|dl|p}}) around terms and definitions if they have blank lines between them, as they often do, especially in non-structured glossaries. | |||
Typical | === Basic format === | ||
Typical use most often resembles: | |||
<div class="nowrap" style="background-color: #eaecf0; border: 2px solid #a2a9b1; line-height: 1.3; margin: 0 0 0.5em 2.5em; max-width: 20vmax; overflow-x: hidden; padding: 0.5em 1em; white-space: pre-wrap; word-wrap: break-word;"><span class="example example-bold" style="color: #184020; font-weight: 700;">{{Tlx|Glossary}}</span><br /><span class="example" style="color: #184020;">{{Tlx|Term|term=<var>glossary term</var>}}</span><br /><span class="example" style="color: #184020;">{{Tlx|Defn|defn=<var>Definition.</var>}}</span><br /><span class="example" style="color: #184020;">{{Tlx|Glossary end}}</span></div> | |||
…which generates the output… | |||
{{Glossary}} | |||
{{Term|term=glossary term}} | |||
{{Defn|defn=Definition.}} | |||
{{Glossary end}} | |||
=== Full syntax === | |||
The following demonstrates a use case with all available parameters in use: | |||
<div class="nowrap" style="background-color: #eaecf0; border: 2px solid #a2a9b1; line-height: 1.3; margin: 0 0 0.5em 2.5em; max-width: 67vmax; overflow-x: hidden; padding: 0.5em 1em; white-space: pre-wrap; word-wrap: break-word;"><span class="example example-bold" style="color: #184020; font: 600 0.875rem/1.3 monospace;">'''<nowiki>{{</nowiki>[[Template:Glossary|Glossary]]'''|id=<var>api_19</var>|style=<var>font-family: Georgia;</var>|class=<var>nowrap</var>'''<nowiki>}}</nowiki>'''</span><br /><span class="example" style="color: #184020; font-weight: 500;">{{Tlx|Term|term=<var>glossary term</var>|content=<var><nowiki>'''term'''</nowiki></var>|id=<var>id</var>|noid=<var>n</var>|style=<var>text-decoration: underline #000 double 1px;</var>|class=<var>nowrap</var>}}</span><br /><span class="example" style="color: #184020; font-weight: 500;">{{Tlx|Term|term=<var>synonym</var>|content=<var><nowiki>'''synonym'''</nowiki></var>|multi=<var>y</var>|class=<var>nowrap</var>}}</span><br /><span class="example" style="color: #184020; font-weight: 500;">{{Tlx|Defn|defn=<var>First definition.</var>|num=<var>1</var>|term=<var>id</var>|id=<var>def1</var>|style=<var>font-family: sans-serif;</var>|class=<var>nowrap</var>}}</span><br /><span class="example" style="color: #184020; font-weight: 500;">{{Tlx|Defn|defn=<var>Second definition.</var>|num=<var>2</var>|term=<var>id</var>|id=<var>def2</var>|style=<var>font-family: sans-serif;</var>|class=<var>nowrap</var>}}</span><br /><span class="example" style="color: #184020; font-weight: 500;">{{Tlx|Glossary end}}</span></div> | |||
…thereby producing the following… | |||
{{Glossary|id=api_19|style=font-family: Georgia;|class=nowrap}} | |||
{{Term|term=glossary term|content='''term'''|id=id|noid=n|style=text-decoration: underline #000 double 1px;|class=nowrap}} | |||
{{Term|term=synonym|content='''synonym'''|multi=y|class=nowrap}} | |||
{{Defn|defn=First definition.|num=1|term=id|id=def1|style=font-family: sans-serif;|class=nowrap}} | |||
{{Defn|defn=Second definition.|num=2|term=id|id=def2|style=font-family: sans-serif;|class=nowrap}} | |||
{{Glossary end}} | |||
== Parameters == | |||
* {{Para|id}} can be used to assign a one-word ID name to the glossary. This can be used as a <code>#<var>id</var></code> link target, and could have other metadata uses. | * {{Para|id}} can be used to assign a one-word ID name to the glossary. This can be used as a <code>#<var>id</var></code> link target, and could have other metadata uses. | ||
* {{Para|style}} will pass CSS styling on to the {{Tag|dl|o}} element. This styles the definition list itself, as a container, not the individual terms and definitions with it. ''There is rarely any reason to do this.'' | * {{Para|style}} will pass CSS styling on to the {{Tag|dl|o}} element. This styles the definition list itself, as a container, not the individual terms and definitions with it. ''There is rarely any reason to do this.'' | ||
* {{Para|class}} will pass one or more space-delimited CSS classes on to the {{Tag|dl|o}} element, in addition to the automatically included class <code>glossary</code>. ''There is rarely any reason to do this, either.'' | * {{Para|class}} will pass one or more space-delimited CSS classes on to the {{Tag|dl|o}} element, in addition to the automatically included class <code>glossary</code>. ''There is rarely any reason to do this, either.'' | ||
== Examples == | |||
This shows both a very simple then a rather complex instance in a structured glossary (including an entry with a block quotation): | This shows both a very simple then a rather complex instance in a structured glossary (including an entry with a block quotation): | ||
{| style="border: 1px solid black; border-collapse: collapse;" | {| style="border: 1px solid black; border-collapse: collapse; text-align: left;" | ||
| style="vertical-align: top;" | <syntaxhighlight | | style="vertical-align: top;" | <syntaxhighlight highlight="2,12"> | ||
== A–M == | == A–M == | ||
{{Glossary}} | {{Glossary}} | ||
{{Term|1=applesnorkel}} | {{Term|1=applesnorkel}} | ||
{{Defn|1=Definition of first term.}} | {{Defn|1=Definition of first term.}} | ||
Line 31: | Line 42: | ||
{{Term|term=arglefarst|content=''arglefarst''{{Anchor|argle-farst|argle farst}}}} | {{Term|term=arglefarst|content=''arglefarst''{{Anchor|argle-farst|argle farst}}}} | ||
{{Defn|num=1|defn=Beginning of first definition of second term | {{Defn|num=1|defn=Beginning of first definition of second term | ||
<blockquote class="templatequote glossary-blockquote" style=" | <blockquote class="templatequote glossary-blockquote" style="font: oblique small-caps 500 1.05em/1.4 Georgia, serif; margin: 0 0 -1.35em; padding: 0 0 1.2em 3em;">Block Quotation In First Definition Of Second Term.</blockquote> | ||
Conclusion of first definition of second term. | <span style="margin-left: 19px;">Conclusion of first definition of second term.</span> | ||
}} | }} | ||
{{Defn|num=2|defn=Second definition of second term.}} | {{Defn|num=2|defn=Second definition of second term.}} | ||
{{Glossary end}} | {{Glossary end}} | ||
</syntaxhighlight> | </syntaxhighlight> | ||
|- style="border-top: 4px dashed darkslategray;" | |- style="border-top: 4px dashed darkslategray;" | ||
| style="vertical-align: top;" | <div style="padding-left: 3em; padding-right: 1em | | style="vertical-align: top;" | <div style="padding-left: 3em; padding-right: 1em;"> | ||
<div style=" | <div style="background: none; border-bottom: 1px solid #aaa; color: #000; font: 1.5em/1.3 Georgia, 'Times New Roman', serif; margin-bottom: 0.25em; margin-top: 1em; padding: 0; page-break-after: avoid;">A–M</div> | ||
{{Glossary}} | {{Glossary}} | ||
{{Term|applesnorkel}} | {{Term|applesnorkel}} | ||
{{Defn|1=Definition of first term.}} | {{Defn|1=Definition of first term.}} | ||
{{Term|term=arglefarst|content=''arglefarst''{{Anchor|argle-farst|argle farst}}}} | {{Term|term=arglefarst|content=''arglefarst''{{Anchor|argle-farst|argle farst}}}} | ||
{{Defn|num=1|defn=Beginning of first definition of second term | {{Defn|num=1|defn=Beginning of first definition of second term<blockquote class="templatequote glossary-blockquote" style="font: oblique small-caps 500 1.05em/1.4 Georgia, serif; margin: 0 0 -1.35em; padding: 0 0 1.2em 3em;">Block Quotation In First Definition Of Second Term.</blockquote><span style="margin-left: 19px;">Conclusion of first definition of second term.</span>}} | ||
<blockquote class="templatequote glossary-blockquote" style=" | |||
Conclusion of first definition of second term. | |||
}} | |||
{{Defn|num=2|defn=Second definition of second term.}} | {{Defn|num=2|defn=Second definition of second term.}} | ||
{{Glossary end}} | {{Glossary end}} | ||
</div> | </div> | ||
|} | |} | ||
== Scope == | |||
This family of templates, like the underlying definition list code, is <em>primarily</em> intended for definitional uses, but can have other applications. The ''[ | This family of templates, like the underlying definition list code, is <em>primarily</em> intended for definitional uses, but can have other applications. The ''[https://www.w3.org/TR/WCAG21/ Web Content Accessibility Guidelines (WCAG) 2.1]'' and the ''[https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element HTML 5.01 Specification]'' say: | ||
<blockquote> | <blockquote> | ||
The '''{{Red|dl}}''' element represents an ''association list'' consisting of … name-value groups (a description list). … Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data. Thus, when advertising a product, one might use a definition list: | |||
{{Glossary}} | {{Glossary}} | ||
{{Term|Lower cost}} | {{Term|Lower cost}} | ||
Line 68: | Line 73: | ||
{{Term|Safe for kids}} | {{Term|Safe for kids}} | ||
{{Defn|You can leave your kids alone in a room with this product and they won't get hurt (not a guarantee).}} | {{Defn|You can leave your kids alone in a room with this product and they won't get hurt (not a guarantee).}} | ||
{{Glossary end}}</blockquote> | {{Glossary end}} | ||
</blockquote> | |||
Accordingly, editors should feel free to use definition list markup as an alternative to bulleted or numbered lists when the material is well-suited to that style of presentation. | |||
== See also == | |||
* {{Tl|Glossary end}} | |||
* {{Tl|Term}} | |||
* {{Tl|Defn}} | |||
<includeonly><!-- CATEGORIES HERE, THANKS --> | |||
[[Category:Definition list templates]] | [[Category:Definition list templates]] | ||
[[Category:Glossary templates]]</includeonly> | [[Category:Glossary templates]]</includeonly><noinclude> | ||
[[Category:Template documentation pages]]</noinclude> |
Latest revision as of 10:45, 27 August 2022
Usage
The {{Glossary}} template is used with {{Glossary end}} to explicitly bracket a glossary or glossary-like description list (also called a definition list or association list). This is a good practice anywhere lists are used for defining large numbers of technical terms. Together, the template pair invoke the <dl>
description list HTML5 element.
Incidentally, they also prevent the MediaWiki parser engine from creating redundant definition list code (<dl>...</dl>
) around terms and definitions if they have blank lines between them, as they often do, especially in non-structured glossaries.
Basic format
Typical use most often resembles:
…which generates the output…
- glossary term
- Definition.
Full syntax
The following demonstrates a use case with all available parameters in use:
…thereby producing the following…
- term
- synonym
- 1. First definition.
- 2. Second definition.
Parameters
|id=
can be used to assign a one-word ID name to the glossary. This can be used as a#id
link target, and could have other metadata uses.|style=
will pass CSS styling on to the<dl>
element. This styles the definition list itself, as a container, not the individual terms and definitions with it. There is rarely any reason to do this.|class=
will pass one or more space-delimited CSS classes on to the<dl>
element, in addition to the automatically included classglossary
. There is rarely any reason to do this, either.
Examples
This shows both a very simple then a rather complex instance in a structured glossary (including an entry with a block quotation):
== A–M == {{Glossary}} {{Term|1=applesnorkel}} {{Defn|1=Definition of first term.}} {{Term|term=arglefarst|content=''arglefarst''{{Anchor|argle-farst|argle farst}}}} {{Defn|num=1|defn=Beginning of first definition of second term <blockquote class="templatequote glossary-blockquote" style="font: oblique small-caps 500 1.05em/1.4 Georgia, serif; margin: 0 0 -1.35em; padding: 0 0 1.2em 3em;">Block Quotation In First Definition Of Second Term.</blockquote> <span style="margin-left: 19px;">Conclusion of first definition of second term.</span> }} {{Defn|num=2|defn=Second definition of second term.}} {{Glossary end}} |
A–M
|
Scope
This family of templates, like the underlying definition list code, is primarily intended for definitional uses, but can have other applications. The Web Content Accessibility Guidelines (WCAG) 2.1 and the HTML 5.01 Specification say:
The dl element represents an association list consisting of … name-value groups (a description list). … Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data. Thus, when advertising a product, one might use a definition list:
- Lower cost
- The new version of this product costs significantly less than the previous one!
- Easier to use
- We've changed the product so that it's much easier to use!
- Safe for kids
- You can leave your kids alone in a room with this product and they won't get hurt (not a guarantee).
Accordingly, editors should feel free to use definition list markup as an alternative to bulleted or numbered lists when the material is well-suited to that style of presentation.
See also
- {{Glossary end}}
- {{Term}}
- {{Defn}}