Subject: I-D ACTION:draft-ietf-atompub-format-05.txt

From: [email-masked]
Date: Thu, 27 Jan 2005 15:53:31 -0500

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Atom Publishing Format and Protocol Working Group of the IETF.

	Title		: The Atom Syndication Format
	Author(s)	: M. Nottingham, R. Sayre
	Filename	: draft-ietf-atompub-format-05.txt
	Pages		: 37
	Date		: 2005-1-27
	
This document specifies Atom, an XML-based Web content and metadata
   syndication format.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-05.txt

To remove yourself from the I-D Announcement list, send a message to 
[email-masked] with the word unsubscribe in the body of the message.  
You can also visit https://www1.ietf.org/mailman/listinfo/I-D-announce 
to change your subscription settings.

Internet-Drafts are also available by anonymous FTP. Login with the username
"anonymous" and a password of your e-mail address. After logging in,
type "cd internet-drafts" and then
	"get draft-ietf-atompub-format-05.txt".

A list of Internet-Drafts directories can be found in
http://www.ietf.org/shadow.html 
or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

Internet-Drafts can also be obtained by e-mail.

Send a message to:
	[email-masked].
In the body type:
	"FILE /internet-drafts/draft-ietf-atompub-format-05.txt".
	
NOTE:	The mail server at ietf.org can return the document in
	MIME-encoded form by using the "mpack" utility.  To use this
	feature, insert the command "ENCODING mime" before the "FILE"
	command.  To decode the response(s), you will need "munpack" or
	a MIME-compliant mail reader.  Different MIME-compliant mail readers
	exhibit different behavior, especially when dealing with
	"multipart" MIME messages (i.e. documents which have been split
	up into multiple messages), so check your local documentation on
	how to manipulate these messages.

Below is the data which will enable a MIME compliant mail reader
implementation to automatically retrieve the ASCII version of the
Internet-Draft.

---

From: Robert Sayre <[email-masked]>
Date: Thu, 27 Jan 2005 16:10:06 -0500

Hi all,

Valid format-04 feeds are valid format-05 feeds.

Known issues:
* Order of appearance in Element Definitions
* Cardinality requirement for atom:content appears in the wrong location.

URIs:

http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html
http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.txt

and the not particularly useful

http://atompub.org/2005/01/27/draft-ietf-atompub-format-05-from-4.diff.html

Robert Sayre

---

From: Danny Ayers <[email-masked]>
Date: Fri, 28 Jan 2005 15:14:58 +0100

> http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.txt

Thanks Robert. The Relax NG snippets make a *huge* difference to the
clarity. (Thanks Norm!).

> http://atompub.org/2005/01/27/draft-ietf-atompub-format-05-from-4.diff.html

Aw, but it's much prettier...

Cheers,
Danny.

-- 

http://dannyayers.com

---

From: Danny Ayers <[email-masked]>
Date: Fri, 28 Jan 2005 15:14:58 +0100

Cheers,
Danny.

-- 

http://dannyayers.com

---

From: Henry Story <[email-masked]>
Date: Fri, 28 Jan 2005 15:34:19 +0100

> Thanks Robert. The Relax NG snippets make a *huge* difference to the

Yes. A real pleasure to read now :-)

---

From: Julian Reschke <[email-masked]>
Date: Sun, 30 Jan 2005 21:21:07 +0100

Hi,

first I'd like to thank the editors for the good work.

The issues were collected after reading the spec top-to-bottom, and 
trying to produce an Atom-05 feed from an existing RSS-1.0 feed through 
XSLT. Most of them are editorial.

Best regards,

Julian

-- snip --

05-C01, 1.2 Example

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.1.2>

Inconsistencies:

- version attribute (whitespace)
- "rel" attribute is missing

05-C02, 3.1.1, "type" attribute

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.3.1.1>

Suggested examples for TEXT, HTML and XHTML: a title containing the 
string "Less: <", where the less sign displays emphasized when possible..

