User:Perryprog/Multi-paragraph lists

(Hey, I'm still working on this! (If you want to know more info about where I am with this draft, there's a few comments in the page's source about my thought process.))

Multi-paragraph replies (as in those that appear in lists on talk pages) are one of the most confounding and hard-to-understand aspects of Wikitext. There's probably over ten ways to do it, each used with varying degrees, and each with their own issues. I'm hoping this essay will help alleviate some of the confusion surrounding it by showing what HTML is emitted for each method, using both description (colon) and unordered (asterisk) lists, and what that HTML looks like to a screen reader.

TL;DR

At some point this will say what to use.

Disclaimer

It's also worth noting that I do not normally use a screen reader. I only know how to use one, as I personally find it a very valuable skill to know (and you should too ). As I do not regularly use one, it's very possible that information I give on it is wrong, inaccurate, or simply fails to mention more effective solutions that I'm not aware of due to not having built up a workflow with the software. If this is the case, then please let me know (or just fix it right away—despite being a userspace essay, I welcome any contributions, regardless of size).

Background

First off, the actual documentation on how multi-paragraph lists should be formatted is spread all over the place. Here's an overview of what's covered:

• WP:THREAD concisely covers how indentation should be done on talk pages, although it does not mention how to create multi-paragraph replies.
• The above links to the infamous MOS:LISTGAP, which does cover multi-paragraph items. It endorses using {{pb}} to indicate line breaks, and proscribes both using <br /> (for semantical reasons), as well as using a colon to match indentation levels in an unordered list.
• Oddly enough, there's yet another section, WP:INDENTGAP, directly underneath the one mentioned above. It also covers the same topic, albeit a little bit more on the technical side. It describes the issues with using a description list for indentation list (regardless of paragraphs), and also suggests putting a blank line with a preceding colon in-between paragraphs to put blank lines in indented text in articles, as well as using paragraph tags for the second paragraph and onwards:

  : First paragraph.
  :
  : Second paragraph.
  
  : First paragraph.<p>Second paragraph.</p>
  

• This then links to Wikipedia:Manual_of_Style/Glossaries/DD_bug_test_cases, which talks all about the various issues with description link from the perspective of MediaWiki's parser.
• Then there's H:LIST, which is probably the most helpful of all of these pages for this issue specifically. It suggests using <br /> for non-paragraph line breaks, <p> tags for paragraphs starting on the second paragraph and going onwards (as the code-block above shows), as well as instructions on how to continue a list item after a sub item.

Screen readers

Almost all of the problems that arise from various forms of the above examples (as well as discouraged forms that are still in heavy use) are due to the way screen readers interpret them. The screen reader I'll be using to demonstrate is VoiceOver, and I have no idea how it compares to other screen reader software like JAWS.

VoiceOver has two main methods of navigating a webpage, which it calls DOM and group mode. In my experience, either mode is helpful in differing circumstances, and typical on a per-website basis. DOM mode will allow the user to navigate directly by the order items appear in the website's HTML, while group mode is a bit more "special" in the sense that it allows the user to move directionally, based on the visual placement of the site's items. Because they differ pretty drastically, I'll be using both to show how each example is read by the screen reader, and how they change the way a user navigates a threaded reply.

Methods

Paragraph tags

Wikitext

: First paragraph.<p>Second paragraph. Signature.</p>
: <p>Same-level reply</p><p>But with a leading paragraph tag as well. Signature.</p>

Renders as

First paragraph.

Second paragraph. Signature.

Same-level reply

But with a leading paragraph tag as well. Signature.

Or with bullets instead of colons:

• First paragraph.

  Second paragraph. Signature.

• Same-level reply

  But with a leading paragraph tag as well. Signature.

HTML

<dl>
<dd>First paragraph.<p>Second paragraph.</p></dd>
<dd><p>Same-level reply</p><p>But with a leading paragraph tag as well.</p></dd>
</dl>

<ul>
<li>First paragraph.<p>Second paragraph.</p></li>
<li><p>Same-level reply</p><p>But with a leading paragraph tag as well.</p></li>
</ul>

Analysis

In DOM mode, my screen reading announces "Description list, two items" when the entire list (what's encapsulated by the <dl>...</dl> tag) is selected. Moving "forward" (as there is essentially only forward and backward in DOM mode) moves focus onto the text "First paragraph" within the first <dd>...</dd> tag, and reads "First paragraph, 1 of 2 [description list items]". Moving forward again and as expected "Second paragraph. Signature." is read. Moving forward again, we get "Same-level reply, 2 of 2" and everything else is the same. Moving forward a final time, we get "end of description list". The only difference with the bulleted list is it says "list" instead of "description list". There's a couple things to note here:

• DOM mode will essentially always read the emitted HTML from left to right. This can be both a blessing and a curse; it's especially helpful with well-formed semantical HTML that reflects its content.
• DOM mode will treat description list and bulleted lists essentially the same.
• It doesn't matter if the <p>...</p> surrounds the first paragraph—it's still a paragraph.
• Despite being a non-standard description lists (<dd>...</dd> tags must be "after dt or dd elements inside dl elements", ), the screen reader still reads it mostly normally—it's confusing initially that it's called a "description list", but not disruptively so.

In group mode, it's a bitlot different. It's a little bit tedious to describe, but the closest analogy I can think of is navigating a large set of nested folders by keyboard.