Subject: Editorial suggestions for Atom -04

From: Norman Walsh <[email-masked]>
Date: Wed, 12 Jan 2005 07:45:56 -0500

| 1.  Introduction
| 
|    Atom is an XML-based document format intended to allow lists of

s/intended to allow/which describes/

|    related information, known as "feeds".  Feeds are composed of a

s/, known/ known/

|    [[ more motivation / design principles ]]

Recent mail on the list suggests we're closing in on our end game.
If these sections aren't going to get written, maybe it's time to
drop the place holders from the spec?

|    Any element in an Atom Document MAY have an xml:base attribute.  XML
|    Base [W3C.REC-xmlbase-20010627] processing MUST be applied to any
|    relative reference [RFC2396bis] present in an Atom Document.  This

s/relative reference/relative URI reference/

|    includes such elements and attributes as specified by Atom itself, as
|    well as those specified by extensions to Atom.
| 
|    Any element in an Atom Document MAY have an xml:lang attribute, whose
|    content indicates the default natural language of the element's

s/default //

| 3.  Common Atom Constructs
| 
|    Many of Atom's elements share a few common structures.  This section
|    defines a few such structures and their requirements, for convenient

s/, / /

| 3.2  Person Constructs
| 
|    A Person construct is an element that describes a person,
|    corporation, or similar entity.
| 
|    Person constructs MAY be extended by namespace-qualified element
|    children.
| 
|    This specification assigns no significance to the order of appearance
|    of the child elements of a Person construct.

s/of a Person/in a Person/

| 3.4  Service Constructs
| 
|    A Service construct is an empty element that conveys the URI of an
|    Atom Publishing Protocol [Atom-protocol] service associated with an
|    entry or feed.  The type of service is identified by the element name.

s/element name/element's name attribute/
| 
|    A Service construct has the following attribute:

But then the name attribute isn't described.

| 3.4.1  "href" Attribute
| 
|    The "href" attribute contains the a URI pointing to the endpoint of
|    the service named by the name attribute.  atom:service elements MUST

But then it's mentioned here. So maybe I'm confused.

|    have a "href" attribute, whose value MUST be a URI reference
|    [RFC2396bis].
| 
|    xml:base processing MUST be applied to the "href" attribute.
| 
| 3.5  Link Constructs
| 
|    A Link construct is an empty element that describes a connection from

s/describes a connection/defines a reference/

|    an Atom Document to another Web resource.
| 
| 3.5.1  "rel" Attribute
| 
|    Link constructs MAY have an optional "rel" attribute that indicates

s/an optional//

|    the link relation type.  If the "rel" attribute is not present, the
|    link construct MUST be interpreted as if the link relation type is
|    "alternate".
| 
|    rel_attribute = segment-nz-nc / URI
| 
|    The value of "rel" MUST be either a name, which is non-empty and does
|    not contain any colon (":") characters, or a URI [RFC2396bis].  Note
|    that use of a relative reference to the "rel" value URI is not

s/reference to the "rel" value URI/URI in the "rel" attribute/

|    The value "related" signifies that the URI in the value of the href
|    attribute identifies a resource to which the resource described by

s/to which/related to/

|    the containing atom:feed or atom:entry element is related.  For

s/is related.//

| 3.5.2  "type" Attribute
| 
|    Link constructs MAY have a type attribute, whose value MUST conform
|    to the syntax of a MIME media type [RFC2045].
| 
|    The type attribute's value is an advisory media type; it MAY be used
|    as a hint to determine the type of the representation which is

Suggest:

     The type attribute's value is an advisory media type; it is
     a hint about the type of the representation which is

|    expected to be returned when the value of the href attribute is
|    dereferenced.  Note that the type attribute does not override the
|    actual media type returned with the representation.

| 3.5.6  "length" Attribute
| 
|    The "length" attribute indicates an advisory length of the linked
|    content in octets; it MAY be used as a hint to determine the content
|    length of the representation returned when the URI in the href

Similarly:

     The "length" attribute indicates an advisory length of the linked
     content in octets; it is a hint about the content
     length of the representation returned when the URI in the href

|    attribute is dereferenced.  Note that the length attribute does not
|    override the actual content length of the representation as reported
|    by the underlying protocol.

| 3.6  Identity Constructs
| 
|    An Identity construct is an element whose content conveys a
|    permanent, universally unique identifier for the construct's parent.
|    Its content MUST be a URI, as defined by [RFC2396bis].  Note that the
|    definition of "URI" excludes relative references.

Replace the last sentence with "It may not be a relative URI."

| 3.7.1  The "term" Attribute
| 
|    The "term" attribute will be a string which identifies the category

s/will be a/is/

|    within the categorization scheme to which the entry or feed belongs.

s/within the categorization scheme//

| 4.2.12  "atom:info" Element
| 
|    The "atom:info" element is a Text construct that conveys a
|    human-readable explanation of the feed format itself.  atom:head
|    elements MAY contain an atom:info element, but MUST NOT contain more
|    than one.
| 
|    The atom:info element SHOULD NOT considered meaningful by processors;
|    it is a convenience to publishers in certain situations.

s/ in certain situations//

| 5.12.2  "src" attribute
| 
|    atom:content MAY have a "src" attribute, whose value MUST be a URI
|    reference [RFC2396bis].  If the "src" attribute is present, software
|    MAY use the URI to retrieve the content.  If the "src" attribute is
|    present, atom:content MUST be empty.  That is to say, the content may
|    be retrievable using "src=" URI, or it may be contained within
|    atom:content, but not both.
| 
|    If the "src" attribute is present, the "type" attribute SHOULD be
|    provided and MUST be a MIME media type [RFC2045], rather than "TEXT",
|    "HTML", or "XHTML".  The value is advisory; that is to say, upon
|    dereferencing the URI to retrieve the content, if the server
|    providing that content also provides a media type, the
|    server-provided media type is authoritative.
| 
|    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.

The last paragraph here seems oddly placed in the section about the src
attribute. I suggest moving it up to 5.12.

| 5.12.3  Processing Model
| 
|    Software MUST apply the following rules in succession in the order

s/in succession //

|    6.  For all other values of "type", the content of atom:content MUST
|        be a valid Base64 encoding [RFC3548], which when decoded SHOULD
|        be suitable for handling by software that knows the indicated
|        media type.  In this case, the characters in the Base64 encoding
|        may be preceded and followed in the atom:content element by
|        whitespace, and lines are separated by a single newline (U+000A)
|        character, as required by XML.

s/required by XML/required by XML Schema/ I think. XML doesn't say anything
about Base64 encoded content.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <[email-masked]> | Everything has been said before, but
http://nwalsh.com/            | since nobody every listens we have to
                              | keep going back and beginning all over
                              | again.--André Gide

---

From: Julian Reschke <[email-masked]>
Date: Wed, 12 Jan 2005 14:17:32 +0100

Norman Walsh wrote:
> ...

"Relative reference" is the correct terminology used in RFC2396bis.

Best regards, Julian

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