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

Test cases and explanation of the definition list definition (<dd>) bug.

Overview

Due to MediaWiki's very brittle handling of HTML list structures generally (in particular their inability to handle multiple paragraphs except under a very specific circumstance, outlined below), the ; and : wikimarkup features cannot be used to produce any but simplistic and easily broken definition lists, unlike real HTML. Some of the interrelated bug reports include: 1584 (unresolved as of September 2014^[update]), 5178 (unresolved as of September 2014^[update]),~~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, especially the termination of a list item by a line break. (See detailed comments in the bug reports for more information.)

Examination of the main problem

In ; and : markup, if a single definition uses multiple paragraphs, it is necessary to specify the paragraphs explicitly with a  or the full ... paragraph markup. We cannot rationally just create a second definition line for a second paragraph, as this indicates 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 must not be separated by a newline either inside or outside of the paragraph, in wikimarkup-based list items such as definitions:

;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 does not work:

;term 1 : Part of the definition of term 1. More of definition of term 1. 

and neither does this one:

;term 1
:Part of definition of term 1.
More of definition of term 1.

nor anything like them (see test cases below).

For the same reason, if a :-initiated definition requires an indented segment, one has to use use <blockquote>...</blockquote> around it to get valid code as a the result, and must butt those tags against any preceding or following paragraph tags in the same definition. Help:List's suggestion to use : as an indentor produces invalid markup. While this is not an enormous concern with a quick-and-dirty wikimarkup lists, it would be a major problem for structured glossaries.

{{gloss}} {{term|term 1}} {{defn|1=Beginning of definition. :Block quotation in definition. Conclusion of definition. }} {{glossend}}

'{{{1}}}'

term 1

Beginning of definition.
Block quotation in definition.
Conclusion of definition.

The rendered output of this looks correct to the sighted human reader, but in reality, the MediWiki parser has made the block quotation into an entire new definition list (glossary)! Wikimarkup definition list structures cannot be mixed with structured markup.

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 of bothering to use definition list markup in the first place. Another is to code a multi-paragraph definition as multiple definitions, but write the prose as if it were a single definition in two paragraphs, as already illustrated. And as already noted this just blatantly falsifies the code, 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 XHTML, among other problems, resulting in accessibility and usability issues.

To repeat: It just doesn't work, due to MediaWiki bugs/features, but there is an easy solution as show below.

NB: Replacing : with a real <dd>...</dd> structure has no effect if ; is used, or vice-versa with <dt>...</dt> and :. The entire structure must be entirely [X]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 XHTML markup: <dl>/<dt>/<dd>. 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, as recommended at WP:Manual of Style (glossaries).

Test cases

`<dl> ;term 1 :<p> This is part of the definition of term 1. </p><p> This is more of the definition of term 1. </p> </dl>`	term 1 This is part of the definition of term 1. This is more of the definition of term 1. Failure: Definitions not indented.
`<dl> ;term 2 :<p>This is part of the definition of term 2.</p> <p>This is more of the definition of term 2.</p> </dl>`	term 2 This is part of the definition of term 2. This is more of the definition of term 2. Failure: Only one definition indented.
`<dl> ;term 3 <dd> <p> This is part of the definition of term 3. </p><p> This is more of the definition of term 3. </p> </dd> </dl>`	term 3 This is part of the definition of term 3. This is more of the definition of term 3. Failure: Definitions not indented.
`<dl> ;term 4 <dd> <p>This is part of the definition of term 4.</p> <p>This is more of the definition of term 4.</p> </dd> </dl>`	term 4 This is part of the definition of term 4. This is more of the definition of term 4. Failure: Definitions not indented.
`<dl> ;term 5 <dd><p> This is part of the definition of term 5. </p><p> This is more of the definition of term 5. </p></dd> </dl>`	term 5 This is part of the definition of term 5. This is more of the definition of term 5. Failure: Definitions not indented.
`<dl> ;term 6 <dd><p>This is part of the definition of term 6.</p> <p>This is more of the definition of term 6.</p></dd> </dl>`	term 6 This is part of the definition of term 6. This is more of the definition of term 6. Failure: Definitions not indented.
`<dl> ;term 7 <dd>This is the entire definition of term 7.</dd> </dl>`	term 7 This is the entire definition of term 7. Failure: Definition not indented.
`<dl> ;term 8 <dd><p>This is the entire definition of term 8.</p></dd> </dl>`	term 8 This is the entire definition of term 8. Failure: Definition not indented.
`<dl> ;term 9 :<p>This is part of the definition of term 9.</p><p>This is more of the definition of term 9.</p> </dl>`	term 9 This is part of the definition of term 9. This is more of the definition of term 9. Poor: Indentation is typical WP style for this markup, but undesirable for proper use of the tags to create a glossary.
`<dl> ;term 10 <dd><p>This is part of the definition of term 10.</p><p>This is more of the definition of term 10.</p></dd> </dl>`	term 10 This is part of the definition of term 10. This is more of the definition of term 10. Failure: Definitions not indented.
`<dl> <dt>term 11</dt> <dd><p>This is part of the definition of term 11.</p><p>This is more of the definition of term 11.</p></dd> </dl>`	term 11 This is part of the definition of term 11. This is more of the definition of term 11. Poor: Indentation gone, but requiring `</p><p>` on the same line is undesirable.
`<dl> <dt>term 12</dt> <dd><p>This is this first definition of term 12.</p></dd> <dd><p>This is part of the 2nd definition of term 12.</p> <p>This is more of the 2nd definition of term 12.</p></dd> </dl>`	term 12 This is the first definition of term 12. This is part of the 2nd definition of term 12. This is more of the 2nd definition of term 12. Success: Perfect, and supports `<p>` properly, which means it will also support `<blockquote>`, nested lists, etc.
`<dl> <dt>term 13</dt> :<p>This is part of the definition of term 13.</p> <p>This is more of the definition of term 13.</p></dd> </dl>`	term 13 This is part of the definition of term 13. This is more of the definition of term 13. Failure: Only one definitions indented.
`<dl> <dt>term 14</dt> <dd>This is this first definition of term 14.</dd> <dd> This is part of the 2nd definition of term 14. This is more of the 2nd definition of term 14. </dd> </dl>`	term 14 This is the first definition of term 14. This is part of the 2nd definition of term 14. This is more of the 2nd definition of term 14. 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.
`<dl> <dt>term 15</dt> <dd><p>This is this first definition of term 15. <dd><p>This is part of the 2nd definition of term 15.</p> <p>This is more of the 2nd definition of term 15.</p></dd> </dl>`	term 15 This is the first definition of term 15. This is part of the 2nd definition of term 15. This is more of the 2nd definition of term 15. Successlure: Perfect, even with a two-fold coding error (missing `</p></dd>` on the first definition)

Developer views

In the process of working on the now-closed MediWiki bug report 1584:

"Real HTML <li>[...]</li> 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."