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

On Dec 8, 2004, at 10:07 AM, Bjoern Hoehrmann wrote:
>> [Definition: ...].  Mark-up should never obscure CONTENT.
>
> The "Definition:" clearly highlights the definition and the square
> brackets clearly delimit the definition from other text in the same
> paragraph.

So does any other mark-up, such as boxes or glossaries or sections
(as in the IEEE example I sent), but the others leave the in-line text
as-is (making just the term bold) so that they do not interfere with
the text surrounding the definition -- the definitions are then 
collected
and repeated automatically in a box, glossary, or Definitions section.

If you don't trust my opinion, then take it to any English writing group
and ask them what the current style means.  I say it means the contents
are editorial and can be skipped.

> This style is widely used in W3C Technical Reports and
> well-understood by the target audience; you are the first one who
> complains about it as far as I can tell; I do not agree that the
> style is "obscure" in a meaningful way. If there are going to be
> such changes, the new style should be much more usable than the old
> style. You have unfortunately not proposed a style that would.

Any style commonly used in technical writing would be better. I gave
you an example from the IEEE standards.  And, no, it is neither 
understood
nor appreciated by the target audience -- why don't you ask them?
I did and only one of the ten people I asked said it was better than
no highlighting at all.  The only reason they go along with it is 
because
they want to be consistent with W3C spec production.

I am the one bringing this issue up because, being an independent that 
is
not subject to W3C politics and group-think, I am expected to question
W3C recommendations and cause change to happen when I think they are 
wrong.


Cheers,

Roy T. Fielding                            <http://roy.gbiv.com/>
Chief Scientist, Day Software              <http://www.day.com/>

Received on Wednesday, 8 December 2004 23:06:44 UTC