<atomTitle type="TEXT">
   Less: &lt;
</atomTitle>

<atomTitle type="HTML">
   Less: &lt;em> &amp;lt; &lt;/em>
</atomTitle>

<atomTitle type="XHTML" xmlns:xhtml="http://www.w3.org/1999/xhtml">
   Less: <xhtml:em> &lt; </xhtml:em>
</atomTitle>

(hope I got these right).

05-C03, 3.1.1, "type" attribute

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.3.1.1>

"The content SHOULD be XHTML text and markup that could validly appear 
directly within an xhtml:div element."

Add reference to XHTML1 
(<http://www.w3.org/TR/2002/REC-xhtml1-20020801>), section A).

05-C03, 4.3, atom:head

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.3>

'The version identifier for this specification is 
"draft-ietf-atompub-format-05: do not deploy"'

Spelling of the version attribute inconsistent with section 4.1.1.

05-C04, 4.11 atom:host

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.11>

Like others, I'm not sure I understand what this is for. I think one 
sentence of rational would make the spec easier to absorb.

05-C04, 4.15.2 atom:content

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.15.2>

Like others, I find the syntactic impact of allowing it either to be 
in-line or out-of-band confusing. I don't feel strongly about this, but 
using two distinct XML elements instead might make things easier.

"If the value of type begins with "text/" or ends with "+xml", the 
content SHOULD be local; that is to say, no "src" attribute should be 
provided."

I'm not sure I understand what this is for. It seems to discourage 
putting XML data out-of-band. Why?

05-C05, 4.15.3 processing model

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.15.3>

"If the value of "type" ends with "+xml" or "/xml", the content of 
atom:content may include child elements, and SHOULD be suitable for 
handling by software that knows the indicated media type. If the "src" 
attribute is not provided, this would normally mean that the 
"atom:content" element would contain a single child element which would 
serve as the root element of the XML document of the indicated type."

The statement about the "src" attribute seems to be unnecessary given 
the SHOULD-level requirement to have local content (thus no "src" 
attribute).

"If the value of "type" begins with "text/" the content of atom:content 
MUST NOT contain child elements."

See 4.15.2: so is this a SHOULD or a MUST?

05-C06, B RelaxNG schema

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.B>

I tried to use the schema to validate a feed that I generated and had 
the following problems:

- my version of trang (20030619) didn't accept the Schematron rules -- 
what else do I need to use RNC as reprinted?

- the namespace name doesn't match the current one

05-E01, todos

For instance:

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.1.p.4>

Recommend to do them using rfc2629bis's "cref" element.

05-E02, Notational Conventions

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#W3C.REC-xml-infoset-20011024>

Should't we refer to <http://www.w3.org/TR/2004/REC-xml-infoset-20040204/>?

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#RELAX-NG>

I think this should come with the following URL: 
<http://www.oasis-open.org/committees/relax-ng/spec-20011203.html>

05-E03, Notational Conventions

"A collected schema appears in an informative appendix."

(refer directly by section/appendix number). Same for some other 
intra-document references.

05-E04, Atom Documents

"... relative reference [RFC2396bis] present in an Atom..."

RFC2396bis has been published as RFC3986.

05-E05, 3.2.2 atom:uri

"The content of atom:uri in a Person construct MUST be a URI reference 
[RFC2396bis]."

Directly point to RFC3986's section (here: 4.1).

05-E06, 3.2.3 atom:email

"Its content MUST be an e-mail address [RFC2822]."

Again, please refer directly to the definition. In this case, it seems 
to be section 3.4.1 (addr-spec production).

05-E07, 4.2 atom:head

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.2>

"The atom:head element MAY contain any namespace-qualified 
[W3C.REC-xml-names-19990114] elements as children."

I think we're overdoing it here a bit and loose readability. I suggest 
to remove the reference or move it to the end of the sentence.

05-E08, 4.6.2 rel attribute

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.6.2>

If we use (A)BNF syntax, the spec needs to say so and reference the 
definition normatively (for instance, RFC2234).

"...same name registered within the IANA Registry of Link Relations 
Section 9, and..."

Put the section reference into brackets.

05-E09, 4.6.3 type attribute

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.6.3>

"Link elements MAY have a type attribute, whose value MUST conform to 
the syntax of a MIME media type [RFC2045]."

Add pointer into RFC2025 (I believe: section 5.1)

05-E10, 4.19 atom:tagline

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.19>

On reading this, it's not obvious to me how this is different from a 
atom:title element. One sentence of explanation (or even inclusion in 
the example) would be helpful.

05-E11, 9 IANA considerations

Something is wrong with the references to RFC3023 (sometimes they appear 
twice, one time even three times in a row).

05-E12, 11 references

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.references>

Here's a procedural question: if we have normative references to the 
protocol and the feed discovery documents, the spec won't get published 
until those are done, too. Is everybody aware of that?

---

From: Tim Bray <[email-masked]>
Date: Sun, 30 Jan 2005 12:47:12 -0800

On Jan 30, 2005, at 12:21 PM, Julian Reschke wrote:
> trying to produce an Atom-05 feed from an existing RSS-1.0 feed 
> through XSLT. Most of them are editorial.

Good stuff, Julian.

> putting XML data out-of-band. Why?

It does.  The idea is that textual content is more valuable if it's 
right there in the feed than if you have to go elsewhere to get it. 
-Tim

---

From: Julian Reschke <[email-masked]>
Date: Sun, 30 Jan 2005 22:03:41 +0100

>> through XSLT. Most of them are editorial.

Thanks.

> right there in the feed than if you have to go elsewhere to get it. -Tim

I agree that this is the case, but does that require a SHOULD-level 
requirement? Explaining the issue instead of just trying to enforce it 
may lead to better results...

Best regards, Julian

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

---

From: Robert Sayre <[email-masked]>
Date: Sun, 30 Jan 2005 17:53:00 -0500

>  - version attribute (whitespace)

Will fix.

>  - "rel" attribute is missing

The rel attribute is optional and the relation is considered to be 
"alternate" in that case.
http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rel_attribute

>  <atomTitle type="TEXT"> Less: &lt; </atomTitle>
>
>  <atomTitle type="HTML"> Less: &lt;em> &amp;lt; &lt;/em> </atomTitle>
>
>  Less: <xhtml:em> &lt; </xhtml:em> </atomTitle>
>

Nice, thanks.

>
>
>  "The content SHOULD be XHTML text and markup that could validly
>  appear directly within an xhtml:div element."
>
>  Add reference to XHTML1

I think mnot just fixed this for -06.

>  Spelling of the version attribute inconsistent with section 4.1.1.

Will fix.

>  sentence of rational would make the spec easier to absorb.

Will try to fix.

>  in-line or out-of-band confusing. I don't feel strongly about this,
>  but using two distinct XML elements instead might make things easier.
>
>

I agree with statements you made in another email on this. I agree that 
we should try to explain the difference, so people like Graham can point 
to it when someone expects the two methods to behave identically.

>  handling by software that knows the indicated media type. If the
>  "src" attribute is not provided, this would normally mean that the
>  "atom:content" element would contain a single child element which
>  would serve as the root element of the XML document of the indicated
>  type."
>
>  "If the value of "type" begins with "text/" the content of
>  atom:content MUST NOT contain child elements."
>

It's a MUST, and not an editorial change.

>  - my version of trang (20030619) didn't accept the Schematron rules
>  -- what else do I need to use RNC as reprinted?
>

I left the Schematron rules in, but I'm not sure I should have. This is 
kind of tricky, because the ISO standard covers schematron, and Relax NG 
XML syntax. There's an update coming to cover the compact syntax, but I 
don't know if it covers schematron annotations (which are comments, in 
any case, right?), or if it will be done in time for us.

