The following is a working draft of a proposed Wikipedia policy, guideline, or process. The proposal is definitely still in development and under discussion, and has not yet reached the process of gathering consensus for adoption. Thus references or links to this page should not describe it as "policy" nor yet even as a proposal.

Shortcuts: WP:MOSGLOSS WP:GLOSSARIES

This page in a nutshell: Use proper markup for glossaries. Avoid in-article glossaries unless both genuinely reader-helpful and concise. Glossary list articles should be created in a consistent manner.

HTML (and XHTML, which Wikipedia uses) provide rich semantics for producing glossaries and lists similar to glossaries. (See HTML elements for more information on definition lists and their term and definition elements.). 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.

Glossaries
List of glossaries Style guide (talk) WikiProject (talk) Category:Glossaries

Contents 1 Terminology 2 General guidelines 2.1 Structured glossaries 2.2 Capitalization 2.3 Alphabetization 2.4 Content 3 Glossary formatting 3.1 Layout 3.2 Article size and split glossaries' sub-articles 3.3 Naming conventions 4 In-article glossaries 5 Non-glossary lists using glossary formatting 6 Technical notes 7 Actual HTML structure 8 See also

[edit] Terminology

A glossary is a list of individual entries. Each entry consists of a term and one or more definitions.

The same pattern can be used for articles or sections which are not literally lists of definitions; for example a list of airplane makes and their serial numbers could fall into the same pattern as a glossary, and the same tools can be used to make one.

There are several ways to make a glossary; the Wikipedia {{table}} templates can be adapted to the purpose, for example. Most glossaries, however, will have the entries as separate terms in boldface, followed by definitions.

[edit] General guidelines

[edit] Structured glossaries

Glossaries can be structured or non-structured; both will appear much the same to the reader. Structured glossaries will require considerably more control code, but will be more readily accessible by some outside applications, and will be easier to reconfigure if we decide to change global format; structured glossaries will also result in cleaner XHTML output from Wikipedia's MediaWiki software engine, and entries in them can be linked directly.

A structured glossary does not use free-form bullet items, or headings and freeform text; rather, it consists of terms and definitions within definition list structures. Writing such structures is explained in the "Glossary formatting" section, below.

The following will produce a structured glossary; this also notes the corresponding pieces of normal wiki markup.

glossary

Place between {{gloss}} and {{glossend}}, on separate lines. These both invoke the <dl>...</dl> HTML element.

terms

Automatically boldfaced. Structured glossaries use the {{term}} template; preceding a plain text term with ; has the same effect. These invoke the <dt>...</dt> HTML element in the background.

definition

Place the : character before definitions, which translates into the <dd>...</dd> HTML element.

Individual terms in a structured glossary should not be made into headings (and doing so will produce garbled markup.) If a glossary consists of a few entries, all with lengthy definitions, it may be better to format the article as a series of sections with definitions in regular paragraphs, rather that using structured glossary format.

If a definition runs to multiple paragraphs, delimiting them with <p> and </p> will produce cleaner output code with fewer accessibility problems; many editors regard this as also producing less readable edit space. As often, this is a tradeoff.

[edit] Capitalization

It is acceptable to present the terms in natural capitalization: as they would appear in the middle of a sentence. Capitalizing the first letter of each term will produce a more uniform output; if the terms are divided roughly evenly between proper and common nouns, however, or there is a difference between the capitalized and uncapitalized form of some term, natural capitalization may well be a good idea.

Definitions should begin with capital letters, even if they are formally sentence fragments.

Multiple definitions of the same term can be numbered. If this is done using the # character, the : should be omitted, and the separate definitions should not have a space between them. It may be simpler to number explicitly thus:

1. First definition here.

[edit] Alphabetization

It is customary to alphabetize glossaries. Each letter can be a separate section, if the glossary is large enough to warrant it.

[edit] Content

Wikipedia is not a dictionary; correspondingly, glossaries should rarely contain dictionary definitions, but should explain their terms encyclopedically. Lists of dictionary definitions belong on Wiktionary; they can still be linked by our articles.

Likewise, the glossary should not contain everyday words, nor terms not specific to the field in question.

All entries must be verifiable with reliable sources, just like any other information in Wikipedia articles.

[edit] Glossary formatting

Structured glossaries will use semantic markup, thus:

