Re: Editorial suggestions for DeltaV 11.2

Thanks for finding these errors, Chuck!

   From: "Fay, Chuck" <CFay@filenet.com>

   Some minor editorial suggestions for DeltaV 11.2:

   Section 1, "Introduction", paragraph 1, 5th sentence:
   "interesting" -> "interested"

Done. (oops :-).

   Section 1.3, "Terms", "Predecessor, Successor, Ancestor, Descendant":
   "When a version is related to another version by one or more predecessor
   relations, it is called an 'ancestor' of that version."
   Consider clarifying which version in the sentence is the predecessor:
   "When a version precedes another version by one or more predecessor
   relations, it is called an 'ancestor' of that version."

I agree this needs improvement.  How about "is connected to another version
by traversing one or more predecessor relations"?

   Section 1.3, "Terms", "Version History Resource" and "Fork, Merge":
   Why aren't these defined in section 1.3.1, Optional Versioning Terms?
   Version History and Merge are both optional.  By my reading, there is no
   requirement to support fork/merge semantics or version history resources in
   Core Versioning.  If "Fork, Merge" definitions are moved to section 1.3.1,
   the diagram following the definition should move with them.

As Tim pointed out, these concepts are present in core versioning.  In
particular, version history is explicitly mentioned, and the
DAV:successor-set and DAV:predecessor-set can have multiple values in
core versioning.  So although a client may not create forks or merges,
it needs to be prepared to deal with them in things like a version
tree display.

   While you're at
   it, why not label the first set of terms "Core Versioning Terms" and make
   them a peer section to "Optional Versioning Terms"?

I believe "Core Versioning Terms" and "Optional Versioning Terms" are
more closely related to each other than they are to the other subsections
of the introduction, and therefore it is better to group them together.

   Section 2.1.1, "Creating a Version-Controlled Resource", paragraph 1,
   sentence 1:
   Add "versionable" as follows to make clear that VERSION-CONTROL can be
   applied only to versionable resources, not just any old resource:  "In order
   to track the history of the content and dead properties of a versionable
   resource, an author can put the resource under version control with a
   VERSION-CONTROL request."

Done.

   Section 2.2.1, "DAV:checked-in  (protected)", sentence 2:
   "This URL can be used to retrieve this particular state of the
   version-controlled resource after the version-controlled resource itself has
   been modified."
   This sentence should be moved to Section 2.2.2, "DAV:checked-out ...",
   because it's true there but incorrect here.

??  The DAV:checked-in property means that the vcr is checked in (thus
the name :-), and the DAV:checked-in version captures the current 
state of the vcr.  This is not true for a checked out vcr.

   Section 2.4, "VERSION-CONTROL", subsection "Postconditions", paragraph 1,
   sentence 5:
   "chose" -> "choose".

Ooops!  Several of those.  Thanks!

   Section 2.8, "Additional PROPPATCH Semantics", subsection "Additional
   Preconditions", last precondition:
   "(DAV:cannot-modify-unsupported-property): An attempt to modify a property
   defined by this document (either core or optional) whose semantics are not
   enforced by the server MUST fail.  This helps ensure that a client will be
   notified when it is trying to use a property whose semantics are not
   supported by the server."
   It seems from RFC 2518 that all dead properties fall under the description
   of "[a property] whose semantics are not enforced by the server", but surely
   we don't want to disallow modifying dead properties.  This should be
   reworded to say:  "DAV:cannot-modify-unsupported-property): An attempt to
   modify an optional property defined by this document but not supported by
   the server MUST fail.  This helps ensure that a client will be notified when
   it is trying to use a property that is not supported by the server."

As Tim mentioned, the document defines no dead properties, so this
precondition has no effect on any dead property.  I prefer the phrase
"whose semantics are not enforced" over "supported by the server"
because this emphasizes that it's not enough just to let that property
exist on the resource, but that the semantics have to be enforced.

Thanks again for the review!

Cheers,
Geoff

Received on Thursday, 18 January 2001 13:26:22 UTC