Wikipedia:Manual of Style/Glossaries

From Wikipedia, the free encyclopedia
Jump to: navigation, search

On Wikipedia, a glossary is a special kind of list. Each glossary is an alphabetically arranged list of a subject's terms, with definitions. Each term is followed by one or more explanatory (encyclopedia-style) definitions. (For example, see Glossary of architecture).

In order to explain jargon for Wikipedia's broad audience, each of its glossaries contains a working vocabulary and definitions for important concepts for a given subject area. A glossary usually includes a field's technical terms, jargon, idioms, and metaphors.

Glossaries can be stand-alone list articles or embedded lists in sections of articles. Stand-alone glossaries are typically titled "Glossary of subject terms". A glossary within an article usually starts with a heading with the title "Glossary".

Terminology[edit]

Every article on Wikipedia with a title in the form "Glossary of subject terms" or similar is such a glossary, as are the glossary sections inside some articles. These are distinct from outlines, which are titled in the form "Outline of subject" and may also include definitions, but are organized as a hierarchy and use their own style of formatting not covered in this guideline. Glossary formatting, however, is not limited to only glossaries in the traditional sense. The underlying HTML description list markup is intended for groups of "terms and definitions, metadata topics and values, questions and answers, or any other groups of name–value data".[1]

The following terms are used consistently throughout this guideline:

glossary
A list of individual entries, each consisting of a one-word or longer term with one or more definitions. Glossaries are subject to all of the same rules (e.g. Wikipedia:Verifiability, and Wikipedia:Neutral point of view) as other content on Wikipedia.
list
A stand-alone list article or a list embedded in an article, consisting of entries in alphabetical order, and in one of the prescribed styles. The differences, for glossary-writing purposes, between stand-alone and embedded are covered below.
entry
A discrete concept that can be unambiguously named with a term and described or otherwise addressed with a definition.
term
A name or label for an entry, distinguishable from other entries. Usually there is only one term, though spelling variants and the like may sometimes result in multiple terms per entry. Like everything else on Wikipedia, the existence of the term must be verifiable.
definition
Prose that addresses the term of the entry in an encyclopedically descriptive manner. While some definitions may be dictionary-like (e.g. for simple concepts, or entries for which insufficient reliable sources have been found to provide more detail yet), an entire glossary of such definitions is not appropriate on Wikipedia and is likely to be moved to Wiktionary. There are often two or more definitions per term. Definitions longer than a short paragraph may indicate a need for an article (or article section) about the topic of the term and a link to it that from the glossary definition, lieu of an a definition that in-depth being included in the glossary itself).
style
The three glossary format styles to choose from are template-structured, bullet-style, and subheading-style. They are mutually exclusive. (By the way, this glossary you are reading right now in this Terminology section is template-structured.)

Glossary formatting styles[edit]

There are three styles to choose from when creating a glossary: template-structured, bullet-style, and subheading-style.

Template-structured[edit]

There is a special set of templates used for formatting glossary content. The templates are:

  • {{gloss}} – this template is used at the beginning of a block of glossary entries
  • {{term}} – this template sets the size and font style (bold) for each term
  • {{defn}} – this template provides the formatting for the term's definition prose.
  • {{glossend}} – this template ends the block of glossary entries

Nearly all stand-alone, and most embedded, glossaries are good candidates for the template-structured format. Here's what the format looks like:

==A–M==

Optional introductory text.

{{gloss}}
{{term|1=term 1}}
{{defn|1=Definition of term 1}}
{{term|1=term 2}}
{{defn|no=1 |1=First definition of term 2.}}
{{defn|no=2 |1=Second definition of term 2.}}
{{glossend}}

A–M

Optional introductory text.

term 1
Definition of term 1.
term 2
1.  First definition of term 2.
2.  Second definition of term 2.

This formatting style produces cleaner and richer XHTML output from Wikipedia's MediaWiki software engine, and uses standard HTML elements specifically intended for glossary markup. It provides many benefits, and the syntax does not take long to learn. Glossaries using this style:

