Definition tuning #158

ahankinson · 2018-09-17T12:58:16Z

Reformatted definitions to follow the style of the rest of the spec.
Reworded some definitions to make their intent clearer
Added missing definitions

- Reformatted definitions to follow the style of the rest of the spec. - Reworded some definitions to make their intent clearer - Added missing definitions

awoods · 2018-09-17T13:37:15Z

draft/spec/index.html

-        <dd>The state of an <a>OCFL object</a>'s content which is constructed using the incremental
-          changes recorded in the sequence of corresponding and prior version directories.</dd>
+        <dd>
+            The file path as it appears on disk including the version directories and the filename, and relative to


The wording here is a bit odd:

including the version directories and the filename, and relative to an <a>OCFL Object Root</a>.

The addition of version directories rather than directories also ignores the potential for directories within the OCFL object itself.

awoods · 2018-09-17T13:38:00Z

draft/spec/index.html

+            <dfn>Digest</dfn>:
+        </dt>
+        <dd>
+            An algorithmic characterisation of the contents of a file conforming to a standard digest algorithm.


U.S. spelling characterization

awoods · 2018-09-17T13:41:34Z

draft/spec/index.html

+            <dfn>Manifest</dfn>
+        </dt>
+        <dd>
+            A complete listing of all files, with their digests, within an OCFL Object and stored in the


It would read better for me if the and stored in the <a>Inventory</a> came earlier. Such as:

A section of the <a>Inventory</a> containing a complete listing...

rosy1280

@zimeon at some point during the F2F meeting in 2018.09 you made a request to keep definitions to one sentence. Some of the changes I'm requesting are because of that. Can you elaborate on that need, or can we forego it...

draft/spec/index.html

rosy1280 · 2018-09-19T12:19:39Z

draft/spec/index.html

+            <dfn>Manifest</dfn>
+        </dt>
+        <dd>
+            A complete listing of all files, with their digests, within an OCFL Object and stored in the


rosy1280 · 2018-09-19T12:20:44Z

draft/spec/index.html

-        <dd>The state of an <a>OCFL object</a>'s content which is constructed using the incremental
-          changes recorded in the sequence of corresponding and prior version directories.</dd>
+        <dd>
+            The file path as it appears on disk including the version directories and the filename, and relative to


The addition of version directories rather than directories also ignores the potential for directories within the OCFL object itself.

rosy1280 · 2018-09-19T12:21:07Z

draft/spec/index.html

+        </dt>
+        <dd>
+            An algorithmic characterisation of the contents of a file conforming to a standard digest algorithm.
+            Digests are used for recording fixity and for content-addressable storage within an OCFL Object.


Again two sentences...

I think the second sentence is actually slightly misleading now... we don't really use content-addressable storage in the usual sense (the files most likely have their original names), instead we have a kind of content reference in the inventory. My sense is that the two sentences are short so I'd be fine to keep them, but would change "content-addressable storage" to "content references"

rosy1280 · 2018-09-19T12:24:37Z

draft/spec/index.html

+        <dd>
+            The base directory of an <a>OCFL Object</a> that may exist either as a plain directory, or in the
+            case of a zipped OCFL Object, as the top directory in a zip file. The Object Root is identified by
+            the presence of a NamAsTe file, "0=ocfl_object_1.0".


Again two sentences....

IMO the second sentence isn't required here, it is repeating part of the spec

zimeon · 2018-09-19T12:45:21Z

@rosy1280 I think the key is to keep the definitions short, usually one sentence. However, if one sentence really doesn't work then I would not force awkward language or forgo clarity to follow that rule

# Conflicts: # draft/spec/index.html

ahankinson · 2018-10-05T19:16:56Z

Thanks for the comments -- I've re-worked the definitions according to feedback, with one exception: I kept the reference to the NamAsTe file in OCFL Object Root since it a) mirrors that of the one in OCFL Storage Root, and b) an OCFL Object Root can be identified as such by its presence, so it forms part of the identity (which seems important to note in the definition)

zimeon · 2018-10-05T19:26:43Z

draft/spec/index.html

