Upgrade guide: Add more details to the jQuery 3.5 upgrade guide

The commit adds information about jQuery Migrate 3.3.0+ logging of
non-compliant HTML input. It also explicitly states the common example
of using a single auto-closing tag works even in jQuery 3.5.0+.

There are also tweaks in other places.

Closes gh-202

Co-Authored-By: Dave Methvin <[email protected]>

Author: mgol

pages/upgrade-guide/3.5.md

@@ -11,6 +11,8 @@ If you want to upgrade to jQuery 3.5.0 or newer and don't have time to deal with
 jQuery.UNSAFE_restoreLegacyHtmlPrefilter();
 ```
 
+jQuery Migrate 3.3.0 or newer logs warnings for all input that's affected by this change, regardless of whether the `jQuery.UNSAFE_restoreLegacyHtmlPrefilter()` method was called or not. **Note**: if you overwrite `jQuery.htmlPrefilter` manually, you'll lose those warnings!
+
 If you don't use jQuery Migrate, don't add it just for this one workaround. Instead, you can revert to the previous behavior by redefining `jQuery.htmlPrefilter` after loading jQuery:
 ```js
 var rxhtmlTag = /<(?!area|br|col|embed|hr|img|input|link|meta|param)(([a-z][^\/\0>\x20\t\r\n\f]*)[^>]*)\/>/gi;
@@ -38,7 +40,7 @@ would create the following structure:
 ```
 because `<div/>` was replaced with `<div></div>` & `<span/>` with `<span></span>`.
 
-jQuery 3.5.0 has changed `jQuery.htmlPrefilter` to be an identity function. That means that the above `jQuery` call would now create above HTML structure only in XML mode of HTML (called also as XHTML) but in regular HTML mode you would now get:
+In jQuery 3.5.0, the `jQuery.htmlPrefilter` method always returns its argument unchanged. Modern browsers usually parse and render HTML strings in HTML mode. Elements such as `<p>` and `<span>` are never self-closing in HTML, so the browser interprets a string like `<p/><span/>` as `<p><span>` and leaves the tags open. The browser closes the tags at the end of the string or at an element that cannot be contained in the element, so another `<p>` tag closes an existing open `<p>` tag.
 ```html
 <div>
 	<span></span>
@@ -55,3 +57,9 @@ do this:
 ```js
 jQuery( "<div></div><img/>" );
 ```
+
+One popular input that still works in jQuery 3.5.0 or newer is the one with a single tag with or without attributes:
+```js
+jQuery( "<div class='yellow' />" );
+```
+This is becuse it's XHTML-compliant and in HTML the parser first changes it to just the opening tag: `<div class='yellow'>` but then immediately auto-closes it as it reaches the end of input.