View source for Wikipedia:Manual of Style/Glossaries/DD bug test cases

{{Wikipedia how-to|interprets=Wikipedia:Manual of Style/Glossaries}}
This page provides test cases for, an explanation of, and information on working around, a long-standing [[MediaWiki]] bug with the {{tag|dd}} HTML element (the description/definition part of a [[description list]], also known as a definition list or association list).

==Overview==
{{hatnote|This page was last updated 12 December 2017, for MediaWiki version 1.31.0-wmf.11. The current version of MediaWiki used by en.Wikipedia is {{CURRENTVERSION}}; if it is a .{{var|XX}} revision ahead, this material may need to be reviewed and, if necessary, updated.}}
Due to MediaWiki's very brittle handling of HTML list structures generally (in particular, the inability to handle multiple paragraphs except under a very specific circumstance, outlined below), {{em|the <code>;</code> and <code>:</code> wikimarkup features cannot be used to produce any but simplistic and easily-broken description lists, unlike real HTML.}} Some of the interrelated bug reports include: [https://bugzilla.wikimedia.org/show_bug.cgi?id=1584 1584] (unresolved {{as of|lc=y|September 2014}}), [https://bugzilla.wikimedia.org/show_bug.cgi?id=5178 5178] (unresolved {{as of|lc=y|September 2014}}), <del>[https://bugzilla.wikimedia.org/show_bug.cgi?id=6200 6200]</del>, etc.

