Re: Section 2.1.1 comments

All changes made as suggested.

Cheers,
Geoff

   From: "Jim Whitehead" <ejw@cse.ucsc.edu>
   Date: Wed, 31 Jan 2001 16:49:53 -0800

   Section 2.1.1:

   It took me a long time to figure out exactly what was being described here.
   I think my confusion derived from not understanding that there were three
   separate entities being discussed:

   - version-controlled resource
   - version resource
   - version history

   I think my confusion would be eased by changing the second, third, and
   fourth sentences of the first paragraph of Section 2.1.1 to more clearly
   identify the three resources, and the fact that the unversioned resource is
   being converted into a new type of resource, the version-controlled
   resource.

   ----------

   VERSION-CONTROL, when invoked on a resource with URL U, performs three
   distinct operations:

   1) It creates a new "version resource" whose body and dead properties are a
   copy of the original, unversioned resource. The server assigns this resource
   a new URL, VR, which is different from the original URL U.
   2) It converts the unversioned resource into a "version-controlled
   resource". The version-controlled resource keeps the original URL U. As part
   of this conversion, it adds the DAV:checked-in property, whose value is the
   URL of the version resource created in step #1.
   3) It creates a new "version history resource" whose state initially just
   contains URL VR, since that is, at present, the only version in the version
   history.

   Thus, whereas before VERSION-CONTROL, there was only one, unversioned
   resource, after VERSION-CONTROL there are three separate, distinct
   resources, each containing their own state and properties: the
   version-controlled resource, the version resource, and the version history
   resource. In core versioning, a version history resource is not assigned a
   URL, and hence is not visible in the http scheme URL space. However, when
   the version-history option (Section 5) is supported, this changes, and the
   version history resource does have a URL.

   ----------

   With this change, the first sentence of the second paragraph is no longer
   needed.

   I recommend moving the third paragraph, and the figure following, to
   immediately after the second paragraph. Plus, I recommend labeling all of
   the boxes in the figure, as follows:


	     ===VERSION-CONTROL==>

		       |                       +----+
		       |                       |    | version history
		       |                       +----+
		       |                         |
	   /foo.html   |   /foo.html             |
		       |                         v
	    +----+     |     +----+ checked-in +----+
	    | S1 |     |     | S1 | ---------->| S1 | version resource
	    +----+     |     +----+            +----+ URL: /hist/73/v1
	 unversioned   | version-controlled
	   resource    |     resource

   Adding an arrowhead to the lines between the version-controlled resource and
   the version resource, and the version history and the version resource,
   would also be helpful, since this is fairly conventional for pointers.

   In the third paragraph, the third sentence ("The new version resource is
   identified...") should be changed to:

   "The original unversioned resource is converted into a version-controlled
   resource, whose DAV:checked-in property identifies the version resource."

   Using "version-controlled resource" is more clear than using the elliptical
   "resource that is now under version control." (The artist formerly known as
   Prince... ;-)


   In the second paragraph, I recommend changing the second sentence "When a
   method is applied..." to:

   Since the version-controlled resource and version resources are separate,
   distinct resources, when a method is applied to the version-controlled
   resource, it only applies to the version-controlled resource, and does not
   apply to the version resource that is currently identified by the
   DAV:checked-in property.

   - Jim

Received on Sunday, 4 February 2001 23:54:12 UTC