"surrounding by" vs "surrounding with" and clarity of `«»` vs `<< >>`

[TallTed]

infra/infra.bs

Lines 1553 to 1556 in 97e62b3

	<p>For notational convenience, a literal syntax can be used to express <a>lists</a>, by surrounding
	the list by « » characters and separating its <a for=list>items</a> with a comma. An indexing syntax
	can be used by providing a zero-based index into a list inside square brackets. The index cannot be
	out-of-bounds, except when used with <a for=list>exists</a>.

1. I struggle with by surrounding the list by « » characters. Though using by with the past tense surrounded is common in US English (I don't know about UK or other non-US English) phrasing, with is more commonly used with the imperative surrounding.

2. « » is not certain to be understood to mean the European quotation chevrons, officially called "guillemets", and named "Left-Pointing Double Angle Quotation Mark" (U+00AB or «) and "Right-Pointing Double Angle Quotation Mark" (U+00BB or «) in Unicode and HTML.

   These are too often typos (or read as such) for << >>, i.e., doubled angle brackets. I strongly suggest and request that the symbol names be included in at least the first instance, and preferably all instances. W3C has a specific recommended presentation of such Unicode characters which I think would be well used here, but I would be probably happy enough with WHATWG's recommended presentation, if there is one.

   (I more strongly suggest and request that WHATWG include character names and Unicode numbers, and optionally HTML escapes, in all cases where such specific characters are required (e.g., square brackets in this paragraph) in this and other WHATWG standards. Misunderstanding of non-standard character naming and/or visual presentation in some fonts/browsers/etc. is too easy even if not frequent.)

[annevk]

1. It seems fine to switch to "with" there.
2. I'm not sure I understand this. Code points is our recommendation for how to represent code points in documents, but here we are not trying to represent a code point. We are using a literal syntax to represent a list. If we used the syntax for code points it would not be understood as a list. I'm also not sure I share the general concern as often you do something with the list that makes it clear that it is a list to the reader and the reader only has to pick this up once and after that can apply this knowledge to many specifications.

[jmdyck]

Re 2, it would be reasonable to include the character names in the quoted paragraph, where the notations are being introduced. But not anywhere else, I think.

[annevk]

Ah, is that what you meant @TallTed? I agree that would make sense.

[aphillips]

FWIW, the I18N WG recommends W3C specs use a specific template when referencing specific Unicode code points (or short sequences), on first occurrence/definition. WHATWG is less consistent about doing this. You might consider adopting something similar.

[TallTed]

I was unclear.

My suggestion would be to change the above-quoted paragraph to the following, which uses the W3C i18n-WG-recommended template, and which could be copied-and-pasted into a PR:

 <p>For notational convenience, a literal syntax can be used to express <a>lists</a>,
    by surrounding the list with
    <span class="codepoint" translate="no"><bdi lang="en">&#x00AB;</bdi>
    <code class="uname">U+00AB Left-Pointing Double Angle Quotation Mark </code></span>
    and
    <span class="codepoint" translate="no"><bdi lang="en">&#x00BB;</bdi>
    <code class="uname">U+00BB Right-Pointing Double Angle Quotation Mark </code></span>
    characters, and separating its <a for=list>items</a> with commas. An indexing syntax 
    can be used by providing a zero-based index into a list inside square brackets.
    The index cannot be out-of-bounds, except when used with <a for=list>exists</a>. 

That renders (approximately, as this lacks the CSS) into the following:

For notational convenience, a literal syntax can be used to express lists, by surrounding the list with « U+00AB Left-Pointing Double Angle Quotation Mark and » U+00BB Right-Pointing Double Angle Quotation Mark characters, and separating its items with commas. An indexing syntax can be used by providing a zero-based index into a list inside square brackets. The index cannot be out-of-bounds, except when used with exists.

[annevk]

#713 addresses this. We don't follow the specific template from the i18n WG. We have a much shorter preferred syntax for code points, but we do repeat that so documents can be read in varied order.