Subject: PaceXhtmlDivSuggestedOnly

From: Thomas Broyer <[email-masked]>
Date: Sat, 30 Apr 2005 16:43:01 +0200

I'm aware that this Pace actually has two purposes: nuke the xhtml:div 
requirement and add distinction between inline and block content. If 
someone wants me to split it into two Paces, I'll do it, but I think 
these two purposes are related to each other and that's why I made a 
single Pace.

http://intertwingly.net/wiki/pie/PaceXhtmlDivSuggestedOnly

== Abstract ==

Make the XHTML div wrapper optional, as it causes more problems than it 
actually solves.

== Status ==

Open

== Rationale ==

The only purpose of the XHTML div wrapper is to have it carry the XHTML 
namespace declaration in case the feed producer doesn't want to use 
prefixed XML names (i.e. always use default namespaces). The required 
wrapper is also expected to prevent feeds using wrong namespaces.

On the other hand, there has been many discussion about which attributes 
are allowed/forbidden on the wrapper and how they should be handled by 
Atom processors, without a clear and clean solution.

Using a XHTML "div" element is also quite inappropriate in an atom:title 
element as a "div" is meant for block content whereas a title is merely 
expected to be used as inline content (e.g. by putting it inside an "h2" 
or "h3" XHTML element). This has no technical impact in the current spec 
as the div is not part of the content but it might disturb 
XHTML-friendly people.

Finally, mandating a "foreign" (outside the Atom namespace) element but 
requiring it not being part of the content and not behaving as it would 
in its originating language (XHTML) is not a clean position: so is this 
element part of Atom or XHTML?

== Proposal ==

Nuke the XHTML div requirement and adds distinction between inline and 
block content to help producers choose the best container for their 
content (div or span).

This means making the following changes/addition to the 
draft-ietf-atompub-format-08 document.

=== section 3.1 ===

Change the {{{atomXHTMLTextConstruct}}} definition to this one: {{{
    atomXHTMLTextConstruct =
       atomCommonAttributes,
       attribute type { "xhtml" },
       (text
        | anyXHTML)*
}}}

And add the following paragraph: {{{
    This specification further refines the Text construct depending on
    the kind of content that is expected. A Text constructs expecting
    inline content is further named Inline Text construct, whereas a
    Text construct expecting block content is named Block Text construct.
}}}

=== section 3.1.1.2 ===

Replace the last paragraph with:{{{
    If the value of "type" is "html", the content of the Text construct
    MUST NOT contain child elements, and SHOULD be suitable for handling
    as HTML [HTML].  Any markup within MUST be escaped; for example,
    "<br>" as "&lt;br>". Atom Processors that display such content MAY
    use that markup to aid in its display.

    The content is subject to further constraints depending on its kind:

    o  HTML markup within an Inline Text construct SHOULD be such that
       it could validly appear directly within an HTML <SPAN> element,
       after unescaping.
    o  HTML markup within a Block Text construct SHOULD be such that
       it could validly appear directly within an HTML <DIV> element,
       after unescaping.
}}}

=== section 3.1.1.3 ===

{{{
    Example atom:title with XHTML content:

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

    If the value of "type" is "xhtml", the content of the Text construct
    MUST be XHTML [XHTML] text and markup. Atom Processors which display
    the content MAY use the markup to aid in displaying it.  Escaped
    characters, such as "&" and ">", represent those characters, not
    markup.

    The content is subject to further constraints depending on its kind:

    o  the content of an Inline Text construct MUST be XHTML text and
       markup that could validly appear within an XHTML span element.
    o  the content of a Block Text construct MUST be XHTML text and
       markup that could validly appear within an XHTML div element.

    Examples of valid XHTML content:

    ...
    <title type="xhtml">
       <span xmlns="http://www.w3.org/1999/xhtml">
          This is an <b>XHTML</b> title
       </span>
    </title>
    <summary type="xhtml">
       <div xmlns="http://www.w3.org/1999/xhtml">
          <p>
             Note that using <code>span</code> and <code>div</code>
             containers allows us to keep using default namespaces
             (namespaces not bound to any prefix).
          </p>
          <p>
             The container element has been choosen to fit the kind of
             content it contains: <code>span</code> for inline content
             and <code>div</code> for block content.
          </p>
       </div>
    </summary>
    ...
    <summary type="xhtml">
       <xhtml:p xmlns:xhtml="http://www.w3.org/1999/xhtml">
          This is an <xhtml:b>XHTML</xhtml:b> paragraph.
       </xhtml:p>
    </summary>
    ...

    The following example assumes that the XHTML namespace has been bound
    to the "xh" prefix earlier in the document:

    ...
    <summary type="xhtml">
       This is <xh:b>XHTML</xh:b> content.
    </summary>
    ...
}}}

=== section 4.1.3 The "atom:content" Element ===

Replace the {{{atomInlineXHTMLContent}}} definition with this one:{{{
    atomInlineXHTMLContent =
       element atom:content {
          atomCommonAttributes,
          attribute type { "xhtml" },
          anyXHTML
       }
}}}

=== section 4.1.3.3 Processing Model ===

Replace third list item with this one:{{{
    3.  If the value of "type" is "xhtml", the content of atom:content
        MUST be XHTML [XHTML] XHTML text and markup that could validly
        appear within an XHTML div element. Atom Processors that
        display the content MAY use the markup to aid in displaying it.
        Escaped characters, such as "&" and ">", represent those
        characters, not markup.
}}}

