[whatwg] Feeedback on <dfn>, <abbr>, and other elements related to cross-references

Sun Apr 20 15:26:46 PDT 2008

HTML5 had a complex mechanism for cross-references using <dfn>, <abbr>, 
, and so forth. I've removed it. It really didn't add much compared to 
<a href=""> other than a whole lot of complexity, and there was very 
little demand for it really. I've also made the title="" attribute on 
<abbr> required, and updated a bunch of examples.

Further comments and changes discussed below.

On Tue, 23 Aug 2005, fantasai wrote:
>
> # The paragraph, definition list group, or section that contains the dfn
> # element
> # contains the definition for the term given by the contents of the dfn
> # element.
> 
> <section>
>   <dl>
>     <dt>foo</dt>
>     <dd><p>Some text... A <dfn>bar</dfn> is ...</p>
>         <p>And so on</p>
>     </dd>
>   </dl>
> </section>
> 
> So which is the definition: the paragraph, the definition list group, or 
> the section? Or do we not know?

We don't know. They all contain the definition, though, which is what the 
spec said. That sentence has been changed to be a requirement now.

On Fri, 14 Oct 2005, Lachlan Hunt wrote:
>
> Just a few issues regarding the use of abbr and dfn elements.
> 
> *The abbr Element's title Attribute*
> 
> I think the title attribute should also be allowed to be omitted from 
> the abbr element if there is another abbr element with a title attribute 
> for the same abbreviation in the document.  This would be very useful 
> for cases where the same abbreviation is used multiple times, but is not 
> defined (using <dfn>) anywhere in the document.

Why would that instance not use <dfn>?

> *Multiple Definitions for the Same Term*
> 
> What happens if there are multiple definitions for the same 
> abbreviation?  For example, if the same abbreviation has two different 
> expansions given with two different meanings.  Which one would an <abbr> 
> element without a title attribute be associated with?

Right now the spec doesn't associate anything together anymore. You need 
explicit <a href> links to make the associations.

> *Definitions with Links*
> 
> If the dfn element contains a hyperlink, as in either:
>   <dfn><abbr><a href="">HTML</a></abbr></dfn>
> or
>   <dfn><a href=""><abbr>HTML</abbr></a></dfn>
> 
> it should be defined as being as a link to either the term's definition or
> supplementary information about the term and/or its defintion.
> 
> For example, a paragraph may contain a simple definition for the term with the
> link to the Wikipedia entry for more information.
> 
> <p><abbr title="..."><a
> href="http://en.wikipedia.org/wiki/HTML">HTML</a></abbr> is a semantic
> language for marking up documents published on the web.</p>

It seems like we'd want to allow, e.g., a link to a list of instances of 
the term.

I have defined the opposite, though (links to a <dfn> element are links 
from instances of that term).

On Mon, 7 Nov 2005, Sander Tekelenburg wrote:
>
> At <http://www.whatwg.org/specs/web-apps/current-work/#dfn0> it says
> 
> 	[...] any [...] element that has a non-empty title attribute whose value
> 	exactly equals the term of a dfn element [...] should be presented in such a
> 	way that the user can jump from the element to the first dfn element giving
> 	the defining instance of that term.
>
> [...]

The above is gone altogether now.

On Fri, 13 Jan 2006, Eugene T.S. Wong wrote:
> 
> I read the specification on <DFN>, and I really like it. Previously, I 
> had never thought about using it; partly because I never really made any 
> help-documentation with semantic HTML, and partly because I never really 
> understood the usefulness of it.
> 
> Some manuscripts will need to refer to a <DFN> that is on another page. 
> Will there be a way of doing that?

Now that the cross-referencing is done just using <a>, yes.

On Fri, 13 Jan 2006, Eugene T.S. Wong wrote:
> 
> That would require making an ID for the element. How would users and 
> developers access definitions without an ID?

You can't.

> If a document by another author contains 100 web pages, and <DFN>s 
> contain no ID, then there is no way of creating an index of all the 
> <DFN>s. I suppose that this is an extreme scenario, but what if the 
> author doesn't create 100 web pages, and still decides to not use IDs? 
> How do we link to it, if we write our own documents?

