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

Le 06 déc. 2004, à 16:24, Roy T. Fielding a écrit :
> I suggest that the W3C ask a literature department (like Harvard or 
> Chicago)
> what they think such a style document says to a typical reader, and 
> perhaps
> suggest a more useful signage for definitions that actually calls them 
> out
> in a normative way that doesn't cause experienced technical writers to 
> go
> into fits of perplexity.  For example, here is the style for IEEE 
> specs:

That's a good suggestion.

They are a few details to clarify.

* What is a definition?
	We define a lot of things in a specification and one would consider 
that everything which is normative is a definition. Another one would 
say that it's only testable assertions which are true definitions. And 
I believe for most of the editors and WGs now is to define terms which 
might belong to a glossary. And I assume it's what we intend here.

* The XMLSpec markup to create definition.

For example from:
http://www.w3.org/TR/2004/REC-xml-20040204/REC-xml-20040204.xml
http://www.w3.org/TR/2004/REC-xml-20040204/Overview.html

* XML Version
<termref def="dt-xml-doc">XML documents</termref>

and

<termdef id="dt-xml-doc" term="XML Document"> A data
object is an <term>XML document</term> if it is
<termref def="dt-wellformed">well-formed</termref>,
as defined in this specification. A well-formed
XML document <rfc2119>MAY</rfc2119> in addition
be <termref def="dt-valid">valid</termref> if it
meets certain further constraints.</termdef>


* HTML Output Version
<a title="XML Document" href="#dt-xml-doc">XML documents</a>

[<a name="dt-xml-doc" id="dt-xml-doc"
title="XML Document">Definition</a>:  A data object
is an <b>XML document</b> if it is <a
title="Well-Formed" href="#dt-wellformed">well-formed</a>,
as defined in this specification. A well-formed XML
document <em class="rfc2119" title="Keyword in
RFC 2119 context">MAY</em> in addition be <a title="Validity"
href="#dt-valid">valid</a> if it meets certain further
constraints.]

COMMENT: My first problem with output even before the square brackets 
is… the use of the element "b" to notify an important word. It should 
be the element "strong", IMHO.
	<term>something</term>
		----> <strong>something</strong>
or even
	<term>something</term>
		----> <strong class="term">something</strong>

I agree that the use of brackets seems completely inappropriate in this 
context and another problem is that it doesn't seem that it helps to 
make a real list of definitions. Square brackets are also used in 
***English*** usually in quotations to add additional information, 
which is less important. For an appropriate example of square brackets:

	Roy Fielding said “The output chosen for definitions
	in W3C specs is easily the worst example of spec language
	abuse [sic] that I have ever seen.”


* The XHTML/HTML markup to create definition.

For the XHTML output, I would encourage (considering the same example):

For the inline mention of the term.
<dfn title="XML Document"><a href="#dt-xml-doc">XML documents</a></dfn>

And for the final glossary, wrapped with all other defined terms in a 
"dl" element

<dl id="glossary" title="Glossary of XML specification">
[…]
<dt id="dt-xml-doc">XML Document</dt>
	<dd>A data object is an <strong class="term">XML
	document</strong> if it is <a title="Well-Formed"
	href="#dt-wellformed">well-formed</a>, as defined in
	this specification. A well-formed XML document <em
	class="rfc2119" title="Keyword in RFC 2119
	context">MAY</em> in addition be <a title="Validity"
	href="#dt-valid">valid</a> if it meets certain further
	constraints.</dd>
[…]
</dl>

* The visual rendering of the  definition (which is easy to achieve.)
	Some manual of style suggests that it should be in Small Caps, others 
warn that italics might be a problem if there are words in italics in 
the definition itself, others to let it as normal text.
	I would have to explore a bit more, but it's only a question of CSS 
rules.

* The semantics re-use of definitions in a specification.
	Why I have used dfn and dl, dt, dd, becase these elements have real 
semantics in HTML and then it defines a possible usage by a semantic 
extractor, a search engine which would compile definitions, etc. It 
will help also projects like the W3C Glossary.


-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***