==Section title terms==
Optional introductory text.
{{gloss}}
{{term|term 1}}
:Definition of term 1.
{{term|term 2}}
:<p>1. Part of the first definition of term 2.</p><p>More of the first definition of term 2.</p>
:2. Second definition of term 2.
{{glossend}}

This renders as the following (eaceot that the heading will actually be a real heading):

Section title

term 1

Definition of term 1.

term 2

1. Part of the first definition of term 2.

More of the first definition of term 2.

2. Second definition of term 2.

Unstructured glossaries can use the simpler markup:

==Glossary of article subject terms==
Optional introductory text.
;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 (but, again, the heading will actually be a real heading):

Glossary of underwater basketweaving terms

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.

Blank lines between entries (which will make this more readable) will cause redundant MediaWiki formatting, which can cause accessibility problems. Some editors, therefore, will wish to avoid this format, or convert unstructured glossaries to the structured format. But this should not be read to deter the use of unstructured glossaries; it is better to have the information, and convert it later when there is interest and consensus in do it.

[edit] Layout

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}}

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

Please note that the section headings must be created manually and must exactly match the selected {{CompactTOC8}} options.

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. 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. Example:

{{term|8 ball}}
:''See [[#eight-ball|eight-ball]].''
...
{{term|eight-ball}}
;''Also '''8 ball''', '''8-ball''', '''eightball'''.'' Definition here.

[edit] Article size and split glossaries' sub-articles

A glossary that becomes too long (more than about 100 kB) should be split into multiple articles. We 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; but very large articles have technical problems: they take a long time to load, especially for editing or previewing; the may cause some browsers to crash by demanding too much memory.

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 two 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 articles formatted in glossary format but not in alphabetical order.

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.

[edit] Naming conventions

Shortcut: WP:NCGLOSS

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 and Subject glossary. This mirrors the more general naming convention of lists, "List of subjects".

For an article that mostly consists of a glossary list but has well-developed 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 and Subject glossary.

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

The sub-articles of multi-page split glossaries should follow the guidelines at Wikipedia: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. The en-dash (–) should be 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, Glossary of computing terms: Microsoft Windows, etc.

See the "In-article glossaries" and "Non-glossary lists using glossary formatting" sections, below, for related naming issues.

[edit] 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 both Wikipedia:Manual of Style#Section headings – do not repeat the subject in the heading. Example: In an article Underwater basketweaving, a glossary would be given a heading of ==Glossary== not ==Glossary of underwater basketweaving terms==, since repeating the subject is redundant. It should not use other pointless language, either (==Glossary of key terms in the discipline==, etc.) – keep it simple.
• 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.
• If the entries will be very detailed, it is probably better to use a stand-alone glossary; in-article entries should be concise.
• In-article glossaries should not use subheadings inside them (e.g. for letters of the alphabet), and should simply be editable as a single section.

The preferred method of creating an in-article glossary is to use templates to lay out the structure of the glossary, just as for glossary list articles, as shown above (see [[#Glossary formatting|the "Glossary formatting" section), under a single clearly labeled heading (usually ==Glossary==).

Important: See the "Technical notes" section for information on how to properly format multi-paragraph definitions.

[edit] Non-glossary lists using glossary formatting

For an article that is a non-glossary list that uses glossary formatting, follow the advice at Wikipedia:Stand-alone lists#Naming conventions. For the naming of multi-page, split lists, see Wikipedia: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.

The {{term}} template should only be used for actual glossaries. For non-glossary lists that simply use glossary formatting, use a bare <dt>...</dt> structure, or its wikimarkup equivalent, ;:

{{gloss}}
;term 1
:Definition of term 1.
{{glossend}}

If it is desired that the terms have link anchors, use the {{anchors}} template to provide them. E.g., ;term 1{{anchors|term 1|another anchor}}

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 ordering needs, e.g. by date in a list of events, instead of alphabetical.

[edit] Technical notes

1. 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 a bug in 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.</p>
<p>This is more of the definition of term 1.</p>

   For the same reason, if an indented segment of the definition is required, use <blockquote>...</blockquote> around it, and butt those tags against any preceding or following paragraph tags in the same definition.

2. 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.
3. 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.

[edit] 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). 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:

<h2>Heading</h2>
<dl class="glossary">
<dt class="glossary" id="term 1">term 1</dt>
<dd>Definition 1.</dd>
<dt class="glossary" id="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>

[edit] See also

• Wikipedia:Explain jargon