You can't, I guess. Ask the author to add IDs.

> Perhaps we should allow for something like: <A 
> HREF="mypage#'DHD'>click</A> or <A HREF="mypage#'dial home 
> device'>click</A>.
> 
> Another problem is that if we use IDs, then we end up replicating 
> information. For example:
> 
> <P>asdf asdf <DFN ID="dialhomedevice"><ABBR TITLE="Dial Home 
> Device">DHD</ABBR></DFN> QWER QER.</P>
> 
> We could use shorter IDs, but that doesn't change my point. If we do 
> that, then <DFN> begins to loose a lot of its value. The idea is that 
> DFN is supposed to be some kind of reference point that we can all point 
> to without having to use IDs. If that isn't true, then there isn't 
> really any use for it, because it would be no different than <SPAN 
> ID="id-of-dfn">foo</SPAN>.
> 
> What do you think?

I agree with the idea, but I think the complexity is probably too high 
given the relatively low level of demand.

On Sat, 14 Jan 2006, Lachlan Hunt wrote:
> 
> That looks like an attempt to redefine how fragment identifiers work for 
> HTML and XML documents, which is out of scope for this spec.

Not that far out of scope. :-)

On Sat, 14 Jan 2006, Sander Tekelenburg wrote:
> 
> Just a thought: perhaps applicable elements (those with a non-empty 
> title attribute) could have an optional src attribute containing a URL 
> to the remote document?
> 
> <p>Teal'c activated his <abbr title="Dial Home Device" 
> src="http://www.whatwg.org/specs/web-apps/current-work/">DHD</abbr> and 
> so Hammond ordered the iris to be opened.</p>

This is the kind of thing that made me realise we were reinventing the 
wheel here.

On Sat, 14 Jan 2006, Simon Pieters wrote:
> 
> I believe that the XPointer string-range function could be used:
> 
>   <a href="otherpage.html#xpointer(string-range(//dfn/abbr,"DHD")[1])">DHD</a>
> 
> I'm not sure that the syntax is correct, but in any case, this issue is 
> covered by XPointer.
> 
> http://www.w3.org/TR/xptr-xpointer/#stringrange

On Sat, 14 Jan 2006, Sander Tekelenburg wrote:
> 
> But XPointer looks like it might be more realistic. I wasn't aware of it 
> until just now. Is it being implemented in any user-agents already?

It seems not, at least not widely.

On Fri, 13 Jan 2006, Eugene T.S. Wong wrote:
> 
> In the following example, the user should be able to go to the picture 
> of the DHD, or the definition of the DHD.
> 
> <p>The <dfn><abbr title="Dial Home Device">DHD</abbr></dfn>
> is a device that allows off-world teams to open the iris.</p>
> <!-- ... later in the document: -->
> <p>Teal'c activated <a href="PicOfDHD">his <abbr title="Dial Home
> Device">DHD</abbr></a>
> and so Hammond ordered the iris to be opened.</p>
> 
> Perhaps right clicking on the text should give the user an indication 
> that there is a definition available, or perhaps the UA should be 
> automatically place an image/icon to indicate that there is a definition 
> available. In the above example, typical user agents would display "his 
> DHD" with an underline by default, and then maybe place an image after 
> "DHD". This image would be clickable. Perhaps the UA could place an 
> overline over "DHD" as well. If there are no conflicts, then the UA 
> wouldn't need to display the icon/image & overline.
> 
> Comments? Questions?

I think it's simpler to just have two links and be done with it. e.g.:

   <p>Teal'c activated the <a href="#dhd"><abbr>DHD</abbr></a> (<a 
   href="dhd.jpeg">picture</a>).</p>

On Fri, 13 Jan 2006, Eugene T.S. Wong wrote:
> 
> On a slightly unrelated note, the spec says, "should be presented in 
> such a way that the user can jump from the element to the first dfn 
> element giving the defining instance of that term".

This is gone now.

