[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: draft-gregorio-atompub-multipart-02
Joe,
Here's a diff that touches up the example a bit and makes it
consistent with the surrounding text a bit.
thanks,
dims
On Wed, Aug 6, 2008 at 6:56 PM, Joe Gregorio <joe@xxxxxxxxxxxxxx> wrote:
>
> On Wed, Aug 6, 2008 at 6:09 PM, Tim Bray <Tim.Bray@xxxxxxx> wrote:
>> On Jul 17, 2008, at 12:44 PM, Joe Gregorio wrote:
>>
>>>
>>> http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02.txt
>>>
>>> http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02.html
>>>
>>> http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02-from-1.diff.html
>>
>> I have a bunch of editorial comments, but I don't think any of these affect
>> the protocol. I feel somewhat guilty about coming in late, so have tried to
>> be as camera-ready as possible, and will cheerfully whack those that don't
>> pick up objections into the XML myself if Joe will lend it to me.
>
> Anyone can pull the sources from subversion out of the code.google.com project
> and send me a diff when you're done. Thanks!
>
> http://code.google.com/p/atompub-mulitpart-spec/
>
> -joe
>
>
>>
>> Title: Shouldn't it have the word "Resource" in it? "AtomPub Multipart
>> Media Resource Creation". We're kinda all about resources here, and "media
>> Creation" is a trifle grammatically awkward
>> =================
>> Abstract. s/should/may/ - we're just specifying a way to do this, we're not
>> asserting that all the servers should or SHOULD go there.
>> =================
>> 1. Introduction
>>
>> typo, "representations" is misspelled
>>
>> Should we add section numbers to some of the RFC5023 references? In
>> particular to #9.2.
>> =================
>> 1/2 Design considerations
>>
>> The draft veers between the past, present, and future tenses. Present
>> throughout is better. I've tried to catch all these.
>> 1st para s/will be/are/
>> 2nd para s/was/is/g
>> =================
>> 1.3 Applicability
>>
>> I apologize in advance for a ton of purely prose-style suggestions; I can't
>> help it.
>>
>> s/just creating/the creation of/
>> ==================
>> 2. Terminology
>>
>> Need to add "foreign markup" from 4287, and perhaps [RFC2387] for "object
>> root", which was new to me.
>> =================
>> 3. Multipart Representations
>>
>> 2nd para, 2nd sentence, style rewrite: "There may be other specifications
>> that define uses for multipart representations in the AtomPub context; this
>> specification only describes one particular representation and how to use it
>> in the media-resource creation process".
>>
>> I recommend that the 3rd paragraph here be slightly re-written to define
>> specific terms, "Media Part" and "Entry Part". I'm not sure the use of
>> "object" in 4. below sits comfortably with RFC2387, which seems to use
>> "object" for the whole multipart thingie, and there are a few places later
>> in the draft where the terms are useful. I find that defined terms are also
>> helpful to implementors when choosing class/variable names and so on.
>>
>> A multipart/related POST to a Media Collection MUST be a valid
>> multipart/related representation as defined by [RFC2387] (Levinson, E., "The
>> MIME Multipart/Related Content-type," August 1998.) and MUST contain two
>> body parts. One, referred to as the Media Part, MUST be an Atom Entry with a
>> media type of 'application/atom+xml' or 'application/atom+xml;type=entry'.
>> The other, referred to as the Media Part, MUST be of a media type acceptable
>> to the collection. The object root MUST be the Entry Part. The Entry Part's
>> atom:content element MUST have a 'src' attribute whose value is the URI of
>> the related media in the Media Part. The 'src' attribute value MUST be a
>> 'cid:' URI as defined by [RFC2392] (Levinson, E., "Content-ID and Message-ID
>> Uniform Resource Locators," August 1998.). The Content-Type: header of the
>> POST request MUST specify "application/atom+xml;type=entry" or
>> "application/atom+xml".
>> ====================
>> 4. Server Processing
>>
>> The first sentence is misleading; if it proceeded just like in 5023 we
>> wouldn't need this! Let me rewrite slightly, using the terms defined above:
>>
>> A successful POST of a multipart/related representation to a Media
>> Collection causes several resource-creation processes to occur as described
>> in [RFC5023]. The Media Part is used to create a Media Resource as if it
>> had been posted as a request body to the collection as described in section
>> 9.6, and the Entry Part is used to create the corresponding Media Link
>> Entry. Assuming these two steps are successful, the server returns a 201
>> status code and a Location: header pointing to the newly created Media Link
>> Entry. The applicable rules from [RFC5023] MUST be followed, including
>> Slug: header processing.
>>
>> 2nd para s/it should either/that is, either/
>> ===================
>> 5. Service Document Extension
>>
>> XML Pedantry at work here, and single/double quote cleanup:
>>
>> 2nd sentence: The "alternate" attribute's value MUST be one more more
>> tokens, space-separated if more than one.
>>
>> 4th: The presence of the "multipart-related" token in the "alternate"
>> attribute's value indicates that the collection accepts multipart/related
>> POSTs whose Media Part has a content-type matching that specified in the
>> app:accept element.
>>
>> 2nd-last para: Can we just lose it? Is there any reason to think that you
>> could suddenly start sending multiparts to random collections?
>>
>> last para: comma before "loses flexibility"
>>
>>
>>
>
>
>
> --
> Joe Gregorio http://bitworking.org
>
>
--
Davanum Srinivas :: http://davanum.wordpress.com
Index: draft-gregorio-atompub-multipart.xml
===================================================================
--- draft-gregorio-atompub-multipart.xml (revision 8)
+++ draft-gregorio-atompub-multipart.xml (working copy)
@@ -234,6 +234,8 @@
Here is an example service document that
contains two media collections. The first collection
accepts multipart/related POSTs for video media types only.
+ This collection accepts audio and text as well but does
+ not allow them to added via multipart/related POSTs.
The second collection accepts multipart/related POSTs
for image/jpeg and image/png media types.
</t>
@@ -255,8 +257,8 @@
<collection
href="http://example.org/blog/pic"; >
<atom:title>Pictures Only</atom:title>
+ <accept alternate="multipart-related">image/jpeg</accept>
<accept alternate="multipart-related">image/png</accept>
- <accept alternate="multipart-related">image/gif</accept>
</collection>
</workspace>
</service>
@@ -273,8 +275,9 @@
Host: example.org
Content-Length: nnnn
content-type: multipart/related;
- boundary="===============1605871705=="
- type="application/atom+xml"
+ boundary="===============1605871705==";
+ type="application/atom+xml";
+ start="<myentry.atom@xxxxxxxxxxx>";
slug: The Beach
mime-version: 1.0
@@ -282,6 +285,7 @@
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
MIME-Version: 1.0
+Content-ID: <myentry.atom@xxxxxxxxxxx>
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom";>
@@ -292,15 +296,15 @@
<summary type="text">
A nice sunset picture over the water.
</summary>
- <content src="cid:99334422@example.com"
- type="image/gif" />
+ <content src="cid:99334422@example.org"
+ type="image/png" />
</entry>
--===============1605871705==
-Content-Type: image/gif
+Content-Type: image/png
MIME-Version: 1.0
-Content-ID: <99334422@xxxxxxxxxxx>
+Content-ID: <99334422@xxxxxxxxxxx>
-GIF89a...binary image data...
+.PNG...binary image data...
--===============1605871705==--
]]></artwork></figure>
@@ -314,7 +318,8 @@
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
-Location: http://example.org/media/edit/the_beach.atom
+Content-Location: http://media.example.org/edit/the_beach.atom
+Location: http://media.example.org/edit/the_beach.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom";>
@@ -327,10 +332,10 @@
</summary>
<content type="image/png"
src="http://media.example.org/the_beach.png"/>
- <link rel="edit-media"
+ <link rel="edit-media" type="image/png"
href="http://media.example.org/edit/the_beach.png"; />
<link rel="edit"
- href="http://example.org/media/edit/the_beach.atom"; />
+ href="http://media.example.org/edit/the_beach.atom"; />
</entry>
]]></artwork></figure>