The main problem is detailed below, but there are also other problems with the wikimarkup version of definition lists. Bug reports include: [https://bugzilla.wikimedia.org/show_bug.cgi?id=6776 6776], [https://bugzilla.wikimedia.org/show_bug.cgi?id=11894 11894], and [https://bugzilla.wikimedia.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&content=definition+list many others].{{update after|2016|reason=This bugs have moved to Phabricator, have different numbers how; the bugzilla links may work for a while but need to be replaced; see Template:Phab.}}

It is unlikely that all these problems will be fixed any time within the next several years, especially as they are seen as "features" by some, including the termination of a list item by a line break.  {{crossref|(See detailed comments in the bug reports for more information.)}}

{{see also2|https://test.wikipedia.org/wiki/Bug_T7718 for a related block-element bug test-cases page.}}

==Examination of the main problem==
In <code>;</code> and <code>:</code> markup, if a single description/definition (or term, for that matter) uses multiple paragraphs, it is {{em|necessary}} to specify the paragraphs explicitly with a {{tag|p|o}} or the full {{tag|p}} paragraph markup, and to do so without line breaks. We cannot just do the seemingly rational thing of creating a second description line for a second paragraph, as this indicates {{em|two separate definitions}}, not a multi-paragraph definition, and doing this causes all sorts of problems. 

Due to bugs in (or alleged features of) the MediaWiki software  ''(see above)'', the paragraphs {{em|must not}} be separated by a newline either inside or outside of the paragraph, in wikimarkup-based list items such as descriptions/definitions: 

{{mxtn|1=<nowiki>;</nowiki>term 1<br /><nowiki>:<p></nowiki>Part of definition of term 1.<nowiki></p><p></nowiki>More of definition of term 1.<nowiki></p></nowiki>}}

or more compactly:

{{mxtn|1=<nowiki>;</nowiki>term 1<br /><nowiki>:</nowiki>Part of definition of term 1.<nowiki><p></nowiki>More of definition of term 1.<nowiki></p></nowiki>}}

and it is highly unlikely that any regularly edited text would retain such precious formatting for long before someone broke it. The same holds true of the use (again without linebreaks) of {{nowrap|<code><nowiki><br /><br /></nowiki></code>}}, as suggested (along with {{tag|p}}) at [[Help:List]], which leads to accessibility problems anyway: text visually broken with simply {{tag|br|s}} line breaks this way will not be treated as separate paragraphs by [[Wikipedia:Manual of Style/Accessibility|screen readers]].

To be clear, this example {{em|does not work}}:

{{!mxt|1=<nowiki>;</nowiki>term 1<br /><nowiki>:<p></nowiki><br />Part of the definition of term 1.<br /><nowiki></p><p></nowiki><br />More of definition of term 1.<br /><nowiki></p></nowiki>}}

and neither does this one:

{{!mxt|1=<nowiki>;</nowiki>term 1<br />
<nowiki>:<p></nowiki>Part of definition of term 1.<nowiki></p></nowiki><br />
<nowiki><p></nowiki>More of definition of term 1.<nowiki></p>
</nowiki>}}

nor anything like them {{crossref|pw=y|(see test cases below)}}.

For the same reason, if a <code>:</code>-initiated definition/descritption requires an indented segment, one has to use something like <code><nowiki><span style="margin-left: 1.6em;">...</span></nowiki></code> (1.6em is how far rightward a MediaWiki-generated list item is indented) around it to get valid code as the result, and {{em|must}} butt those tags against any preceding or following paragraph tags in the same definition. Trying to use {{tag|blockquote}} for this would be semantically wrong (unless the content actually consists of a quotation), and would still have this no-line-breaking requirement.

[[Help:List]]'s suggestion to use <code>:</code> as an indent produces semantically invalid markup, which will also not [[W3C Markup Validation Service|validate]] because it is missing the {{tag|dt|o}} element.<ref>{{cite web |url= https://validator.w3.org/ |title=Markup Validation Service: Check the markup (HTML, XHTML, …) of Web documents |work=Validator.W3.org |publisher=[[World Wide Web Consortium]] |date=2017 |version=v1.3+hg |access-date= December 13, 2017}}</ref>  While this is not an enormous concern with a quick-and-dirty wikimarkup lists, it's poorly-accessible and poorly-[[Wikipedia:Reusing Wikipedia content|reusable]] output would be a major problem for [[Wikipedia:Manual of Style (glossaries)|structured glossaries]]:

<table>
<tr>
<th>Sloppy code</th>
<th>Looks okay...</th>
<th>But output is poor</th>
</tr>
<tr>
<td style="border: 1px solid black; width: 33%; vertical-align: top;">
<pre>
{{glossary}}
{{term|term 1}}
{{defn|1=Beginning of definition.
:Indented text in definition.
Conclusion of definition.
}}
{{glossend}}
</pre>
</td>
<td style="border: 1px solid black; width: 33%; vertical-align: top;">
{{block indent|1=
{{glossary}}
{{term|term 1}}
{{defn|1=Beginning of definition.
:Indented text in definition.
Conclusion of definition.
}}
}}
{{glossend}}
</td>
<td style="border: 1px solid black; width: 33%; vertical-align: top;">
{{!mxt|1=<pre>
<dl>
<dt>term 1</dt>
<dd>Beginning of definition.
<dl>
<dd>Indented text in definition.</dd>
</dl>
Conclusion of definition.</dd>
</dl>
</pre>}}
</td>
</tr>
</table>
The rendered output of this looks correct to the fully-sighted human reader in a graphical browser, but in reality, the MediWiki parser has made the <code>:</code>-"indented" item into an entire new definition list (glossary), which is broken anyway (in having no term), as well as defeating the intent of the original list it's embedded in!  {{strong|Wikimarkup definition list structures cannot be mixed with structured markup.}}

The brittle list handling [http://www.globalnerdy.com/2007/12/04/bug-vs-feature/ "bug/feature"] is quite general, and also affects ordered (<code>#</code>) and (<code>*</code>) unordered lists.

From the perspective of non-technical editors, simple tricks can be used to make the code more readable for some editors. One such kluge is to put linebreaks between definitions, as already illustrated, giving the false appearance of a well-spaced list, when in reality MediaWiki creates a whole slew of pointless micro-lists, ruining the [[Semantic HTML|semantic value]] and [[Wikipedia:Manual of Style/Accessibility|accessibility]] of bothering to use definition list markup in the first place.  Another is to {{em|code}} a multi-paragraph definition as multiple definitions, but write the {{em|prose}} as if it were a single definition in two paragraphs. And as already, noted this just blatantly falsifies the semantic markup, resulting in pretty-looking but technically awful output. 

Such hacks will lead to confusing Wikipedia code (that other editors are likely to correct anyway), redundant MediaWiki output, and blatantly invalid HTML, among other problems, resulting in accessibility and usability issues.

To repeat: {{strong|It just doesn't work}}, due to MediaWiki "bug/features", {{strong|but there is an easy solution}} as shown below.

NB: Replacing <code>:</code> with a real {{tag|dd}} structure has no effect if <code>;</code> is used, or vice-versa with {{tag|dt}} and <code>:</code>.  The entire structure must be entirely HTML in order to function properly. Which brings us to...

==Workaround==
The workaround, as illustrated below, is to abandon <code>;</code> and <code>:</code> entirely for any case in which one intends to produce rich definition lists, including glossaries, and instead use pure HTML markup: <code><nowiki><dl><dt>...</dt><dd>...</dd>...</dl></nowiki></code>.  And there is no reason to use HTML manually to produce a glossary when the easy-to-use [[Wikipedia:Manual of Style (glossaries)#Template-structured|structured glossary templates]] will do this for you, and do it consistently with other glossary articles. For non-structured glossaries, [[Wikipedia:Manual of Style (glossaries)#Glossary formatting styles|use bullet lists or use subheadings and plain-text entries]].

==Test cases==
{{hatnote|This section was last updated 10 June 2024, for MediaWiki 1.43.0-wmf.8. The current version of MediaWiki used by en.Wikipedia is {{CURRENTVERSION}}; if it is a .{{var|XX}} revision ahead, this section may need to be reviewed and, if necessary, updated.}}
<table>
<tr>
<td style="padding-left:5px; width: 50%; border: 1px solid black;">
<pre>
<dl>
;term 1
:<p>
This is part of the definition.
</p><p>
This is more of the definition.
</p>
</dl>
</pre>
</td>
<td style="padding-left:5px; width: 50%; border: 1px solid black; background-color:#FCC">
<dl>
;term 1
:<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dl>
----
{{strongbad|Failure}}: Code invalid (two {{mono|<nowiki><dl></nowiki>}} elements created, one broken by having sub-elements other than {{mono|<nowiki><dt></nowiki>}} or {{mono|<nowiki><dd></nowiki>}} directly inside). Visually, definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 2
:<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 2
:<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dl>
----
{{strongbad|Failure}}: Code broken ({{mono|<nowiki><dl></nowiki>}} terminates early and the continuance of the definition is not part of the list). Visually, only one definition indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 3
<dd>
<p>
This is part of the definition.
</p><p>
This is more of the definition.
</p>
</dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 3
<dd>
<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dd>
</dl>
----
{{strongbad|Failure}}: Definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 4
<dd>
<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 4
<dd>
<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dd>
</dl>
----
{{strongbad|Failure}}: Definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 5
<dd><p>
This is part of the definition.
</p><p>
This is more of the definition.
</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 5
<dd><p>This is part of the definition.</p>
<p>This is more of the definition.</p></dd>
</dl>
----
{{strongbad|Failure}}: Definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 6
<dd><p>This is part of the definition.</p>
<p>This is more of the definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 6
<dd><p>This is part of the definition.</p>
<p>This is more of the definition.</p></dd>
</dl>
----
{{strongbad|Failure}}: Definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 7
<dd>This is the entire definition.</dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 7
<dd>This is the entire definition.</dd>
</dl>
----
{{strongbad|Failure}}: Definition not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 8
<dd><p>This is the entire definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 8
<dd><p>This is the entire definition.</p></dd>
</dl>
----
{{strongbad|Failure}}: Definition not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 9
:<p>This is part of the definition.</p><p>This is more of the definition.</p>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FF9;">
<dl>
;term 9
:<p>This is part of the definition.</p><p>This is more of the definition.</p>
</dl>
----
{{Strong|Poor}}: Indentation is typical WP style for this markup, but undesirable for proper use of the tags to create a glossary, because even the term is indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
;term 10
<dd><p>This is part of the definition.</p><p>This is more of the definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
;term 10
<dd><p>This is part of the definition.</p><p>This is more of the definition.</p></dd>
</dl>
----
{{strongbad|Failure}}: Definitions not indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 11</dt>
<dd><p>This is part of the definition.</p><p>This is more of the definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FF9;">
<dl>
<dt>term 11</dt>
<dd><p>This is part of the definition.</p><p>This is more of the definition.</p></dd>
</dl>
----
{{strong|Poor}}: Undesirable indentation of the term is gone, so it looks right, but it requires <code>&lt;/p&gt;&lt;p&gt;</code> on the same line, which is easily broken.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<code style="font-size:90%"><nowiki>
<pre>
<dl>
<dt>term 12</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
</pre>
</nowiki></code>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#9f9;">
<dl>
<dt>term 12</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
----
{{stronggood|Success}}: Perfect, and supports <code><nowiki><p></nowiki></code> properly, which means it will also support <code><nowiki><blockquote></nowiki></code>, nested lists, etc.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 13</dt>
:<p>This is part of the definition.</p>
<p>This is more of the definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
<dt>term 13</dt>
:<p>This is part of the definition.</p>
<p>This is more of the definition.</p>
</dl>
----
{{strongbad|Failure}}: Only one definition indented.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 14</dt>

<dd>1. This is the first definition.</dd>

<dd>
2. This is part of the second definition.

This is more of the second definition.
</dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#FCC;">
<dl>
<dt>term 14</dt>

<dd>1. This is the first definition.</dd>

<dd>
2. This is part of the second definition.

This is more of the second definition.
</dd>
</dl>
----
{{strongbad|Failure}}: Lack of auto-markup of paragraphs.  This used to work perfectly, because MediaWiki would auto-generate paragraph markup for plain text entered on isolated lines, even inside a {{tag|dd}} wrapper, and didn't have any problem with definitions spaced apart from terms, either.  This broke in late 2013.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 15</dt>
<dd>1. This is the first definition.
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#9f9;">
<dl>
<dt>term 15</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
----
{{stronggood|Success}}: Perfect, even with a two-fold coding error (missing <code><nowiki></p></dd></nowiki></code> on the first definition)
</td>
</tr>
<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 16</dt>
<dd>1. This is the first definition.</dd>
<dd>2. This is part of the second definition.
<p>This is more of the second definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color: #D2FF95;">
<dl>
<dt>term 16</dt>
<dd>1. This is the first definition.</dd>
<dd>2. This is part of the second definition.
<p>This is more of the second definition.</p></dd>
</dl>
----
{{strong|Acceptable}}: Vertical spacing isn't quite right, but with real paragraphs of content in place, no one would really notice or care.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 17</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#9f9;">
<dl>
<dt>term 17</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
</dl>
----
{{stronggood|Success}}: Perfect; no {{code|p}} markup required on single-paragraph entries.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
<dl>
<dt>term 18</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
<dd>3. This is a third, complex definition:
{{quote|With a block quotation.}}
Another paragraph, and
* An embedded list
* More list
Conclusion of definition 3.</dd>
<dd>4. Fourth definition, with blank line

to cause paragraph break.</dd>
</dl>
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#D2FF95;">
<dl>
<dt>term 18</dt>
<dd>1. This is the first definition.</dd>
<dd><p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p></dd>
<dd>3. This is a third, complex definition:
{{quote|With a block quotation.}}
Another paragraph, and
* An embedded list
* More list
Conclusion of definition 3.</dd>
<dd>4. Fourth definition, with blank line

to cause paragraph break.</dd>
</dl>
----
{{strong|Acceptable}}: Blockquote has too much vertical spacing between its leading and following text, but few would probably care.
</td>
</tr>

<tr>
<td style="padding-left:5px; border: 1px solid black;">
<pre>
{{glossary}}
{{term|term A}}
{{defn|This is the definition.}}
{{term|term B}}
{{defn|{{ghat|A hatnote.}}
1. This is the first definition.}}
{{defn|<p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p>
}}
{{defn|3. This is a third, complex definition:
{{quote|With a block quotation.}}
Another paragraph, and
* An embedded list
* More list
Conclusion of definition 3.
}}
{{defn|4. Fourth definition, with blank line

to cause paragraph break.}}
{{term|term C}}
{{defn|This is the definition.}}
{{glossary end}}
</pre>
</td>
<td style="padding-left:5px; border: 1px solid black; background-color:#9f9;">
{{glossary}}
{{term|term A}}
{{defn|This is the definition.}}
{{term|term B}}
{{defn|{{ghat|A hatnote.}}
1. This is the first definition.}}
{{defn|<p>2. This is part of the second definition.</p>
<p>This is more of the second definition.</p>
}}
{{defn|3. This is a third, complex definition:
{{quote|With a block quotation.}}
Another paragraph, and
* An embedded list
* More list
Conclusion of definition 3.
}}
{{defn|4. Fourth definition, with blank line

to cause paragraph break.}}
{{term|term C}}
{{defn|This is the definition.}}
{{glossary end}}
----
{{stronggood|Success}}: Perfect &ndash; everything works as expected, using templated version of code that relies on TemplateStyles to cascade necessary CSS classes (causing the blockquote to tighten-up with its leading and following text).
</td>
</tr>
</table>

==Developer views==
In the process of working on the now-closed MediaWiki bug report {{phabricator|art=y|T3584}} (formerly bugzilla 1584, now tracked as {{phab|T11996}}):
{{quote|1="Real HTML <code>&lt;li&gt;[...]&lt;/li&gt;</code> tags are very rarely used, and then only by HTML-savvy editors who want to apply a class or style attribute, or by editors who cut-and-paste some existing HTML code.  Since block or inline content is allowed in list items, this would be the way to allow correct and more complex formatting of the contents of list items, but at the cost of complex and unusual markup in the edit field, incompatible with wikitext lists."}}

==References==
{{reflist}}