Are more accessible to those using screen readers, which is important for Wikipedia
Have directly linkable entries and other editorial benefits (with a simplicity tradeoff), such as code consistency
Enhance Wikipedia's application richness and usability, and make glossary easier to parse and re-use in various ways by third party applications
Use semantic HTML, improving reusability of Wikipedia content by both software and people
Will validate as both correct XHTML and HTML, ensuring the broadest browser compatibility (see #Technical notes for why this is important)
Are technically well-formed XML, another compatibility factor
Can be extended consistently, e.g. to include metadata, or to specially style terms and definitions
Will be easier to reconfigure if Wikipedia decides to change site-wide formatting, as it often does.

To produce a template-structured glossary, follow these simple steps:

  1. The glossary as a whole (or each part, if broken into sections, e.g. "A–M") is surrounded by a {{gloss}} template and a corresponding {{glossend}} tag.
  2. A term is given on its own line using the {{term}} template, and is automatically boldfaced.
  3. A definition is next given on its own line using the {{defn}} template, and follows either the term or a previous definition.

Do not make individual terms in a template-structured glossary into headings. Doing so will produce garbled output. The terms will be linkable without being headings.

Use the templates as a set, and do not mix-and-match glossary templates with wikimarkup definition list code (; and : style) or other markup.

If a glossary consists of few entries, all with lengthy definitions, consider instead formatting the article as a subheading-style glossary, in regular paragraphs.

Formatting[edit]

Template-structured glossaries use semantic, accessible markup that adheres to Web standards, for reasons detailed above. Some example code, showing various formatting options, as might appear in a stand-alone glossary article divided into sections by letter of the alphabet:

==A–M==

Optional introductory text.

{{gloss}}
{{term|1=term 1}}
{{defn|no=1 |1=
Beginning of the definition of term 1.

More of the definition of term 1.
}}

{{term|1=term 2}}
{{defn|no=1 |1=First definition of term 2.}}
{{defn|no=2 |1=Second definition of term 2.}}
{{term|1=term 3}}
{{defn|1=Simple definition of term 3.}}
{{term|1=term 4}}
{{defn|1=Definition of term 4, with a...
<blockquote>Block-quoted passage</blockquote>
More definition of term 4.
}}

{{glossend}}

A–M

Optional introductory text.

term 1
Beginning of the definition of term 1. More of the definition of term 1.
term 2
1.  First definition of term 2.
2.  Second definition of term 2.
term 3
Simple definition of term 3.
term 4
Definition of term 4, with a...

Block-quoted passage

More definition of term 4.

As is shown in the example, multiple definitions use multiple {{defn}} templates. See the templates' documentation for the advanced features of {{term}}, {{defn}}, and {{gloss}}.

With template-structured (using these templates, or created manually with HTML), a definition behaves, inside its <dd>...</dd> bounds, just like normal prose and markup. Multiple paragraphs can be used with ease, and block-quotes, nested lists and other structures can be used freely, unlike the other styles. The flexibility and power of HTML tags are much richer than those provided by wikimarkup's ; and : definition list or * unordered list features, which do not work properly due to MediaWiki bugs and misfeatures.

Multiple paragraphs can be created, as in regular prose, simply by introducing a blank line as shown in the example, or can be explicitly blocked out with <p>...</p> markup.

Within a {{gloss}}, all text and other content must be inside a {{defn}}. This markup is invalid in several places, as annotated:

{{gloss}}
{{main|Hatnotes and other templates can't go here, inside the glossary list but before terms and definitions}}
{{term|1=term 1}}
[[File:misplaced_image.png|thumb|right|300px|This image cannot be between the term and definition like this.]]
{{defn|1=Definition of term 1.}} {{term|1=term 2}}
{{defn|no=1|1=First definition of term 2.}}
<blockquote>Between definitions is no place for a quotation or anything else.</blockquote>
{{defn|no=2|1=Second definition of term 2.}}
<p>A paragraph (or whatever) can't be between entire entries, without {{glossend}} to close the glossary before the content and a new {{gloss}} to open glossary formatting again after that content being interpolated.</p>
{{term|1=term 3}}
{{defn|1=Definition of term 3.}}
{{glossend}}

Such add-on content does not go inside the {{term}}, which is just for the term and its markup.

Bullet-style[edit]

This is the simplest style used for glossaries. It is an application of a bulleted list. It is done like this:

==Glossary==

Optional introductory text.

*'''term 1''': Definition.
*'''term 2''': 1. First definition. 2. Second definition

Glossary

Optional introductory text.

  • term 1: Definition.
  • term 2: 1. First definition. 2. Second definition

This easy style is often used in embedded glossaries. Numbered lists (beginning with # instead of *) should not be used, as they imply a specific (e.g. hierarchical or chronological) order.

Complex glossaries are best done using template-structured format.

Blocks of text, properly marked up, can be used for longer definitions. Multi-paragraph definitions require the HTML <p>...</p> paragraph markup, without any wikimarkup whitespace between either of the passages and the break, due to MediaWiki limitations (see Wikipedia:Manual of Style/Glossaries/DD bug test cases for technical details). The <p>...</p> markup is required both before and after the break or the line spacing will be noticeably inconsistent. Example showing various extended aspects of bulleted list wikimarkup for a glossary:

==Glossary==

Optional introductory text.

*'''term 1:''': Definition.
*'''term 2''': 1. First definition. 2. Second definition
*'''term 3''':
:Long definition.
*'''term 4''':
#First long definition.
#Second long definition.
*'''term 5''': Intro to long definition:
:<p>Continuation of long definition.</p><p>Conclusion of long definition.</p>

Glossary

Optional introductory text.

  • term 1: Definition.
  • term 2: 1. First definition. 2. Second definition
  • term 3:
Long definition.
  • term 4:
  1. First long definition.
  2. Second long definition.
  • term 5: Intro to long definition:

Continuation of long definition.

Conclusion of long definition.

Subheading-style[edit]

Stand-alone glossaries with long and detailed definitions can sometimes be best formatted with entries as subheadings. This style should not be used for embedded glossaries. In this style, definitions are presented as normal prose paragraphs:

==A–M==

Optional introductory text.

===term 1===

Definition.

===term 2===

1. First definition.

2. Second definition.

A–M

Optional introductory text.

term 1

Definition.

term 2

1. First definition.

2. Second definition.

For cases in which most or all of the definitions are long, multi-paragraph explanations, this format is actually preferable to a template-structured glossary, as the article is only marginally classifiable as a glossary.

Number multiple definitions manually, as shown; do not use ordered lists. This glossary type especially sometimes uses non-numeric identifiers with multiple definitions. Multi-paragraph definitions are just like any other Wikipedia prose paragraphs.

==A–M==

Optional introductory text.

===term 1===

Definition.

===term 2===

''[[Chemistry]]'': First definition.

More of first definition.

''[[Economics]]'': Second definition.

''[[Underwater basketweaving]]'': Third definition.

A–M

Optional introductory text.

term 1

Definition.

term 2

Chemistry: First definition.

More of first definition.

Economics: Second definition.

Underwater basketweaving: Third definition.

One example of such a glossary is Glossary of ancient Roman religion.

General guidelines for making glossaries[edit]

The following guidelines apply to all glossaries and should be followed regardless of which format style presented above is used. Wikipedia outlines, featuring entries with annotations in a hierarchical (classified) order, are not covered by these guidelines.

Alphabetize[edit]

In a glossary, alphabetize all the terms from A to Z. Entries must not be added randomly or in an arbitrary order. A Latin-based character with diacritics is alphabetized after the plain character it is based on. Non-Latin-based characters are alphabetized in order of their appearance in Unicode.

If strictly numeric entries are present, they precede alphabetic ones, and any symbolic entries precede both (i.e.: "!" before "1" before "A"). Numeric entries that sometimes appear in the article subject's context as either numerals or spelled out should be given in the form "three (3)". Do not create numerical entries unless absolutely necessary, such as the case of a definable difference between "eight-" and "8-" in the context, or exclusive use of the numerical version.

If there are no symbolic and only one or a few numeric entries, it is permissible to alphabetize the numeric entries as if they were spelled out, to avoid creation of a very short numeric entries section.

Make a separate section in a stand-alone list for each letter/number if the glossary is large enough to warrant it, but group them into ranges when appropriate, e.g. "X–Z". Otherwise divide the entire article into ranges, e.g. "0–9", "A–M" and "N–Z". Do not section an embedded list, as this impedes editing and may greatly lengthen the overall article's table of contents; if an embedded list is long enough that it would benefit from sectioning, it is a good candidate splitting into a separate stand-alone glossary list article. Do not create empty sections.

Glossary formatting can be used for lists that are not strictly glossaries in the senses covered by this guideline, and many of them will have non-alphabetic ordering rationales (e.g. chronological).

Use natural capitalization[edit]

In most glossaries, begin each glossary term with a lower-case letter, unless it is a proper name or an acronym. While capitalizing the first letter of each term would produce a more uniform, outline-like results (which is why this is the standard for Wikipedia lists more generally), natural capitalization produces fewer ambiguities in a glossary. The use of leading capitals on all entries is recommended only if all of the following apply:

  • No term in the glossary is a lower-case form of something that in other contexts is usually capitalized
  • There is no difference between the capitalized and uncapitalized form of any term in the glossary
  • The terms do not contain a mixture of proper names and common nouns
  • Capitalizing all entries is otherwise unlikely to produce any form of ambiguity or confusion.
  • The glossary is unlikely to ever expand in a way that will break one of the above cases (i.e., it is either already exhaustive, is strictly limited by narrow inclusion criteria, or exclusively contains proper names).

Begin each definition with a capital letter, even if it is a sentence fragment.

What to include[edit]

Wikipedia is not a dictionary; correspondingly, explain glossary terms descriptively (just like an encyclopedia article would do it, but shorter). Only rarely and sparingly add dictionary definitions to a glossary on Wikipedia (usually solely for the sake of completeness). Lists of dictionary definitions belong on Wiktionary; you can still link to them from Wikipedia articles.

Do not add everyday words. Include only specialized terms specific to or having a special meaning within the subject of the glossary.

All entries must be verifiable with reliable sources, just like regular article content.

The Wiktionary glossaries appendix project is likely to transwiki a copy of any glossary created on Wikipedia, and could considerably re-develop it in a more dictionarian direction. It is not necessary (and may be detrimental) to synchronize edits between the two versions, though it will be rare for an entry to be appropriate to exist at all in some form in only one version but not the other. The existence of a Wiktionary glossary on a topic that has a well-developed main article may be a good indication that an encyclopedic glossary on the subject may be developed, either using the dictionarian glossary as a base, or starting from scratch. If both versions do exist they should link to each other in their respective "See also" sections with a sister-project template, e.g. {{Wiktionary|name of page at Wiktionary}} (see Wikipedia:Wikimedia sister projects for recommendations about the best choice of template for various situations).

How to handle multiple variants of a term[edit]

One definition can actually have two or more terms above it as variations or alternatives with the same definition. The most common use case for this is presenting the term in two language variants. This is done with {{lang}} and the appropriate ISO language codes as described at that template. In template-structured glossaries, the bare term, without markup, must be the first parameter of {{term}}, and the language-markup version is parameter 2. If display of the language/dialect name is desired, the {{lang-language-code}} template family can be used instead of {{lang}}. Example:

{{term|1=tyre |content={{lang-en-GB2|tyre}}}}
{{term|1=tire |content={{lang-en-US2|tire}}}}
{{defn|1=A resilient wheel covering usually made of vulcanized rubber.}}

Result:

tyre (British English)
tire (American English)
A resilient wheel covering usually made of vulcanized rubber.

The wikimarkup version is leaner, but has very limited functionality and cannot handle complex input:

;{{lang-en-GB2|tyre}}
;{{lang-en-US2|tire}}
:A resilient wheel covering usually made of vulcanized rubber.

How to handle multiple definitions[edit]

Give some kind of consistent identifiers for two or more definitions of a term. In most cases, multiple definitions should be numbered. Other conventions exist, such as identification of the sub-field to which each definition pertains, but these are rarely mutually exclusive with numbering, and numerical identification is a convenient mnemonic for readers and referent for editors (and because they may be used this way, existing definition order should generally not be changed without good reason).

Avoid definition list wikimarkup[edit]

Avoid using definition list wikimarkup (with ; and :) for glossaries, as it is severely limited and buggy. While such lists are okay for very casual indented list creation, the software does not handle multi-paragraph definitions gracefully or permit blank lines between items. Existing examples should be converted to template-structured glossaries, since most of the work is already done.

Use the standard styles only[edit]

Use a glossary style defined above. Do not use a customized glossary style, such as a table, or a pseudo-list created with manual styling. "Artificial" formats are strongly deprecated. They do not fit reader and editor expectations, they hamper reusability of Wikipedia content, they make automated processing more difficult, and they often introduce usability and accessibility problems.

Stand-alone glossary articles[edit]

Naming conventions[edit]

Shortcut:

For a glossary list article that consists of a simple lead and a glossary, the form Glossary of subject terms is preferred, with redirects to it from Subject terms, Subject glossary, Subject terminology, Subject jargon, Subject slang, and (to comply with the more general naming convention of lists pattern of "List of subjects") List of subject terms.

For an article that mostly consists of a glossary list but has well-developed prose material on the history and use of the terminology, or other such information (several paragraphs worth), the form Subject terms is preferred, with redirects to it from Glossary of subject terms, Subject glossary and the other names (remember that reader cannot guess whether or not the article has been developed in this way). The links from the "glossary"-named redirects may go directly to the glossary section, if the historical and other material is lengthy. For an article that is mostly on the history, development, spread, etc. of the terminology as a body of a certain subject area's jargon (like legal, dance, etc., terminology generally), and may include an embedded glossary key terms, prefer Subject terminology, again with all the redirects. It is reasonably likely that such an article will eventually split into a prose article and a stand-alone, more developed, glossary article over time.

For a glossary of terms and characters used in a work or series of works of fiction (i.e. a fictional universe), the form Glossary of Work/Series/Franchise name terminology is preferred (again with redirects) since the terms form a terminological system that does not exist as terms in use outside that fictional context. Example: Glossary of His Dark Materials terminology.

The general advice at WP:Stand-alone lists#Naming conventions (e.g. handling of nationalities, fictional subjects, etc.) includes glossaries as well, to the extent applicable.

The sub-articles of multi-page split glossaries should follow the guidelines at WP:Naming conventions (long lists) to the extent applicable. In short, they should be named as the original (main) glossary page, with the letter or range of covered letters of the alphabet (or numbers, etc.) following a colon after this title, e.g. Glossary of underwater basketweaving terms: A–M or Curling terms: N–Z. Per WP:Manual of Style#Dashes, The en-dash (–) is used to divide the range, not a hyphen (-), em-dash (—), minus (−) or other similar character, but the hyphenated form of the article name (e.g. Curling terms: N-Z) must also exist as a redirect to the real article page.

Specialized glossaries may require a different sort of name (including for multi-part glossaries' sub-articles), e.g. Glossary of computing terms: Unix and Linux, Glossary of computing terms: Microsoft Windows, etc.

See the "Embedded glossaries" and "Using glossary formatting in non-glossary lists" sections, below, for related naming issues.

Layout[edit]

Glossary articles are expected to satisfy the same conditions as other articles; this will include a well-developed lead section and references.

The default Wikipedia table of contents will not be very useful with most glossaries. One solution is:

__NOTOC__{{CompactTOC8|center=yes|symnum=yes|refs=yes}}

or, if there are only alphabetical entries from A to Z, simply:

__NOTOC__{{CompactTOC8|center=yes|refs=yes}}

There are a number of variants; see the documentation for Template:CompactTOC8.

Please note that the section headings must be created manually, as usual, and must exactly match the selected {{CompactTOC8}} parameters.

Each section in a lengthy glossary page should terminate with another call to {{CompactTOC8}} (or some other form of concise sectional navigation). CompactTOC8 can be used with various other parameters enabled to keep the display thin and linear and with a link to the top of the page, e.g.:

{{CompactTOC8|side=yes|center=yes|top=yes|symnum=yes|refs=yes|nobreak=yes}}

Depending upon the {{CompactTOC8}} parameters set, there may be a section for entries beginning with numerals, with symbols, or both. If present, this section should precede "A" or whatever the first alphabetic section is ("A–M", etc.) Entries that are commonly but not always found in numeric form should be given in this section and cross-referenced to it from its spelled-out name, or vice-versa, not given duplicate definitions. Cross references are italicized. Example:

{{term|1=20 Tanks}}

{{defn|''See [[#Twenty Tanks|Twenty Tanks]].''}}
...
{{term|1=Twenty Tanks}}

{{defn|''Also '''20 Tanks'''.'' Twenty Tanks was an award-winning micro-brewery in San Francisco, California, and a sister enterprise to the Triple Rock brewery in Berkeley.}}

Article growth and splitting[edit]

A glossary that becomes too long (more than about 400 KB) should be split into multiple articles. This is a higher suggested limit than for normal articles, because we generally do not expect readers to work their way through a glossary from head to tail, so their length need not be limited by attention span, and a glossary's primary purpose is linking to specific entries and, crucially, in-page searching, which is broken by splitting. On the other hand, very large articles take a long time to load, especially for editing or previewing.

When necessary, glossaries should usually be split into roughly equal chunks, rather than attempting to convert to summary style, or thinning out by narrowing the subject of the glossary. For example, the first split of Glossary of underwater basketweaving terms could be into Glossary of underwater basketweaving terms: A–M and Glossary of underwater basketweaving terms: N–Z, but very long glossaries may need even more parts, and some glossaries will have one letter much longer than others. If there are terms beginning with numbers or symbols, they should go before A, in sections of their own, unless there are enough of them to warrant their own subarticle.

There are two good solutions for the original Glossary of underwater basketweaving terms:

  • Have it redirect to the first chunk, and include the original lead there.
  • Have it as a disambiguation page, with a full lead, and links to all the chunks.

In either case, the other chunks should have summaries of the full lead, so that multiple different leads do not evolve. The first method is simpler; the second is preferable for glossaries so long that they need more than three or four chunks, or list articles in glossary format but not in basic alphabetical order (bicycles by manufacturer, wars by year, etc.).

Care is needed in dividing glossaries into subarticles. Each subarticle must link with the ones before and after, and to the disambiguation page if there is one; {{CompactTOC8}} can help with this. Each sub-article must have its own references section, and these should be checked to be sure they still work. In particular, the first instance of a named <ref> tag in each subarticle will need its own text and cannot simply be a <ref name="ref-name" /> secondary ref call. The name= name for the same ref should not change from subarticle to subarticle.

Embedded glossaries[edit]

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. It may also provide a glossary that can be linked to from related articles, unless and until such time as a stand-alone glossary is warranted.

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 (this is not only orderly, it allows the glossary to be linked to directly). The title of this section should conform to WP:Manual of Style#Section headings – do not repeat the subject in the heading. It also should not use excess verbiage ("Glossary of key terms in the discipline", etc.) – keep it simple. A plain ==Glossary== is fine in most cases.
  • 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 article.
  • If the entries will be very detailed, it is probably better to use a stand-alone glossary; embedded entries should be concise.
  • Embedded glossaries should not use subheadings inside them (e.g. for letters of the alphabet), and should simply be editable as a single section. If it is large enough to need subsectioning, it should probably be a separate article.

The preferred method of creating an embedded glossary is to use the template-structured style, and put the glossary under a single, clearly labeled heading (e.g. ==Glossary==). This requires a bit more work than bulleted lists, but it provides most of the benefits of a stand-alone, template-structured glossary, and makes it very easy to eventually move the glossary to its own page when the glossary grows longer.

Using glossary formatting in non-glossary lists[edit]

Glossary-style formatting is not limited to use in glossaries. There are other uses for the markup methods employed in glossaries. They can be used for data presentation purposes in other types of lists. For example, glossary-style formatting may work well for presenting a list of aircraft serial numbers along with their models and descriptions, using the same basic basic layout as glossaries.

For an article that is a non-glossary list that uses glossary formatting, follow the advice at WP:Stand-alone lists#Naming conventions. For the naming of multi-page, split lists, see WP:Naming conventions (long lists). Such lists sometimes need customized naming, if they are not naturally expressible as alphabetic or numeric ranges, e.g. List of automobiles: Chevrolet, List of automobiles: Ford, etc. Note, however, the standardized use of a colon, not a parenthetical, comma, dash, slash or other separator.

Non-glossaries often need different sectioning (numerical, topical) than a glossary, and consequently may have different table of contents needs, and for multi-page long lists, each sub-article needs inter-page navigation of some kind to other articles in the series. Some solutions include specialized compact tables of contents and custom navigation templates. Such lists may also have different section {{em|ordering{{em| needs, e.g. by date in a list of events, instead of alphabetical.

Technical notes[edit]

  1. While most of us already understand that accessibility and usability are crucial, many are not aware that code validation, semantics and well-formedness are also important. Very trivial HTML syntax errors can cause rendering failures in even the parser of Wikipedia's robust MediaWiki server engine, and their effect on each of the numerous browser platforms and automated tools on the user end is unpredictable. This is not the 1995 World Wide Web; standards actually matter today.
  2. MediaWiki's handling of definition lists with the semicolon and colon (; and :) wikimarkup features is severely broken, and cannot be used for any but the simplest of glossaries without causing problems for both readers and editors. Real HTML must be used instead via the simple templates described here (or bare HTML in unusual cases with special requirements). The two biggest problems with the ; and : markup are that even one blank line, for readability, between definitions leads to mangled markup (not visible to the user, but problematic per point #1, above), and multi-paragraph definitions can only be correctly achieved in a way that makes them difficult to edit. (See Wikipedia:Manual of Style/Glossaries/DD bug test cases for lots of technical detail.) Both of these problems are eliminated by using the template-structured presented above.
  3. In wikimarkup definition lists, a blank line between entire entries (i.e. between the definition of one entry and the term of the next) to space the entries further apart is fine, and will not affect the semantics of the code or the output but only if {{gloss}} and {{glossend}} (or manually inserted <dl>...</dl> tags) surround all of the entries (of the whole glossary, or of the section, if the glossary is sectioned) as a block. If these are omitted, MediaWiki will treat every term as its own entire definition list, and output messy code that is semantically useless.
  4. Update (8 May 2011): Now that a known MediaWiki bug has been fixed in Wikipedia's software engine, and the HTML element <dfn>...</dfn> is properly supported, the {{term}} template will now also identify the term as the defining instance of its usage in the page, as en.wikipedia has in fact installed the upgraded version of MediaWiki.

Actual HTML output of template-structured glossaries[edit]

For the technically minded, the following is an explanation of the actual HTML markup that will be rendered from the templates by the reader's browser (not counting various classes and other details that are supplied automatically by the MediaWiki web application, and with spacing cleaned up a little for human readability). The code validates, is structurally well-formed, and is semantically correct.

  1. {{gloss}} and {{glossend}} together invoke the <dl>...</dl> description list HTML structure (called a definition list in HTML 4, and sometimes also called an association list); the "dl" shortcut is not available at this time, unfortunately
  2. {{term}} a.k.a. {{dt}} invokes the <dt>...</dt> description list term HTML element, with an embedded <dfn>...</dfn> defining instance of term element
  3. {{defn}} a.k.a. {{dd}} invokes the <dd>...</dd> description list definition element


Example wikicode

==Heading==

{{gloss}}
{{term|term 1}}
{{defn|Definition 1.}}
{{term|term 2}}
{{defn|
1. Definition 2a start.
Definition 2a conclusion.
}}

{{defn|2. Definition 2b.}}

{{glossend}}
HTML represented

<h2>Heading</h2>

<dl class="glossary">
<dt class="glossary" id="term 1"><dfn>term 1</dfn></dt>
<dd>Definition 1.</dd>
<dt class="glossary" id="term 2"><dfn>term 2</dfn></dt>
<dd>
<p>1. Definition 2a start.</p>
<p>Definition 2a conclusion.</p>
</dd>

<dd>2. Definition 2b.</dd>

</dl>

References[edit]

  1. ^ W3C. "HTML5". Retrieved 5 April 2011. .