>  - the namespace name doesn't match the current one

Will fix.

>  Recommend to do them using rfc2629bis's "cref" element.

Will look into it.

>
>
>  Should't we refer to
>  <http://www.w3.org/TR/2004/REC-xml-infoset-20040204/>?
>

mnot has already fixed this.

>  <http://www.oasis-open.org/committees/relax-ng/spec-20011203.html>

I don't want to refer to OASIS's URLs.

>  intra-document references.

OK.

>  RFC2396bis has been published as RFC3986.

Oops, I adjusted this reference right before I submitted it, but forget 
to get the web page. Now you know why the IETF has these pesky rules...

>
>  05-E05, 3.2.2 atom:uri
>
>  "The content of atom:uri in a Person construct MUST be a URI
>  reference [RFC2396bis]."
>

OK.

>  Again, please refer directly to the definition. In this case, it
>  seems to be section 3.4.1 (addr-spec production).
>

OK.

>  I think we're overdoing it here a bit and loose readability. I
>  suggest to remove the reference or move it to the end of the
>  sentence.
>
>

Will fix.

>  Put the section reference into brackets.

Will fix.

>  Add pointer into RFC2025 (I believe: section 5.1)

I think you just mean point to the section. Will do.

>  the example) would be helpful.

Will try.

>  Something is wrong with the references to RFC3023 (sometimes they
>  appear twice, one time even three times in a row).
>