On Tue, 21 Mar 2006, Christoph Paeper wrote:
>
> | 2.9.8. The |dfn| element
> 
> | The |dfn| element enables automatic cross-references. Specifically,
> | any |span|, |abbr|, |code|, |var|, |samp|, or |i| element that has a
> | non-empty |title| attribute whose value exactly equals the [term] of a
> | |dfn| element in the same document, or which has no |title| attribute
> | but whose |textContent| exactly equals the [term] of a |dfn| element
> | in the document, and that has no [interactive elements] or |dfn|
> | elements either as ancestors or descendants, and has no other
> | elements as ancestors that are themselves matching these conditions,
> | should be presented in such a way that the user can jump from the
> | element to the first |dfn| element giving the defining instance of
> | that term.
> 
> Despite being a quite complex description already, should or rather may this
> include definitions in documents referenced inside the document by a |link|
> element instance of |rel| "glossary"?

This is now moot, since it's gone.

> Why should the following example not work?
> 
>   <p>The <dfn><abbr title="Dial Home Device">DHD</abbr></dfn>
>   is a device that allows off-world teams to open the iris.</p>
>   <!-- ... later in the document: -->
>   <p>Teal'c activated his <abbr>DHD</abbr> and so Hammond ordered
>   the iris to be opened.</p>
> 
> IOW, I think the special case of an |abbr| with |title| (and perhaps 
> some other element types that assign special semantics to this 
> attribute) inside a |dfn| should generate to [term]s, one for the 
> abbreviation and one for the expanded form. I consider repeating 
> |title|s on |abbr|s excessive markup.

You would have written it as:

The <dfn><abbr>DHD</abbr></dfn> (Dial Home Device) is a..

Teal'c activated the <abbr>DHD</abbr>...

That is, the <abbr> element could only have its expansion omitted if the 
abbreviation has been defined. Otherwise, the reader had no way to know 
what the abbreviation stands for.

At least, that's the theory... I guess one would have expect edthis to be 
ok too:

The <dfn title="Dial Home Device"><abbr>DHD</abbr></dfn> (Dial Home 
 Device) is a..

Teal'c activated the <abbr>DHD</abbr>...

...and would _not_ have expected this to be ok:

The <dfn title="Dial Home Device"><abbr>DHD</abbr></dfn> is a...

Teal'c activated the <abbr>DHD</abbr>...

...which is kind of a mess... I've removed the confusion here by simply 
requiring the title="" attribute on <abbr>. The point of the element is to 
provide expansions for abbreviations, not to satisfy the compulsion needs 
of semanticists. :-)

On Fri, 27 Oct 2006, Simon Pieters wrote:
> 
> I notice that what was previously the <i> element is now the <x> 
> element. [1]
> 
> I realize that <x> is shorter than <span>. I don't think it's useful to 
> have both to work with <dfn>. I suggest either make <span> don't work 
> with <dfn> or drop <x>.
> 
> I also think <x> should exclusively represent a cross-reference, and not 
> be used for e.g. phrases in foreign languages in general. (I'd use <i> 
> for that.)

Pretty much none of what you talk about here is left. :-)

On Wed, 1 Nov 2006, Christoph Päper wrote:
>
> First off I think the requirement for a |title| is too strict, because 
> there are time and space saving abbreviations everyone knows -- i.e. 
> either their expansion or their meaning -- that do not need an 
> expansion, e.g. "e.g." or "AIDS". Therefore the second sentence should 
> use 'may', not 'should'. Maybe there could be a mechanism using |link| 
> to external abbreviation glossaries, which may use |dl| instead of 
> |dfn|. (I have kind of a deja-vu here, like I already proposed that 
> sometime somewhere.)

Not sure which second sentence you mean, but for the record, you don't 
have to mark up all abbreviations. If they're known, don't bother.

