Wikipedia:Manual of Style/Glossaries
 | This page in a nutshell: Use proper markup for glossaries. Avoid in-article glossaries unless both necessary and conscise. Glossary list articles should be created in a consistent manner. |
HTML (and XHTML) provide rich semantics for producing glossaries and lists similar to glossaries. (See HTML elements for more information on definition lists, terms and definitions.). The guidelines below show how to use these elements to create Wikipedia glossaries that are accessible and which can be parsed and re-used in various ways by third party applications.
Terminology
The following terms and definitions will be used in this guideline: '{{{1}}}'
- glossary
- Any list of terms and definitions (or similarly formatted list, such as a list of airplanes and their serial numbers, etc.)
- dt|definition list (DL)
- The [X]HTML structure into which the glossary is formatted. It contains the terms and their definitions (entries). The definition list is marked up with {{gloss}} and {{glossend}}, which use the
<dl>...</dl>HTML element. - term, or definition list term (DT)
- The term to be defined (or term-like item to receive something similar to a defintion). The term is marked up with a prepended
;character in in-article glossaries, or with {{term}} in glossary list articles, both of which use the<dt>...</dt>HTML element. - definition, or definition list definition (DD)
- The definition of the term (or definition-like material relating to the term-like item). The definition is marked up with a prepended
:character, which translates into the<dd>...</dd>HTML element. - entry
- A term and its definition(s). The definition list (and thus the glossary) consists of entries.
General guidelines
- The glossary must be marked up as a series of terms and definitions within definition list structures, not simply free-form bullet items, or headings and text. Different methods of doing this, for different contexts, are provided in the sections below.
- The glossary should not contain every-day words, nor terms not specific to the field in question. For example, warp and weft are general weaving terms and are not specific to underwater basketweaving, a contrived example; these terms should thus not appear in a glossary of underwater basketweaving terms, unless their entries provide specific information on how the terms apply to this particular type of weaving.
- Terms should not begin with a capital letter unless normally capitalized in the middle of a sentence. General Wikipedia style is to always begin headings and list items (and things that look like them) with a capital letter, but this is an exception, as doing so may introduce reader-confusing ambiguities about the spelling of the terms being defined.
- Definitions of terms should begin with a capital letter, and end with a period (full stop), even if not full sentences.
- A glossary should not be created simply to provide bare dictionary definitions. The purpose of a glossary in an encyclopedia article is to provide an encyclopedic view of terminology – not simply a definition, but an explanation. If all that is needed is a simple definition, then define the term, e.g. with a parenthetical, at its first occurrence in the prose in any relevant article, and/or link to an article about that term and its usage in that context if one exists.
- A term with multiple definitions should have those definitions begin with numbers to indicate this fact. The numbering must be done by hand e.g.,
1. First definition here.Using wikimarkup's#-list feature will cause definitions to be indented, which will not match the rest of the glossary.
Stand-alone glossary list articles
Glossary articles in Wikipedia are a special form of list article. All of the guidelines applicable to stand-alone lists apply to glossary articles, but there are also other concerns specific to glossaries.
The preferred method of creating a glossary in Wikipedia is to use templates to lay out the structure of the glossary, to make the entries individually editable, and to provide rich, semantic markup:
==Glossary of article subject terms==
Optional introductory text.</nowiki>
{{gloss}}
{{term|term 1}}
:This is the definition of term 1.
{{term|term 2}}
:<p>1. This is part of the first definition of term 2.</p><p>This is more of the first definition of term 2.</p>
:2. This is the second definition of term 2.
{{glossend}}
This renders as the following (other than the heading will actually be a real heading):
'{{{1}}}'
<dt class="glossary " id="term 1" style="margin-top: 0.4em;">term1
- This is the definition of term 1.
<dt class="glossary " id="term 2" style="margin-top: 0.4em;">term2
1. This is part of the first definition of term 2.
This is more of the first definition of term 2.
- 2. This is the second definition of term 2.
This method correctly places the terms and definitions in a definition list structure, and prevents the creation of redundant definition lists. (See HTML elements for more information on definition lists.)
See the documentation of Template:term for instructions on how to style (italicize, etc.) or add links to terms, and how to provide custom link anchors for them.
In-article glossaries
A glossary included within an article may occasionally be helpful for readers, either to understand an article's terminology better, to learn more about the terminology used in a field covered by the article, or both. Some guidelines on including glossaries within articles, in addition to the general guidelines above:
- The glossary must be its own section, with a heading identifying it as a glossary. The title of this section should conform to the article naming conventions, since the glossary could grow over time and eventually need to be split off into its own article. Example:
==Glossary of underwater basketweaving terms==) - If the glossary would be 5 terms or fewer, it is probably better to define the terms concisely in context in the prose of the article, instead of using a glossary.
- If the glossary would be 25 terms or more, it is probably better to create a stand-alone glossary list article.
- In-article glossaries should not use subheadings inside them (e.g. for letters of the alphabet), and should simply be editable as a single block.
The preferred method of creating an in-article glossary is to use templates to lay out the structure of the glossary, as shown above, under a single clearly-labeled heading:
==Glossary of article subject terms==
Optional introductory text.</nowiki>
{{gloss}}
;term 1
:This is the definition of term 1.
;term 2
:<p>1. This is part of the first definition of term 2.</p><p>This is more of the first definition of term 2.</p>
:2. This is the second definition of term 2.
{{glossend}}
This renders as the following (other than the heading will actually be a real heading):
'{{{1}}}'
- term 1
- This is the definition of term 1.
- term 2
1. This is part of the first definition of term 2.
This is more of the first definition of term 2.
- 2. This is the second definition of term 2.
Please note again that a multi-paragraph definition must have explicitly defined paragraphs, and there must not be a linebreak between the paragraphs.
Important: See the "Technical notes" section for information on how to properly format multi-paragraph definitions.
If it is desired to make the entries linkable, use {{anchors}} to provide one or more link anchors for them; they will then be linkable just like headings:
;shortstop{{anchors|shortstop|short-stop|short stop|Shortstop}}<nowiki></code><br />
<code><nowiki>:This is the definition<nowiki></code>
A simpler, sloppier method of creating an in-article glossary looks like this:
<code><nowiki>==Glossary of article subject terms==
Optional introductory text.</nowiki>
;term 1
:This is the definition of term 1.
;term 2
:<p>1. This is part of the first definition of term 2.</p><p>This is more of the first definition of term 2.</p>
:2. This is the second definition of term 2.
This renders as the following (other than the heading will actually be a real heading):
- term 1
- This is the definition of term 1.
- term 2
1. This is part of the first definition of term 2.
This is more of the first definition of term 2.
- 2. This is the second definition of term 2.
This form is not recommended, as insertion of blank lines between entries (common for code readability) will cause the MediaWiki software to generate redundant definition list code around each entry. It is therefore preferable to use the {{gloss}} and {{glossend}} templates to bracket the glossary.
Technical notes
If a single definition requires multiple paragraphs, it is necessary to specify the paragraphs explicitly with
<p>...</p>. Do not simply create a second definition line for a second paragraph, as this indicates two separate definitions, not a multi-paragraph definition.Due to limitations of the MediaWiki software, the paragraphs must not be separated by a newline either inside or outside of the paragraph. This example does not work:
;term 1:<p>This is part of the definition of term 1.</p><p>This is more of the definition of term 1.</p>And neither does this one:
;term 1:<p>This is part of the definition of term 1.</nowiki><p>This is more of the definition of term 1.- A blank line between entries (i.e. between the definition of one entry and the term of the next entry) to space the entries further apart is fine, and will not affect the semantics of the code, so long as {{gloss}} and {{glossend}} surround all of the entries as a block.
- Forthcoming: When a known MediaWiki bug is fixed, so that the [X]HTML element
<dfn>is properly supported, the {{term}} template will also identify the term as the defining instance of its usage in the page.
Actual HTML structure
For the technically-minded, the following is an explanation of the actual XHTML markup that will be rendered from these templates by the reader's browser (not counting various classes and other details that are supplied automatically by the MediaWiki web application, nor the "[edit]" buttons). The code validates, is structurally well-formed, and semantically correct:
Wikicode:
==Heading==
{{gloss}}
{{term|term 1}}
:Definition 1.
{{term|term 2}}
:<p>1. Definition 2a part 1.</p><p>Definition 2a part 2.</p>
:2. Definition 2b.
{{glossend}}
HTML represented:
<h1>Heading</h1>
<dl class="glossary">
<dt class="glossary" id="term 1" name="term 1">term 1</dt>
<dd>Definition 1.</dd>
<dt class="glossary" id="term 2" name="term 2">term 2</dt>
<dd><p>1. Definition 2a part 1.</p><p>Definition 2a part 2.</p></dd>
<dd>2. Definition 2b.</dd>
</dl>