=== section 4.2.4 The "atom:copyright" Element ===

In the first paragraph, replace "Text construct" with "Inline Text 
construct".

=== section 4.2.12 The "atom:subtitle" Element ===

In the first paragraph, replace "Text construct" with "Inline Text 
construct".

=== section 4.2.13 The "atom:summary" Element ===

In the first paragraph, replace "Text construct" with "Block Text 
construct".

=== section 4.2.14 The "atom:title" Element ===

In the first paragraph, replace "Text construct" with "Inline Text 
construct".

== Impacts ==

Producers of Atom documents based on the IETF drafts and using XHTML 
content will have to either:
  * drop the XHTML div wrapper if they use prefixes for namespaces
  * change it to a "span" in atom:title and atom:copyright if they want 
to produce prefix-free Atom documents and check the XHTML content to be 
valid inside XHTML span or div elements
  * move to prefix-bound (non-default) namespaces and drop the XHTML div 
wrapper if they don't check the XHTML content

== Notes ==

The "wrong namespace use" concern is answered in the second example, 
some might prefer making it clearer by putting the example description 
in its own spec paragraph and have the example only an illustration.

----

CategoryProposals

---

From: Graham <[email-masked]>
Date: Sat, 30 Apr 2005 17:17:36 +0100

On 30 Apr 2005, at 3:43 pm, Thomas Broyer wrote:

> Using a XHTML "div" element is also quite inappropriate in an  
> atom:title element as a "div" is meant for block content whereas a  
> title is merely expected to be used as inline content (e.g. by  
> putting it inside an "h2" or "h3" XHTML element).

The div is not part of the content, and inline content can safely  
appear within a div. -1.

Next.

Graham

---

From: Thomas Broyer <[email-masked]>
Date: Sat, 30 Apr 2005 20:03:28 +0200

Graham wrote:
> appear within a div.

I'm OK with that but I'm still bothered by putting my titles in a 
block-level element: because the div is still part of XHTML (even if not 
part of the content here), which defines it as a block-level container!

Are you considering the following title OK?

<atom:title type="xhtml">
    <div>
       <p>Hey this is an entry title!</p>
       <p>Look what the Atom spec allows us to do with it!</p>
    </div>
</atom:title>

If not (which I suppose), then the spec should at least be changed to 
introduce inline vs. block content.

And the same distinction should be done for escaped HTML content to 
forbid (well, actually not, I know, because we use a SHOULD and not a 
MUST) titles like this one:

<atom:title type="html"><![CDATA[
    <p>Hey this is an entry title!</p>
    <p>Look what the Atom spec allows us to do with it!</p>
]]></atom:title>

> -1.

I'm not sure it's so easy. There's another problem with the actual spec: 
it allows any attribute on the XHTML div container without defining how 
they have to be handled.
Should they be discarded along with the div? Should they be somehow 
"inherited" by the content?
If the spec is changed to forbid any attribute (other than the XHTML 
namespace declaration), then the XHTML div is not really an XHTML div, 
it becomes (and actually it already is, as it is not part of the 
content) a dummy container belonging to the XHTML namespace, whichever 
its name (though it's better if it looks like an existing XHTML element).

I'm sorry but these kind of "hacks" have nothing to do within a standard 
(IETF or else), especially if they have no mean other than just being 
hacks and if there are clean solutions: Atom is XML using XML 
namespaces, it's enough for usefulness without the need to introduce 
such a dummy container; and people willing to use default namespaces 
only (prefix-free XML names) can still achieve that by introducing 
meaningless "span" or "div" containers, with the difference they will be 
part of the content.

-- 
Thomas Broyer

---

From: Antone Roundy <[email-masked]>
Date: Sat, 30 Apr 2005 13:53:36 -0600

On Saturday, April 30, 2005, at 12:03  PM, Thomas Broyer wrote:
> block-level element: because the div is still part of XHTML (even if 
> not part of the content here), which defines it as a block-level 
> container!

PaceXmlContentWrapper would enable the use of an inline element in Atom 
elements that aren't supposed to have block content.  And it would 
enable people who declare the namespace elsewhere to omit the container 
element.  And it would keep the status of the top level element in the 
content, if there is one, unambiguous.

>    <p>Look what the Atom spec allows us to do with it!</p>

I'd support forbidding block markup in titles and other such places 
where it's not appropriate.

> I'm not sure it's so easy. There's another problem with the actual 
> spec: it allows any attribute on the XHTML div container without 
> defining how they have to be handled.

I'd support forbidding any attributes other than (a) namespace 
declaration(s) on container elements...in fact, I'm going to add that 
to PaceXmlContentWrapper.

> its name (though it's better if it looks like an existing XHTML 

I disagree with this characterization.  We may have profiled the XHTML 
div element for this particular use, but that doesn't stop it from 
being an XHTML div.

> I'm sorry but these kind of "hacks" have nothing to do within a 
> standard (IETF or else), especially if they have no mean other than 
> just being hacks and if there are clean solutions: Atom is XML using 
> XML namespaces, it's enough for usefulness without the need to 
> introduce such a dummy container; and people willing to use default 
> namespaces only (prefix-free XML names) can still achieve that by 
> introducing meaningless "span" or "div" containers, with the 
> difference they will be part of the content.

If the author adds a div or span, that's fine.  But if the software ads 
it, it's altering the author's content, and should have a way to so 
indicate so that the change can be undone.