Re: WebCrypto spec: typographic conventions ?

[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..

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.  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 note in S 3 "Conformance" that there is this statement..

   "String literals in this specification written in monospace
    font like "this" do not include the enclosing quotes."

..("this" has blue background and is monospace-regular font) but that
doesn't say anything about all the other uses of monospace fonts, unquoted
blue-background words/phrases, or ones in monospace-bold, or
monospace-bold-italics.

And this stuff brings up a couple more questions..


2. In 
<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#algor
ithm-dictionary-members>..

   11.1. Algorithm  Dictionary Members

          
            
   name

            
            
        The name of the registered algorithm to use.
            
          
        


..name is given in monospace-regular with blue-background.


However, in 
<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#key-a
lgorithm-dictionary-members>..

   12.2. KeyAlgorithm dictionary members
          

   name
            

       The name of the algorithm used to generate the CryptoKey


..this name is given in proportionalspace-bold font with no background
color. 

Yet, both the Algorithm dictionary and the KeyAlgorithm dictionary appear
to be essentially the same..

   dictionary Algorithm {
     required DOMString name
   };



   dictionary KeyAlgorithm {
     required DOMString name
   };


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?


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)

Perhaps that first paragraph in S 18.4.4. should use monospace-regular
background-blue font to denote the input parameters for the "normalize an
algorithm" algorithm.


hth,

=JeffH

Received on Tuesday, 15 December 2015 00:14:16 UTC