Re: WebCrypto spec: typographic conventions ?

On Mon, Dec 14, 2015 at 4:13 PM, Hodges, Jeff <jeff.hodges@paypal.com>
wrote:

> [please forgive and ignote my prior inadvertant posting of an unfinished
> very early draft of this msg]
>
> wrt https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html..
>

Please be aware the ED now lives on GitHub - github.com/w3c/webcrypto

http://w3c.github.io/webcrypto/Overview.html has a current version of the
draft (mod the date being out of date, oops), although a number of links
link back to the old mercurial repo and need to be fixed.


> In perusing the above-linked webcrypto spec editors' draft perhaps I'm
> just not getting it, but I'm finding it difficult to understand the
> employed typographic conventions.


W3C specs tend not to follow any terribly consistent typographic
conventions universally, due to the many different ways spec authors try to
mangle things into the W3C format.

That said, I have a hard time finding *any* W3C specification that
documents the typographic conventions employed within the spec; generally,
it's seen as syntactic sugar for understanding.


>   Perhaps part of this is because I am
> unable to find a section thoroughly describing typographic conventions.  S
> 9 "Terminology" seems to be where this might be done, but after combing
> that section and other portions of the spec I have these questions..
>
> 1. what is semantically meant by various words/phrases -- eg "true" (not
> including quotes), DataError, ""kty"" (including inner quotes) -- that are
> in monospace-regular font and have a light blue background?  These seem to
> be things that materialize in the Ecmascript world if one is developing to
> the WebCrypto API, yes?
>

I've tried to parse this question repeatedly, and I'm coming up a bit
spotty about what you're asking. The examples I could find it used should
all be obvious and seem consistent with usage in other W3C specs. Perhaps
you could elaborate on the concerns here?

If you mean "Is the doc supposed to be consistent about the typography
employed" - yes, it is, but I've done a poor job taking an editing pass on
the 16K+ line spec :(

TL;DR:
The source document tries to use <var></var> to indicate variables
described in the various (implementation/processing) algorithms,
<code></code> to refer to literals/objects/functions (whether they be
in-spec or through references to other specs), and [[]] to denote internal
object variables (consistent with ES2015-and-friends). However, I haven't
had the time to ensure everything is consistent, and not every external
reference is wrapped in <code> (DOMString, BufferSource struck as two
examples). I'm also glossing over <dfn> (which defines a term) and the <a
href>'s back to that term when it's used, and whether or not the <a> wraps
a <code>/<var> or is left as a naked <a>.

In short, inconsistency from having multiple people collaboratively editing
w/o any strict rules and doing it all in the old XML/XSL combo, rather than
ReSpec, Bikeshed, Markdown, or whatever else the new W3C hotness is :)


> Is there some subtle distinction that the different typographic treatments
> of name is attempting to signify?  if so, then documenting such
> distinctions as a function of typographic treatment would be a welcome
> addition to the spec. Otherwise, perhaps those two name attributes ought
> to have the same typographic treatment?
>

Yeah, they should have the same treatment. The underlying issue is that
https://github.com/w3c/webcrypto/blob/master/spec/Overview-WebCryptoAPI.xml#L1037
wrapped name in a <code> block, while
https://github.com/w3c/webcrypto/blob/master/spec/Overview-WebCryptoAPI.xml#L1071
didn't; see above.

>
> 3. wrt S 18.4.4. Normalizing an algorithm
> <
> https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#algor
> ithm-normalization-normalize-an-algorithm>:
>
> In the first paragraph, there is this sentence..
>
>    Its input is an operation name op and an AlgorithmIdentifier alg.
>
> ..where "op" and "alg" are proportionalspace-italics no-background-color
> font. However, it seems that the spec's convention is to (usually?)
> present algorithm input parameters in monospace-regular background-blue
> font (eg see 14.3.1. The encrypt method)
>

Does the above explanation help? The 'internal' algorithm variables are
treated as italics because they're wrapped in <var></var>, and denote
'conceptual' variables rather than literal variables (as spec conformance
is "gives the same outputs for the same inputs", and many of the internal
algorithms are notational shorthand)

Whereas the encrypt method is an IDL spec and describes literal named
variables, hence the <code></code> treatment

I think highlighting areas of inconsistency you see are great; the spec
definitely needs a typographic editing pass on it, but 'most' of it should
be consistent with the general rules clarified above.