> 1.
>   <abbr>i. e.</abbr>
>   <abbr>i.e.</abbr>
>   <abbr>ie.</abbr>
>   <abbr>ie</abbr>
> (That's out of the scope of the specification of course.)

Well, you shouldn't use <abbr> without defining what the abbreviation is.

> 2.
>   <abbr>i. e.</abbr>
>   <abbr title="id est">i. e.</abbr>
>   <abbr title="that is">i. e.</abbr>

The middle one is the right one, if you insist on using <abbr> for this.

> 3.
>   <abbr ... lang="la">i. e.</abbr>
>   <abbr ... lang="en">i. e.</abbr>

Either is fine, since i.e. is part of the english language now.

> If you cannot answer 2. and 3. the definition of |abbr| is broken, but I
> expect either of these:
>   <abbr title="id est" lang="la">i. e.</abbr>
>   <abbr title="that is" lang="en">i. e.</abbr> (or inherited language)

i.e. is not an abbreviation for "that is".

> This is a more expressive solution, but also harder to implement:
> 
>   <link rel="abbr glossary" href="abbr.html">
>   ...
>   <abbr>i. e.</abbr>
> 
> abbr.html:
>   <dl>
>     <di><dt lang="la">i. e.</dt>
>         <dd lang="la">id est</dd><dd lang="en">that is</dd></di>

I don't really know what we're trying to solve here. The problem is people 
not knowing what "i.e." means was solved long ago, using dictionaries.

On Wed, 1 Nov 2006, Michel Fortin wrote:
> 
> There are plenty of better reasons to omit title. I can think of three 
> right know:
> 
> What if the author doesn't know what an abbreviation stands for? It 
> could be a fictional abbreviation, or it could be an author asking his 
> readers for the meaning of this particular abbreviation.

Then don't use <abbr>. :-)

> What if the author does not want to disclose the meaning of the 
> abbreviation? The meaning could be a question in a quiz.

Don't use <abbr> either. :-) (For this one, use .)

> And what if the abbreviation has two meanings at the same time? For 
> instance, how would you markup the first CSS acronym of the second 
> paragraph here: <http://people.opera.com/howcome/2002/dvd/index.html>

I wouldn't use <abbr> here either.

The point of <abbr> is to expand the acronym, not to just mark up what is 
an acryonym or abbreviation. It's pretty obvious what is an acronym or 
abbreviation. :-)

> There are legitimate reasons to not fill up the title attribute of 
> <abbr>. Or should <abbr> be disallowed in these situations?

I've disallowed it.

On Thu, 2 Nov 2006, Matthew Paul Thomas wrote:
> 
> > I disagree. There is never a guarantee that people will know what an 
> > abbreviation stands for, I know what AIDS is but not what it stands 
> > for.
> 
> But that applies not just to abbreviations, but to writing in general. 
> All writing assumes a level of knowledge. If a blind biologist listening 
> to a scientific journal heard "DNA" expanded as "deoxyribonucleic acid" 
> on every page, that would quickly become infuriating, even if the UA was 
> smart enough to do it for only the first occurrence on each page. 
> (Temporarily turning off such expansions would be unreasonable if there 
> were other, unfamiliar, abbreviations present; and trying to request 
> expansions from the UA case-by-case would be tiresome.)

Why? I would expect one to have to request the expansions when one wanted 
them. That's how visual users have to interact with <abbr>, too.

