User:Perryprog/Multi-paragraph lists

(Hey, I'm still working on this! No peeking!)

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.

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

Rendered output

Markup	Renders as
: First paragraph.<p>Second paragraph.</p>	First paragraph. Second paragraph.
* First paragraph.<p>Second paragraph.</p>	First paragraph. Second paragraph.

HTML output

Markup	Renders as
: First paragraph.<p>Second paragraph.</p>	<dl><dd>First paragraph.<p>Second paragraph.</p></dd></dl>
* First paragraph.<p>Second paragraph.</p>	<ul><li>First paragraph.<p>Second paragraph.</p></li></ul>