Subject: Autodiscovery Draft Issues

From: Lachlan Hunt <[email-masked]>
Date: Wed, 29 Nov 2006 16:38:34 +1100

Hi,
   This feedback is related to the autodiscovery draft.

Before reading on, I suggest anyone writing a specification of any kind 
actually learn a little about how to write good conformance criteria.

http://ln.hixie.ch/?start=1140242962&count=1

I do not believe it is at all useful for this spec to continue as either 
normative or informational.  If it were to be published as 
informational, who would it's target audience be?  What benefit would it 
provide to anyone?  What purpose would it serve?

James M Snell wrote:
> To document best practice as it relates specifically to syndication
> feeds.

It's not entirely clear what that actually means.  How would it be any 
different from, or more useful than, existing documentation on the 
subject that has been around for the past 3 or 4 years.

What we do need is a normative specification that clearly defines both 
document and user agent conformance requirements, and that really has to 
be in a normative specification.  The only issue that then remains is 
where this should take place and, for reasons documented later in this 
e-mail, I strongly believe that HTML5 is the correct place for this to 
be defined.

> For example, HTML5 says nothing about whether the relative order 
> of feed autodiscovery links within a document is significant.  The Atom 
> autodiscovery draft, however, defines that the order is significant.

That can be considered a limitation of the HTML5 spec which can be 
addressed there.  In fact, at the time of writing this, you've already 
raised the issue on the WHATWG list and it looks like its been resolved.

Note: The rest of this feedback is written as though this spec were 
still going to be published as a normative RFC, despite the suggestion 
that it be published as an informational item only or not at all. 
That's because I had most of it written before that suggestion and it's 
useful feedback anyway.

Feed autodiscovery should ideally be defined independent of the 
syndication feed format.  It is illogical to have a separate 
autodiscovery spec for Atom [1] and RSS [2].  As far as autodiscovery is 
concerned, the only difference between these and any other format is the 
MIME type.  But, if this spec is to continue, it should at least be 
renamed to "Syndication Feed Autodiscovery" or similar.

*Introduction*

The introduction should discuss the use of Atom, RSS and RDF Site 
Summary because they're all widely used and are relevant to anyone 
implementing autodiscovery.  I suggest it also talk about the generic 
concept of what a syndication feed is (independent of the syntax) and 
only refer to Atom, RSS and RDF as examples.

*Notational Conventions*

This section should be titled "Conformance Requirements".  It should 
make a clear distinction between user agent conformance and document 
conformance, and clearly explain the requirements for each.

If there are separate categories of user agents, then they should be 
defined here.  For instance, a conformance checker would have different 
requirements from a web browser.  e.g. A conformance checker must report 
errors to a user, whereas as a web browser isn't required to do so and 
may recover gracefully, in the way defined by the specification (where 
applicable).

It should state something like the following to define which sections 
are normative and non-normative.

   All examples and notes in this specification are non-normative, as are
   all sections explicitly marked non-normative. Everything else in this
   specification is normative.

*Defintion of an autodiscovery element*

This should be moved to a separate definitions section (perhaps within 
the previous conformance requirements section).  It does not belong in 
the Relationship to HTML and XHTML section.  The definitions should also 
include other terms used throughout the spec, which are then used in the 
conformance requirements (see the writing specifications article linked 
above).

| An Atom autodiscovery element is a link element, as defined in
| section 12.3 of HTML 4 [W3C.REC-html401-19991224].

Assuming this section is normative, that reference should be normative 
also.  Throughout the spec, it should also refer to it as just an 
"autodiscovery element" (see above about it not just being for Atom).

I do not agree that only <link> elements should be used for 
autodiscovery.  Since visible meta data is always better than invisible 
meta data, documents should be allowed to use the <a> element as well.

| As with other types of link elements, an autodiscovery element MAY
| appear within the <head> element of an HTML or XHTML document,

Why is that requirement only stated as a *MAY*?  It should be a *MUST* 
requirement and it should be made clear that this is a document 
conformance requirement only.

| but it MUST NOT appear within the <body>.

For document conformance, I agree.  But, UA conformance requirements 
also need to be defined.  What must a UA do if it finds a link element 
in the body?  This error is actually far more common than you may think.

As part of a study of several billion pages done by Ian Hickson in 
September this year, it was found that "Parse error: link element start 
tag out of place." was the 32nd most common error and happened for about 
1 in 8 documents, on average.  That means in roughly 12.5% of pages, the 
link element occurred in the body.

The study was similar to the Web Authoring Statistics [3] published by 
Google in January (also done by Ian Hickson), but with a significantly 
larger sample and much more data collected.

In HTML5 (which is based upon the way several browsers have already 
implemented HTML), regardless of where the link tag occurs in the 
serialisation, each link element is still inserted into the head.  So, 
strictly speaking, it is impossible for a link element to appear in the 
body in HTML, though the tag could appear anywhere the author put it.

For example, if that were not the case and the link was not inserted 
into the head regardless of where it occurred, consider the following 
test case.  Is the link considered to be in the head or not?

<head>
<title>Autodiscovery</title>
<script type="text/javascript">
document.write("<p>test<\/p>");
</script>
<link rel="alternate" type="application/atom+xml" href="/feed" />
</head>

