W3C home > Mailing lists > Public > public-html@w3.org > July 2007

Re: (marks, definitions, terms, abbreviations, and variables <m>, <dfn>, <abbr>, <term>) part of my review of 3.12 Phrase elements

From: Robert Burns <rob@robburns.com>
Date: Thu, 26 Jul 2007 16:39:21 -0500
Message-Id: <6474A37C-84F7-4D69-BBCF-1ED95F74C61F@robburns.com>
Cc: public-html WG <public-html@w3.org>
To: Smylers <Smylers@stripey.com>


On Jul 26, 2007, at 4:02 PM, Smylers wrote:

>
> Robert Burns writes:
>
>> Defining terms, abbreviations and
>>     variable (DFN, ABBR, VAR) for the current draft:
>> ----------------------------------
>> Consider changing the current draft for DFN to:
>> proposed new language/
>> Defining term:
>> A) If the dfn element has a title attribute, then the exact value of
>> that attribute is the term being defined. If the author includes a
>> value for the title attribute to indicate the term, the element must
>> be empty. [otherwise, we should specify what precisely the meaning of
>> the enclosed text is]
>
> I do not think it must be empty; I think the content, like the content
> of nearly all elements in HTML, should be what the author wishes to
> display to the user.  This could be used where the structure of a
> sentence means that the term being defined is being used in its
> non-canonical form.  For example:
>
>   The departmental <dfn title="poet">poets</dfn> are the people  
> who ...
>
> or:
>
>   <dfn title="frobincate">Frobnicating</dfn> is the process of ...
>
> I'm also wondering if it could be used when the content is presented
> with an image or something:
>
>   <dfn title="The Artist Formerly Known as Prince">
>     <img src="squiggle.png" alt="The Artist Formerly Know as Prince">
>   </dfn> is a famous ...

Those are great examples. As I said in the review "otherwise, we  
should specify what precisely the meaning of
the enclosed text is". I think those examples do that very well. We  
should include them in the draft along with your sentiment you  
expressed with: "where the structure of a sentence means that the  
term being defined is being used in its non-canonical form."

>
>> Consider changing the first (only) example to:
>> In the following fragment, the term "GDO" is first defined in the
>> first paragraph, then used in the second. A compliant UA must provide
>> a mechanism to present the definition ...
>
> What's your justification for changing the requirement to "must"  
> there?
> An author marking up the text in this way enables a user-agent to  
> choose
> to provide such an interface, but does it make sense to force all  
> user-
> agents to implement such?  Is it indeed appropriate for all types of
> user-agents?
>
> An interface like this is only a convenience for a reader; since the
> contents of <dfn> elements are displayed distinctively, it's still
> possible for a reader to scroll to and read the relevant definition
> without any extra assistance from the browser.  Can't we let browser
> creators decide on the appropriate level of convenience for their
> software?
>
> (Though if we do decide this is a "must", then its "must"-iness needs
> defining in a normative part of the text, not merely in an example; I
> think changing the "should" in the paragraph preceding the example  
> would
> achieve this.)

Perhaps this should be narrowed to browser UAs or something along  
those lines to make it clear that non-browsers do not have to  
necessarily do that. I don't see a problem with requiring a feature  
like that (and leaving the exact mechanism up to the browser). You  
can reduce all of this to a level of convenience if you like. A text  
reader like "more" is a browser in that sense in that I can read the  
source of an HTML5 document. It's just no very convenient. Even an  
app that displayed the raw bytes would just be a less convenient  
browser. I think part of making features of HTML5 useful involves  
specifying certain requirements for UAs that will then make the extra  
work of coding this worthwhile for both users and authors. Not that  
this is necessarily and accessibility issue, but I see many of the  
problems surrounding the HTML accessibility facilities related to the  
problem of under specifying requirements for authors and UAs. It  
leaves the proper usage and intent of the facilities rather nebulous:  
leaving both authors and UAs unwilling and unsure of how to use the  
facilities. I think this same issue affects DFN and the related  
attributes and elements.

>> ... from the immediately next surrounding structural-inline ancestor
>> or block ancestor of the dfn element, whichever occurs first.
>
> That would contradict what the normative text say is the definition of
> the term: "the paragraph, description list group, or section that
> contains the dfn element".

Perhaps it does. I'm not totally clear what the sentence you quote  
means. I was trying to provide normative prose that would be clearer  
and more precise. Perhaps you could say a little more about how it  
contradicts the current text and we can find clearer language that  
does not contradict what's there.

>> Consider providing examples for the other two state/cases mentioned
>>
>> <p>A <dfn>fundamental class process</dfn> is a process of performing
>> and appropriating surplus labor. It occurs at the point of production
>> between a performer of surplus labor and the appropriator of that
>> surplus labor.</p>
>> <!-- ... later in the document: -->
>> <p> The <span title='fundamental class process' >fundamental class
>> process</span> is therefore a condition of existence for the subsumed
>> class process. </p>
>>
>> <p>A <dfn>class</dfn> is a a factory for objects. It defines all of
>> the methods for accessing the instance variable data for an object as
>> well as defining the constructor that stamps out new instances of the
>> object. represented by this class.  .</p>
>> <!-- ... later in the document: -->
>> <p>For a <span title='class' >class</span> to be highly reusable,
>> developers should focus their attention on opportunities for
>> polymorphism.</p>
>
> I don't object to more examples, but it seems to be that those two
> examples demonstrate exactly the same construct and sage as each  
> other.

OK. I think the examples you gave are better. I didn't find the draft  
clear enough on this to even provide a relevant example. Now from  
you're email, I'm beginning to understand. The two examples you gave  
above would be perfect there.

> Also, in neither of those cases do the <span> elements need those  
> title
> attributes; since the title is merely repeating the textContent, it  
> can
> be ommitted and the textContent will be used instead.

OK. I didn't understand from the current draft that the text matching  
would make use of the contents of any <span> element. I still think  
this is a case that should involve a newly specified semantic element  
(TERM). However, it sounds like the current draft makes us of SPAN in  
much the same way. It may be even more important then to use a new  
element since it might provide a performance optimization to focus on  
only TERM, ABBR and VAR elements instead of all SPAN elements too.

>> The VAR element makes mention of special meaning to @title when used
>> with DFN but nothing else is said about that here.
>
> Yes there is: the paragraph between the note and the example starts:
>
>   The dfn element enables automatic cross-references.   
> Specifically, any
>   span, abbr, code, var, samp, or i element that ...

As I said: "but nothing else is said about that here." Emphasis on  
the "here". It would be best for the draft to include the same  
description on SPAN, ABBR, CODE, VAR, I and SAMP (or whatever  
elements we include in this basket). The recommendation will often be  
used as a reference document. Authors will look at these elements and  
not necessarily look at DFN to see how to use VAR (for example).  
Again, my preference would be for us to provide the missing semantic  
element in this list TERM and skip the I and SPAN (perhaps skip CODE  
and SAMP too since it's not clear from the draft how authors would  
provide a definition for the contents of those elements).


>> An example and explanation would be helpful. (is this meant to match
>> the @title of the defining dfn element for the variable?).
>
> Exactly the same as with <span>.

Again, the draft should include brief mention of that in each of the  
subsections.

Take care,
Rob
Received on Thursday, 26 July 2007 21:39:44 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 9 May 2012 00:16:02 GMT