[css-link-params-1] Switch to using fragment directives. #14235

Author: tabatkins

css-link-params-1/Overview.bs

@@ -23,6 +23,9 @@ spec:html; type:element
 	text: a
 spec:fill-stroke-3; type:property; text:fill
 spec:css-env-1; type:function; text:env()
+spec:scroll-to-text-fragment; type:dfn; 
+	text:fragment directive
+	text:text directive
 </pre>
 
 Introduction {#intro}
@@ -48,7 +51,8 @@ are a way to set CSS <a>custom environment variables</a> on an "external" resour
 either by a CSS property
 or thru a special fragment scheme on the URL.
 This gives a limited, but powerful, subset of the customizability that "inline" SVG images have
-to "external" SVG images.
+to "external" SVG images,
+or to other linked resources that use CSS to style themselves.
 
 A [=link parameter=] is a pair of a <<dashed-ident>> name,
 and an arbitrary (possibly empty) <<declaration-value>> value.
@@ -70,7 +74,7 @@ and an arbitrary (possibly empty) <<declaration-value>> value.
 	in several ways:
 
 	<xmp highlight=html>
-		<img src="image.svg#param(--color,green)">
+		<img src="image.svg#:~:param(--color,green)">
 	</xmp>
 
 	<pre highlight=css>
@@ -99,7 +103,7 @@ There are three ways to specify a [=link parameter=]:
 	which applies to the resource itself
 	(if the element represents an external resource),
 	and to all external resources used in CSS properties on the element
-* via a special syntax in the fragment portion of the URL of an external resource
+* via a [=fragment directive=] directly in the URL of an external resource.
 * via a ''param()'' argument in the ''url()'' syntax
 
 If specified in multiple of these ways,
@@ -108,7 +112,7 @@ for the external resource,
 in the order:
 
 1. the 'link-parameters' property on the element, if relevant
-2. the [=param()=] URL fragment identifiers
+2. the [=link parameter directives=] of the URL
 3. the ''param()'' <<url-modifier>>s in ''url()''
 
 If multiple [=link parameters=] exist with the same name,
@@ -163,33 +167,43 @@ It has the syntax:
 In The URL {#url-frag}
 ----------
 
-A special "fragment identifier" can be used in the <a for=url>fragment</a> of a URL
-used to reference an external resource.
-Several examples of existing "fragment identifiers" for SVG documents can be found in <a href="http://www.w3.org/TR/SVG/linking.html#LinksIntoSVG">the SVG 1.1 specification</a>.
+[=Link parameters=] can be passed to an external resource directly,
+as a [=fragment directive=].
 
-The syntax of an <dfn export local-lt="param()">SVG parameter fragment identifier</dfn> is:
+Note: [=Text directives=] are another example of [=fragment directives=],
+letting you link to specific text somewhere in a document.
 
-<pre class=prod>param( <<dashed-ident>> , <<declaration-value>>? )</pre>
+The <dfn export>link parameter directive</dfn> is a [=fragment directive=]
+with the following syntax:
 
-(using the <a>CSS value definition syntax</a>; TODO define an actual parser for it).
+```
+:~:param(...)
+```
+
+Where the <code>...</code> represents any sequence of URL codepoints and/or <l spec=url>[=percent-encoded bytes=]</l>.
+
+After URL-decoding, the [=link parameter directive=] is then [=CSS/parsed=] as a <<param()>>.
+If it fails to parse, the directive is ignored.
+Otherwise, it's added to the embedded document's list of link parameters,
+with a name given by the <<dashed-ident>> and a value given by the <<declaration-value>>?.
 
 <div class="example">
 	For example, to set the ''env(--text-color)'' [=custom environment variable=]
 	of an SVG image to ''blue'',
 	one can reference the image with a url like
-	“<code>http://example.com/image.svg#param(--text-color,blue)</code>”.
+	“<code>http://example.com/image.svg#:~:param(--text-color,blue)</code>”.
 </div>
 
 Multiple [=link parameters=] can be passed to an image
-by appending multiple [=param()=] fragment identifiers to the URL.
+by appending multiple [=link parameter directives=] to the URL.
 When combined, either with each other or with other "fragment identifiers",
 each value is separated with an <code>&</code> character,
 as in a URL's query parameters.
 
 <div class="example">
 	For example, if the image from the previous example also used ''env(--bg-color)'',
 	it could be referenced with a url like
-	“<code>http://example.com/image.svg#param(--text-color,blue)&amp;param(--bg-color,white)</code>”
+	“<code>http://example.com/image.svg#:~:param(--text-color,blue)&amp;param(--bg-color,white)</code>”
 	to set both ''env(--text-color)'' and ''env(--bg-color)''.
 </div>
 
@@ -205,7 +219,7 @@ Setting via the CSS ''url()'' Function {#setting-url}
 -----------------------------------------------------
 
 When referencing an external resource via CSS,
-the <a>param()</a> function can be used in the ''url()'' function.
+the ''param()'' function can be used in the ''url()'' function.
 But a common use-case is passing in values of the page's own <a>custom properties</a>;
 for example, a page might use a ''--primary-color'' <a>custom property</a>,
 and want to make an SVG image match.