The answer actually depends upon whether or not script is enabled.  If 
it's disabled, then the answer is yes.  Otherwise, when the p element 
written to the serialisation, it implies the end of the head and the 
beginning of the body, and so the answer is no.  That is actually the 
behaviour of IE7, but not Firefox, Opera or Safari.

*Relationship to HTML and XHTML*

*Syntax rules inherited from HTML*

This significantly limited, informative list of syntax requirements, if 
included, should be non-normative.  Instead, the spec should normatively 
refer to an HTML spec which clearly defines the syntax and parsing 
requirements for conforming user agents.

However, if HTML 4.01 is chosen, then as far as the SGML parsing is 
concerned, HTML 4.01 cannot be implemented in the real world.  No web 
browser does and I seriously doubt any existing tools that implement 
autodiscovery do so either.

I would strongly recommend that you normatively reference HTML5 for the 
parsing requirements, which is far more relevant than HTML 4.01 is. 
However, even though the relevant parts of the parsing section are 
relatively stable, the spec itself is not, which is a problem because 
because it's not usually a good idea to normatively reference a moving 
target.

To do so would make HTML5 a dependency, but it's difficult to progress 
any specification that has such unstable dependencies.  In other words, 
this would technically be held up by the progress of HTML5 anyway.  So, 
therefore, it doesn't really make sense for this to defined separately 
from HTML, particularly when it actually is an HTML feature itself.

*Syntax rules inherited from XHTML*

Again, this significantly limited, informative list of syntax 
requirements, if included, should be non-normative.  Instead, the spec 
should normatively reference the XML 1.0 and XHTML 1.0 specs which 
clearly define the syntax and parsing requirements.

*The rel attribute*

| The rel attribute MUST be present in an Atom autodiscovery element.
| As defined in section 6.12 of HTML 4 [W3C.REC-html401-19991224], the
| value of the rel attribute is a space-separated list of keywords.

That's another example of a normative reference to HTML4.  In this case, 
it's ok to reference HTML4 for the definition of the rel attribute, but 
HTML5's definition would be better.

| The list of keywords MUST include the keyword "alternate" in
| uppercase, lowercase, or mixed case.

That's a reasonable example of a document conformance requirement, 
though I'd suggest it be rephrased:

   The list of keywords MUST include the keyword "alternate".  The value
   is case-insensitive.

It is also missing user agent conformance requirements, but they would 
be covered by a normative reference to the HTML spec that defines how to 
process the rel attribute.  There's an edge case that should be covered. 
  e.g.

<link rel="alternate stylesheet" type="application/atom+xml" href="/feed">

In HTML, the combination of alternate and stylesheet has special 
meaning.  Yet the type attribute still has the atom MIME type.  Does 
that still represent an autodiscovery link?  If so, that should be 
defined and it is currently an interoperability issue.  (Note: This 
looks like it's also a problem with the HTML5 spec at the moment)

I believe the feed value should also be specified in this section, as it 
is in the WHATWG spec.  Primarily because a syndication feed isn't 
necessarily an alternative representation of the page, as clearly 
demonstrated in the mozilla.org example shown in an earlier post today.

*The type attribute*

The definition of this should also include the value 
"application/rss+xml".  This is because of the above reasons about it 
not just being for Atom and because UAs already have to support it as well.

*The href attribute*

The defintion of this is very good.  It contains both document and user 
agent conformance requirements.  No further comments.

*Multiple autodiscovery elements*

| * Each autodiscovery element SHOULD point to a different Atom feed.

What must a UA do if multiple links point to the same feed?

| * Each autodiscovery element SHOULD include a title attribute that
|   gives a human-readable label for the feed that the element points
|   to.  Clients MAY use these titles to present a list of available
|   Atom feeds to the end user.

That "MAY" in the last sentence should be at least a "SHOULD", but 
probably not a "MUST" in case a UA has a good reason not to show it.

| * The order of the autodiscovery elements is significant.  The first
|   element SHOULD point to the publisher's preferred feed for the
|   document.
| * Clients who present a list of autodiscovered feeds to the end user
|   SHOULD present them in the same order as the autodiscovery
|   elements appear in the document.
| * Clients who wish to choose exactly one feed without user input
|   SHOULD choose the one pointed to by the first autodiscovery
|   element.

This section is quite good, but there are a few issues.  What if the 
first one is an unsupported format?  e.g. the first is RSS, the second 
is Atom, and the UA only supports Atom.  Since it's a SHOULD, UAs can 
technically do that, but this stuff should be explicitly defined.

What if the link elements has an hreflang attributes, indicating 
alternate languages for the feeds.  Say the first is "en", the second 
"fr", and ther user has configured "fr" as their preferred language. 
UAs should choose the first one provided in the user's preferred language.

*Examples*

I left comments about the examples section before [4].  Those comments 
still stand.

[1] 
http://www.ietf.org/internet-drafts/draft-snell-atompub-autodiscovery-00.txt
[2] http://www.rssboard.org/rss-autodiscovery
[3] http://code.google.com/webstats/
[4] http://www.imc.org/atom-syntax/mail-archive/msg19103.html

-- 
Lachlan Hunt
http://lachy.id.au/