+            <dfn>OCFL Object Root</dfn>:
+        <dt>
+        <dd>
+            The base directory of an <a>OCFL Object</a>, identified by a NamAsTe file "0=ocfl_object_1.0".


[[NAMSATE]] not NamAsTe? Good to link and the spec doesn't use the CamelCase version (though does explain as "NAMe AS TExt")

zimeon · 2018-10-05T19:26:57Z

draft/spec/index.html

+            <dfn>OCFL Storage Root</dfn>:
+        </dt>
+        <dd>
+            A base directory used to store OCFL Objects, identified by a NamAsTe file "0=ocfl_1.0".


similarly: [[NAMASTE]]

zimeon · 2018-10-05T19:27:26Z

draft/spec/index.html

-        <dd>The state of an <a>OCFL object</a>'s content which is constructed using the incremental changes recorded in
-          the sequence of corresponding and prior version directories.</dd>
+        <dd>
+            The file path of a file on disk, relative to the <a>OCFL Object 


... of a file on disk or in an object store, ...

rosy1280 · 2018-10-06T02:57:25Z

draft/spec/index.html

+            <dfn>Inventory</dfn>:
+        </dt>
+        <dd>
+            A file, expressed in JSON-LD, that tracks the history and current 


Well spotted!

ahankinson · 2018-10-09T09:30:27Z

🎉

Definition tuning

78112b6

- Reformatted definitions to follow the style of the rest of the spec. - Reworded some definitions to make their intent clearer - Added missing definitions

ahankinson requested review from rosy1280, awoods, zimeon, julianmorley and neilsjefferies September 17, 2018 12:58

awoods requested changes Sep 17, 2018

View reviewed changes

rosy1280 requested changes Sep 19, 2018

View reviewed changes

ahankinson added 4 commits October 5, 2018 19:54

Merge branch 'master' into tuning-definitions

2f9224f

# Conflicts: # draft/spec/index.html

Merging updated files

994f31c

Merge branch 'master' into tuning-definitions

937f344

# Conflicts: # draft/spec/index.html

Updated definitions based on feedback

68038a5

zimeon requested changes Oct 5, 2018

View reviewed changes

ahankinson added 2 commits October 5, 2018 20:29

Fixed reference to namaste

1472907

Clarify object stores are our friends too.

87c3047

zimeon previously approved these changes Oct 5, 2018

View reviewed changes

rosy1280 requested changes Oct 6, 2018

View reviewed changes

Remove reference to JSON-LD

f418f7c

ahankinson dismissed zimeon’s stale review via f418f7c October 8, 2018 12:00

zimeon approved these changes Oct 8, 2018

View reviewed changes

awoods approved these changes Oct 8, 2018

View reviewed changes

rosy1280 approved these changes Oct 8, 2018

View reviewed changes

julianmorley approved these changes Oct 8, 2018

View reviewed changes

zimeon merged commit 2f8c45e into master Oct 8, 2018

zimeon deleted the tuning-definitions branch October 8, 2018 17:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Definition tuning #158

Definition tuning #158

ahankinson commented Sep 17, 2018

awoods Sep 17, 2018

rosy1280 Sep 19, 2018

awoods Sep 17, 2018

awoods Sep 17, 2018

rosy1280 Sep 19, 2018

rosy1280 left a comment

rosy1280 Sep 19, 2018

rosy1280 Sep 19, 2018

rosy1280 Sep 19, 2018

zimeon Sep 19, 2018

rosy1280 Sep 19, 2018

zimeon Sep 19, 2018

zimeon commented Sep 19, 2018

ahankinson commented Oct 5, 2018

zimeon Oct 5, 2018 •

edited

Loading

zimeon Oct 5, 2018

zimeon Oct 5, 2018

rosy1280 Oct 6, 2018

zimeon Oct 6, 2018

ahankinson commented Oct 9, 2018

Definition tuning #158

Definition tuning #158

Conversation

ahankinson commented Sep 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rosy1280 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zimeon commented Sep 19, 2018

ahankinson commented Oct 5, 2018

zimeon Oct 5, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahankinson commented Oct 9, 2018

zimeon Oct 5, 2018 •

edited

Loading