Already fixed.

>  protocol and the feed discovery documents, the spec won't get
>  published until those are done, too. Is everybody aware of that?

Yep.

Robert Sayre

---

From: Sam Ruby <[email-masked]>
Date: Sun, 30 Jan 2005 18:32:44 -0500

> (hope I got these right).

This is not only right, but also a good example of why many people would 
prefer to have another element so that they don't have to deal with 
prefixes:

   <atomTitle type="XHTML">
     <div xmlns="http://www.w3.org/1999/xhtml">Less: <em> &lt; </em></div>
   </atomTitle>

The above is "similar" to your example, but not _identical_ to your 
example, given the current spec.

- Sam Ruby

---

From: Henri Sivonen <[email-masked]>
Date: Mon, 31 Jan 2005 09:58:18 +0200

On Jan 31, 2005, at 01:32, Sam Ruby wrote:

> This is not only right, but also a good example of why many people 
> would prefer to have another element so that they don't have to deal 
> with prefixes:

Their serializer should deal with them. If they are concatenating 
source strings, using XHTML is risky.

> example, given the current spec.

You could also have
<atom:title type="XHTML" xmlns="http://www.w3.org/1999/xhtml">
   Less: <em> &lt; </em>
</atom:title>
(assuming the "atom" prefix to be bound higher up)

-- 
Henri Sivonen
[email-masked]
http://iki.fi/hsivonen/

---

From: Henri Sivonen <[email-masked]>
Date: Mon, 31 Jan 2005 09:58:35 +0200

> I don't want to refer to OASIS's URLs.

Why not? Will ISO-Relax NG be available on the Web free of charge? 
Specs that are available free of charge on the Web win.

-- 
Henri Sivonen
[email-masked]
http://iki.fi/hsivonen/

---

From: Julian Reschke <[email-masked]>
Date: Mon, 31 Jan 2005 10:02:46 +0100

Thanks for the feedback, Robert...

> http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rel_attribute

<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.2.p.4>:

'atom:head elements MUST contain at least one atom:link element with a 
rel attribute value of "alternate".'

> It's a MUST, and not an editorial change.

If it's a MUST then 
<http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.15.2.p.3> 
needs to be adjusted.

> I don't want to refer to OASIS's URLs.

Why not? Aren't they considered to be stable?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 31 Jan 2005 09:56:08 +0100

> example, given the current spec.

Well, the current spec absolutely allows people to stick in the div 
element. It just doesn't require them to do it.

Best regards, Julian

