Wikipedia:Manual of Style/Glossaries/DD bug test cases

This page provides test cases for, an explanation of, and information on working around, a long-standing MediaWiki bug with the  HTML element (the description/definition part of a description list, also known as a definition list or association list).

Overview
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), Some of the interrelated bug reports include: 1584 (unresolved ), 5178 (unresolved ), 6200, etc.

The main problem is detailed below, but there are also other problems with the wikimarkup version of definition lists. Bug reports include: 6776, 11894, and many others.

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.

Examination of the main problem
In  and   markup, if a single description/definition (or term, for that matter) uses multiple paragraphs, it is  to specify the paragraphs explicitly with a  or the full  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, 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  be separated by a newline either inside or outside of the paragraph, in wikimarkup-based list items such as descriptions/definitions:


 * term 1
 * Part of definition of term 1.   More of definition of term 1.

or more compactly:


 * term 1
 * Part of definition of term 1. More of definition of term 1.

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, as suggested (along with ) at Help:List, which leads to accessibility problems anyway: text visually broken with simply line breaks this way will not be treated as separate paragraphs by screen readers.

To be clear, this example :

Part of the definition of term 1. More of definition of term 1.
 * term 1

and neither does this one:


 * term 1



More of definition of term 1.

nor anything like them.

For the same reason, if a -initiated definition/descritption requires an indented segment, one has to use something like   (1.6em is how far rightward a MediaWiki-generated list item is indented) around it to get valid code as the result, and  butt those tags against any preceding or following paragraph tags in the same definition. Trying to use  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  as an indent produces semantically invalid markup, which will also not validate because it is missing the  element. While this is not an enormous concern with a quick-and-dirty wikimarkup lists, it's poorly-accessible and poorly-reusable output would be a major problem for structured glossaries:

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 -"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!

The brittle list handling "bug/feature" is quite general, and also affects ordered and  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 value and accessibility of bothering to use definition list markup in the first place. Another is to a multi-paragraph definition as multiple definitions, but write the  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:, due to MediaWiki "bug/features", as shown below.

NB: Replacing  with a real  structure has no effect if   is used, or vice-versa with  and. 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  and   entirely for any case in which one intends to produce rich definition lists, including glossaries, and instead use pure HTML markup:. And there is no reason to use HTML manually to produce a glossary when the easy-to-use structured glossary templates will do this for you, and do it consistently with other glossary articles. For non-structured glossaries, use bullet lists or use subheadings and plain-text entries.

Test cases
on the same line, which is easily broken.

   term 12 1. This is the first definition.  2. This is part of the second definition. This is more of the second definition. </dd> </dl>

Success: Perfect, and supports  properly, which means it will also support , nested lists, etc.

<td style="padding-left:5px; border: 1px solid black;"> <dl> <dt>term 13</dt>
 * This is part of the definition.

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

This is more of the definition. </dl>

Failure: Only one definition indented.

<td style="padding-left:5px; border: 1px solid black;"> <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> <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>

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 <dd ></dd> wrapper, and didn't have any problem with definitions spaced apart from terms, either. This broke in late 2013.

<td style="padding-left:5px; border: 1px solid black;"> <dl> <dt>term 15</dt> <dd>1. This is the first definition. <dd> 2. This is part of the second definition. This is more of the second definition. </dd> </dl> <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> 2. This is part of the second definition. This is more of the second definition. </dd> </dl>

Success: Perfect, even with a two-fold coding error (missing  on the first definition) <td style="padding-left:5px; border: 1px solid black;"> <dl> <dt>term 16</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> <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. This is more of the second definition. </dd> </dl>


 * Vertical spacing isn't quite right, but with real paragraphs of content in place, no one would really notice or care.

<td style="padding-left:5px; border: 1px solid black;"> <dl> <dt>term 17</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> <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> 2. This is part of the second definition. This is more of the second definition. </dd> </dl>

Success: Perfect; no p markup required on single-paragraph entries.

<td style="padding-left:5px; border: 1px solid black;"> <dl> <dt>term 18</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> <dd>3. This is a third, complex definition: "With a block quotation."

Another paragraph, and Conclusion of definition 3.</dd> <dd>4. Fourth definition, with blank line
 * An embedded list
 * More list

to cause paragraph break.</dd> </dl> <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> 2. This is part of the second definition. This is more of the second definition. </dd> <dd>3. This is a third, complex definition: "With a block quotation."

Another paragraph, and Conclusion of definition 3.</dd> <dd>4. Fourth definition, with blank line
 * An embedded list
 * More list

to cause paragraph break.</dd> </dl>


 * Blockquote has too much vertical spacing between its leading and following text, but few would probably care.

<td style="padding-left:5px; border: 1px solid black;">

term A: This is the definition. term B: 1. This is the first definition. 2. This is part of the second definition. This is more of the second definition. 3. This is a third, complex definition: "With a block quotation."

Another paragraph, and Conclusion of definition 3. 4. Fourth definition, with blank line
 * An embedded list
 * More list

to cause paragraph break. term C: This is the definition.

<td style="padding-left:5px; border: 1px solid black; background-color:#9f9;">

term A: This is the definition. term B: 1. This is the first definition. 2. This is part of the second definition. This is more of the second definition. 3. This is a third, complex definition: "With a block quotation."

Another paragraph, and Conclusion of definition 3. 4. Fourth definition, with blank line
 * An embedded list
 * More list

to cause paragraph break. term C: This is the definition.

Success: Perfect – 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).

Developer views
In the process of working on the now-closed MediaWiki bug report (formerly bugzilla 1584, now tracked as ): ""Real HTML 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.""