W3C home > Mailing lists > Public > spec-prod@w3.org > January to March 2005

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

From: Norman Walsh <Norman.Walsh@Sun.COM>
Date: Thu, 10 Feb 2005 09:38:59 -0500
To: spec-prod@w3.org
CC: "Roy T. Fielding" <fielding@apache.org>
Message-ID: <87oeesscn0.fsf@nwalsh.com>
(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.


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,

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.

Received on Thursday, 10 February 2005 14:39:34 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:12 UTC