---

From: Robert Sayre <[email-masked]>
Date: Mon, 31 Jan 2005 08:05:36 -0500

Henri Sivonen wrote:
> Why not? Will ISO-Relax NG be available on the Web free of charge? Specs 
> that are available free of charge on the Web win.
> 

I wish that were true. We'll probably be told what to do anyway, so 
there's no point in debating it.

Robert Sayre

---

From: Robert Sayre <[email-masked]>
Date: Mon, 31 Jan 2005 07:37:09 -0500

> rel attribute value of "alternate".'

Point taken. How about 'atom:head elements MUST contain at least one 
atom:link element with a relation of "alternate".'

> <http://atompub.org/2005/01/27/draft-ietf-atompub-format-05.html#rfc.section.4.15.2.p.3> 

You're correct, but the WG should decide which sentence will change.

> Why not? Aren't they considered to be stable?

I couldn't find any standards track documents that reference them. I 
guess we could link it up in the HTML document, but note that the W3C 
docs are linked either.

Robert Sayre

---

From: Julian Reschke <[email-masked]>
Date: Mon, 31 Jan 2005 15:05:01 +0100

> atom:link element with a relation of "alternate".'

Can't we just get rid of the defaulting? That would make the spec 
simpler with little additional verbosity in the instance documents.

> guess we could link it up in the HTML document, but note that the W3C 

For instance <http://www.w3.org/TR/xhtml2/references.html#ref_RELAXNG> 
and <http://greenbytes.de/tech/webdav/rfc3470.html#RELAX-NG>.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 31 Jan 2005 15:21:36 +0100

Robert Sayre wrote:
> In this case, my preference would be for the spec to define the 
> inevitable, but the WG should decide. If the WG decides to leave 
> attribute defaulting, would the text above be sufficient?

Yep.

> LOL. It's probably OK if that one does it. But... the first document is 
> a W3C spec. The second is a BCP, not a standards track document. We'll 
> probably be told what to do anyway.

True. I'd prefer us to try to get the URL in (with the risk to be told 
to take it out) rather non trying at all.

Best regards, Julian

---

From: Robert Sayre <[email-masked]>
Date: Mon, 31 Jan 2005 09:13:54 -0500

Julian Reschke wrote:

> Robert Sayre wrote:
>
>>> 'atom:head elements MUST contain at least one atom:link element with 
>>> a rel attribute value of "alternate".'
>>
>>
>>

Robert Sayre

---

From: Tim Bray <[email-masked]>
Date: Mon, 31 Jan 2005 07:31:47 -0800

> Specs that are available free of charge on the Web win.

Indeed.  And what's wrong with OASIS URL's? -Tim

---

From: Tim Bray <[email-masked]>
Date: Mon, 31 Jan 2005 07:35:21 -0800

On Jan 31, 2005, at 4:37 AM, Robert Sayre wrote:

>> <http://atompub.org/2005/01/27/draft-ietf-atompub-format 
>> -05.html#rfc.section.4.15.2.p.3> needs to be adjusted.

Huh?  What's the issue?  I just stared at that text for a couple of  
minutes and didn't get it. -Tim

---

From: Julian Reschke <[email-masked]>
Date: Mon, 31 Jan 2005 16:48:07 +0100

> minutes and didn't get it. -Tim

As far as I understand the spec, 4.15.2 (last sentence) says it's a 
SHOULD, 4.15.3 (5.) says it's a MUST.

I think the fact that both sections say something about the same thing 
is the problem that needs to be fixed.

Best regards, Julian

---

From: Henri Sivonen <[email-masked]>
Date: Mon, 31 Jan 2005 18:44:35 +0200

> simpler with little additional verbosity in the instance documents.

If there is no default, someone will still omit the attribute and 
consumers will try to cope. I think it is better if they cope in the 
same way normatively.

-- 
Henri Sivonen
[email-masked]
http://iki.fi/hsivonen/