RE: Editorial comments on 2 May draft of XSLT 2.0

On Mon, 2003-06-23 at 10:56, Kay, Michael wrote:
> > 
> > I'd like to make two stylistic but important points
> > about the 2 May 2003 draft of XSLT 2.0 [1].
> > 
> > 1) Some words are underlined but are not links. In the context
> >    of the Web, this can be confusing. I recommend that some
> >    other convention be used to emphasize those words. Some
> >    examples are "doc" or "collection".
> 
> These should become hyperlinks to a different document in the family of
> specs at the next version. I used the "underlined but not linked" convention
> as an editorial marker that links should be added when the target documents
> were stable enough to allow linking.

Hi Michael,

Thank you for the explanation. I apologize if I missed an
explanatory note to that effect. 

> > 
> > 2) I noted in 2.2 Notation that "An attribute is required
> >    if and only if its name is in bold." For accessibility
> >    reasons, please do not rely on style alone to convey
> >    information, especially normative information. Someone
> >    listening to the document read as synthesized speech is
> >    likely to miss this. 
> > 
> >    It's fine to highlight required attributes by using
> >    bold text, or colors, for example. But there needs to 
> >    (also) be a indication in text. 
> > 
> >    One suggestion is that in the appendix C, before 
> >    "Permitted parent elements", include a line 
> >    "Required attributes: a, b, c"
> > 
> 
> Thanks for this, a useful comment. I'm not immediately sure how best to
> address it but will try to meet your concerns.

Thank you for your consideration. One other approach
would be to use the word "required" in the prose description
of the meaning of the attribute. For instance, in 16.3.1:

 "The required name attribute specifies the name of the key."

or

 "The name attribute (required) specifies the name of the key."

 _ Ian
-- 
Ian Jacobs (ij@w3.org)   http://www.w3.org/People/Jacobs
Tel:                     +1 718 260-9447

Received on Monday, 23 June 2003 11:06:43 UTC