> I use <abbr title="that is">i.e.</abbr> not just because that's what it 
> means, but because that's how it *should* be expanded if it needs to be 
> expanded, for example if it is being read aloud. (Expanding it as "id 
> est" would be pretentiously unreasonable.)

Why wouldn't you just read it "eye-ee"?

> Similarly in "Mac <abbr>OS</abbr> <abbr title="10">X</abbr>", I don't 
> give "<abbr>OS</abbr>" a title=, because what "OS" stands for is never 
> relevant in the context.

Why give it an <abbr> at all?

On Thu, 2 Nov 2006, James Graham wrote:
> 
> I agree, unless using <abbr> with no title is useful to get the correct 
> rendering of abbreviations in non-visual media. I guess e.g. aural 
> browsers must cope with rendering of abbreviations like PET and DNA 
> without needing explicit markup, but I think knowing this sort of thing 
> is important in determining the wording of the spec.

Right, speech synthesis has progressed enough that <abbr> isn't really 
going to be a huge help anyway; and it's more likely than not to be 
omitted when it's needed anyway.

On Thu, 2 Nov 2006, Lachlan Hunt wrote:
> 
> Using <abbr> without a title would be useful if it automatically 
> referred to a previous instance with the title attribute.
> 
> e.g.
> 
> You could mark up the first occurance as like this
> 
>   <abbr title="As Far as I Know">AFAIK</abbr>
> 
> Then, later in the document, you could use it without the title attribute
> 
>   <abbr>AFAIK</abbr>
> 
> and a UA could allow the user to discover the expansion.  This idea is 
> already somewhat supported in the current draft, but requires that it 
> references the defining term of a previously marked up <dfn>, rather 
> than just another occurrence of the same abbreviation.  IMHO, that part 
> of the spec needs fixing.

I've actually removed this altogether. It didn't really seem compelling, 
and nobody seems to have tried implementing this experimentally anyway.

On Tue, 28 Nov 2006, Michel Fortin wrote:
> 
> > There must only be one <dfn> element per document for each term 
> > defined (i.e. there must not be any duplicate terms).
> 
> So, according to the spec, using <dfn> to identify multiple definitions 
> of the same term is wrong. But what if there is actually two definitions 
> for the same term in the text? And what if it's two identical words in 
> two different languages?

Removed that requirement.

On Fri, 1 Dec 2006, Simon Pieters wrote:
> 
> The dfn element:
> 
>   The dfn element represents the defining instance of a term.
>   The paragraph, definition list group, or section that contains
>   the dfn element contains the definition for the term given
>   by the contents of the dfn element.
> 
> Given the definition of "defining term" two paragraphs later, the term 
> of the dfn element is not always the contents of the element.

Fixed.

On Mon, 26 Mar 2007, Simon Pieters wrote:
>
> The current draft of HTML5 has an automatic cross-reference feature with 
> the span, abbr, code, var, samp, and i elements, which would point to a 
> matching <dfn> element.
> 
>    http://www.whatwg.org/specs/web-apps/current-work/#the-dfn
> 
> The current design has a number of problems [...]

It's gone now.

> So. The proposal here is to replace the current xref design with a 
> boolean attribute "xref" on the span, abbr, code, var, samp, and i 
> elements, that, when present, makes the element a cross-reference to a 
> <dfn> element with a matching term. (What is a term is already defined 
> in the spec, and is fine.)

To solve even more problems, I just made <a href="#foo"> and id=foo the 
way to do cross-references. This has the advantage of working already...

On Mon, 26 Mar 2007, Nicholas Shanks wrote:
> 
> I don't see tens of thousands of web developers crying out for this kind 
> of feature. Is it really necessary or is it just delaying and bloating 
> the spec?

It's gone now.

On Tue, 21 Aug 2007, Edward O'Connor wrote:
> 
> Currently, the only elements which work with dfn automatic 
> cross-referencing are <span>, <abbr>, <code>, <var>, <samp>, and <i>.[1] 
> I'd like to suggest adding <strong> to that list.
> 
> My specific use-case is the use of RFC 2119 terms in HTML. My
> boilerplate looks like this:
> 
> <p>
>   The key words "<dfn>MUST</dfn>", "<dfn>MUST NOT</dfn>",
>   "<dfn>REQUIRED</dfn>", "<dfn>SHALL</dfn>", "<dfn>SHALL NOT</dfn>",
>   "<dfn>SHOULD</dfn>", "<dfn>SHOULD NOT</dfn>",
>   "<dfn>RECOMMENDED</dfn>", "<dfn>MAY</dfn>", and "<dfn>OPTIONAL</dfn>"
>   in this document are to be interpreted as described in <a
>   href="http://www.ietf.org/rfc/rfc2119.txt"
>      rel="help glossary">RFC 2119</a>.
> </p>
> 
> Later in the text, I'd like to be able to say things like "Conforming 
> processors <strong>MUST</strong> frobnicate the widget vigorously," and 
> have the dfn association happen.

Use <a>. :-)

> Secondly, I notice that the "glossary" link relation has been dropped. I 
> found it useful in the boilerplate above, and for other cases where a 
> document uses external definitions, such as what I imagine Christoph had 
> in mind in [2], and Eugene in [3].
> 
> 2. http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2006-March/006101.html
> 3. http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2006-January/005404.html

If I recall correctly, rel=glossary was dropped on the principle that 
hardly anybody used it, UAs didn't show it, and users didn't care.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'