RE: Square-bracket output of Definition in specs is bogus

I don't know about QA but would have thought that reliance on colour 
alone would have accessibility problems.  This may seem naff, but how 
about:

  [Definition:] *Naff* means unstylish, clichéd, or outmoded.[End]

?

Misha


-----Original Message-----
From: spec-prod-request@w3.org [mailto:spec-prod-request@w3.org] On Behalf Of Norman Walsh
Sent: 10 February 2005 14:39
To: spec-prod@w3.org
Cc: Roy T. Fielding
Subject: Re: Square-bracket output of Definition in specs is bogus

(Hmm, the thread is 11 weeks old, but since I'm finally trying to catch
up on spec-prod mail...)

/ "Roy T. Fielding" <fielding@gbiv.com> was heard to say:
| The output chosen for definitions in W3C specs is easily the worst
| example of spec language abuse that I have ever seen. Definitions
| are supposed to highlighted to the reader, not placed in obscurity
| through the addition of [Definition: ...]. Mark-up should never
| obscure CONTENT.

I don't hear anyone defending the current style, so there seems to be
willingness to change. I understood the requirements to be:

1. To allow inline definitions.
2. To mark them up such that a reader using a non-GUI UA could
   identify them.

One style is:

  [Definition: some text that defines a *term*. It may go on for
  more than a single sentence.] So it's important to indicate both
  the beginning and the end.

The style Henry points to is:

  [Definition:] some text that defines a *term*. It may go on for
  more than a single sentence. So it's important to indicate both
  the beginning and the end.

The second style uses color to distinguish the extent of the definition.
I thought that the QA folks had ruled that out-of-order on the grounds
that color is not available in some UAs.

I'm not sure I completely understand Karl's suggestion, but it seems
to depend on using a Glossary at the end of the document for the definitions,
which is not consistent with the first requirement.

Perhaps it would be better if there was a glossary (I'm not convinced,
it was a royal pain to maintain for the webarch document and I don't
think it adds much), but that is not the current style and it would seem
to be a somewhat wrenching change to require one.

Questions:

a. Is there agreement on the stated requirements?
b. If so, does anyone have a suggestion that is both an improvement
   on the current style and satisfies them both?
c. Is using color to distinguish the definition from the surrounding
   text an acceptable solution?

                                        Be seeing you,
                                          norm

-- 
Norman.Walsh@Sun.COM / XML Standards Architect / Sun Microsystems, Inc.
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.



-----------------------------------------------------------------
        Visit our Internet site at http://www.reuters.com

Get closer to the financial markets with Reuters Messaging - for more
information and to register, visit http://www.reuters.com/messaging

Any views expressed in this message are those of  the  individual
sender,  except  where  the sender specifically states them to be
the views of Reuters Ltd.

Received on Thursday, 10 February 2005 14:59:58 UTC