Expand introductory text and examples

spec.bs

@@ -92,12 +92,54 @@ table {
   top: -0.8em;
   left: -0.8em;
 }
+
+/* props from https://resources.whatwg.org/standard.css */
+dl.props { display: grid; grid-template-columns: max-content auto; row-gap: 0.25em; column-gap: 1em; }
+dl.props > dt { grid-column-start: 1; margin: 0; }
+dl.props > dd { grid-column-start: 2; margin: 0; }
+p + dl.props { margin-top: -0.5em; }
 </style>
 
 <script src="https://resources.whatwg.org/file-issue.js" async></script>
 
 <h2 id=urlpattern-class>The {{URLPattern}} class </h2>
 
+A {{URLPattern}} consists of several [=components=], each of which represents a [=/pattern string|pattern=] which could be matched against the corresponding component of a [=/URL=].
+
+It can be constructed using a string for each component, or from a shorthand string. It can optionally be resolved relative to a base URL.
+
+<div class="example">
+  The shorthand "`https://example.com/:category/*`" corresponds to the following components:
+
+  <dl class="props">
+    :  [=protocol component|protocol=]
+    :: "`https`"
+    :  [=username component|username=]
+    :: ""
+    :  [=password component|password=]
+    :: ""
+    :  [=hostname component|hostname=]
+    :: "`example.com`"
+    :  [=port component|port=]
+    :: ""
+    :  [=pathname component|pathname=]
+    :: "`/:category/*`"
+    :  [=search component|search=]
+    :: ""
+    :  [=hash component|hash=]
+    :: ""
+  </dl>
+
+  It matches the following URLs:
+  * `https://example.com/products/`
+  * `https://example.com/blog/our-greatest-product-ever`
+
+  It does not match the following URLs:
+  * `https://example.com/`
+  * `http://example.com/products/`
+  * `https://example.com:8443/blog/our-greatest-product-ever`
+</div>
+
 <xmp class="idl">
 typedef (USVString or URLPatternInit) URLPatternInput;
 
@@ -833,6 +875,18 @@ To <dfn>compute protocol matches a special scheme flag</dfn> given a [=construct
 
 A <dfn>pattern string</dfn> is a string that is written to match a set of target strings.  A <dfn for="pattern string">well formed</dfn> pattern string conforms to a particular pattern syntax.  This pattern syntax is directly based on the syntax used by the popular [path-to-regexp](https://github.com/pillarjs/path-to-regexp) JavaScript library.
 
+It can be [=parse a pattern string|parsed=] to produce a [=/part list=] which describes, in order, what must appear in a component string for the pattern string to match.
+
+<div class="example">
+  Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (`/` in the pathname, `.` in the hostname). For example, the pathname pattern "`/blog/:title`" will match "`/blog/hello-world`" but not "`/blog/2012/02"`.
+
+  A regular expression can also be used instead, so the pathname pattern "`/blog/:year(\\d+)/:month(\\d+)`" will match "`/blog/2012/02`".
+
+  A group can also be made optional, or repeated, by using a modifier. For example, the pathname pattern "`/products/:id?"` will match both "`/products`" and "`/products/2`" (but not "`/products/`"). In the pathname specifically, groups automatically require a leading `/`; to avoid this, the group can be explicitly deliminated, as in the pathname pattern "`/products/{:id}?"`.
+
+  A full wildcard `*` can also be used to match as much as possible, as in the pathname pattern "`/products/*`".
+</div>
+
 <h3 id=parsing-patterns>Parsing Patterns</h3>
 
 <h4 id=tokens>Tokens</h4>