Merge pull request #447 from ResearchObject/fix/issue-446-cosmeticfixes-12-RC1

applying some cosmetics to 1.2-RC1

Author: stain

Makefile

@@ -86,19 +86,19 @@ release/:
 
 release/ro-crate-${TAG}.md: dependencies release/ docs/_specification/${RELEASE}/_metadata.liquid docs/_specification/${RELEASE}/.references.md docs/_specification/${RELEASE}/*.md docs/_specification/${RELEASE}/appendix/*.md docs/_includes/references.liquid
 	cp docs/_specification/${RELEASE}/_metadata.liquid docs/_specification/${RELEASE}/.metadata.md
-	pandoc --from=markdown+gfm_auto_identifiers --to=markdown+gfm_auto_identifiers \
+	pandoc --wrap=none --from=markdown+gfm_auto_identifiers --to=markdown+gfm_auto_identifiers \
 	   docs/_specification/${RELEASE}/.metadata.md \
 	   `grep ^nav_order: docs/_specification/${RELEASE}/*.md | sort -n -k 2 | grep -v index.md| grep -v about.md | sed s/:.*//` \
 	   `grep ^nav_order: docs/_specification/${RELEASE}/appendix/*.md | sort -n -k 2 | sed s/:.*//` \
 	   docs/_includes/references.liquid docs/_specification/${RELEASE}/.references.md \
 	   > release/ro-crate-${TAG}.md
 	# Our own rendering of Note/Warning/Tip
 	sed -i -E 's/\{% include callout.html //g' release/ro-crate-${TAG}.md
-	sed -i -E 's/\" %}//g' release/ro-crate-${TAG}.md
-	sed -i -E 's/type=\"note\" content=\"/**Note**: /g' release/ro-crate-${TAG}.md
-	sed -i -E 's/type=\"warning\" content=\"/**Warning** :/g' release/ro-crate-${TAG}.md
-	sed -i -E 's/type=\"tip\" content=\"/**Tip**: /g' release/ro-crate-${TAG}.md
-	sed -i -E 's/type=\"important\" content=\"/**Important**: /g' release/ro-crate-${TAG}.md
+	sed -i -E "s/[\"'] ?\n?%}//g" release/ro-crate-${TAG}.md  # note that this assumes the closing string-quote to be followed by «space»%} on the same line !
+	sed -i -E "s/type=[\"']note[\"'] content=[\"']/**Note**: /g" release/ro-crate-${TAG}.md
+	sed -i -E "s/type=[\"']warning[\"'] content=[\"']/**Warning** :/g" release/ro-crate-${TAG}.md
+	sed -i -E "s/type=[\"']tip[\"'] content=[\"']/**Tip**: /g" release/ro-crate-${TAG}.md
+	sed -i -E "s/type=[\"']important[\"'] content=[\"']/**Important**: /g" release/ro-crate-${TAG}.md
 	# remove any remaining lines beginning with {%
 	sed -i -E 's/\{%.*//g' release/ro-crate-${TAG}.md
 	# Skip intermediate table-of-contents

docs/_data/sidebars/spec.yml

@@ -33,42 +33,42 @@ versions:
         url: /specification/1.1/appendix/implementation-notes.html
       - title: RO-Crate JSON-LD
         url: /specification/1.1/appendix/jsonld.html
-- title: RO-Crate 1.2 RC1 (release candidate)
-  url: /specification/1.2-RC1/index.html
+- title: RO-Crate 1.2
+  url: /specification/1.2/index.html
   subitems:
   - title: Introduction
-    url: /specification/1.2-RC1/introduction.html
+    url: /specification/1.2/introduction.html
   - title: Terminology
-    url: /specification/1.2-RC1/terminology.html
+    url: /specification/1.2/terminology.html
   - title: RO-Crate Structure
-    url: /specification/1.2-RC1/structure.html
+    url: /specification/1.2/structure.html
   - title: Metadata of the RO-Crate
-    url: /specification/1.2-RC1/metadata.html
+    url: /specification/1.2/metadata.html
   - title: Root Data Entity
-    url: /specification/1.2-RC1/root-data-entity.html
+    url: /specification/1.2/root-data-entity.html
   - title: Data Entities
-    url: /specification/1.2-RC1/data-entities.html
+    url: /specification/1.2/data-entities.html
   - title: Contextual Entities
-    url: /specification/1.2-RC1/contextual-entities.html
+    url: /specification/1.2/contextual-entities.html
   - title: The focus of an RO-Crate
-    url: /specification/1.2-RC1/crate-focus.html
+    url: /specification/1.2/crate-focus.html
   - title: Provenance of entities
-    url: /specification/1.2-RC1/provenance.html
+    url: /specification/1.2/provenance.html
   - title: Profiles
-    url: /specification/1.2-RC1/profiles.html
+    url: /specification/1.2/profiles.html
   - title: Workflows and scripts
-    url: /specification/1.2-RC1/workflows.html
+    url: /specification/1.2/workflows.html
   - title: Appendix
-    url: /specification/1.2-RC1/appendix/index.html
+    url: /specification/1.2/appendix/index.html
     subitems:
       - title: Changelog
-        url: /specification/1.2-RC1/appendix/changelog.html
+        url: /specification/1.2/appendix/changelog.html
       - title: Handling relative URI references
-        url: /specification/1.2-RC1/appendix/relative-uris.html
+        url: /specification/1.2/appendix/relative-uris.html
       - title: Implementation notes
-        url: /specification/1.2-RC1/appendix/implementation-notes.html
+        url: /specification/1.2/appendix/implementation-notes.html
       - title: RO-Crate JSON-LD
-        url: /specification/1.2-RC1/appendix/jsonld.html
+        url: /specification/1.2/appendix/jsonld.html
 - title: RO-Crate 1.2-DRAFT (draft for next release)
   url: /specification/1.2-DRAFT/index.html
   subitems:

docs/_specification/1.2-DRAFT/appendix/implementation-notes.md

@@ -37,7 +37,7 @@ nav_order: 21
 
 When implementing tools to work with RO-Crate it is not necessary to use JSON-LD software libraries, however, programmers should keep in mind the following:
 
-- **_RO-Crate JSON-lD_ has a flat structure**; every entity is a JSON object directly within the `@graph` array in the _RO-Crate Metadata Document_. A useful strategy when processing a crate is to build a look-up table and/or function so that entities can be found via their ID, for example provide a method such as `getEntity(id)` which returns an entity by its id or a `null` value if it's not there.
+- **_RO-Crate JSON-LD_ has a flat structure**; every entity is a JSON object directly within the `@graph` array in the _RO-Crate Metadata Document_. A useful strategy when processing a crate is to build a look-up table and/or function so that entities can be found via their ID, for example provide a method such as `getEntity(id)` which returns an entity by its id or a `null` value if it's not there.
 
 - **Code defensively**. Code should not assume that values will always be a String; values for properties may be single scalar values such as strings or integers (`"2"` or 2), or references to other entities such as `{"@id", "_:1"}` (where the referenced entity may or may not be described in the crate, see the point above about having a `getEntity()` method).
 
@@ -135,9 +135,9 @@ b0556450…8802  bag-info.txt
 000b27e3…c52e  manifest-sha512.txt
 ```
 
-{% include callout.html type="warning" content='The BagIt manifest is intended to detect "bit rot" and accidental damage,
-it does not provide proof the RO-Crate has not been deliberately
-tampered with, as a malicious actor can also update the checksums.' %}
+{% include callout.html type="warning" content="The BagIt manifest is intended to detect \"bit rot\" and accidental damage,
+it does not provide proof the RO-Crate has not been deliberately tampered with, as a malicious actor can also update the checksums."
+%}
 
 Guarding against such scenarious would require additional cryptographic
 measures, e.g.  

docs/_specification/1.2-DRAFT/appendix/relative-uris.md

@@ -135,11 +135,13 @@ Converting a Detached Crate to an Attached Crate can mean multiple things depend
 First, check if the Root Data Entity already have a [distribution download](../data-entities#directories-on-the-web-dataset-distributions) listed, in which case that can be retrieved as the corresponding Attached Crate.
 
 To archive a snapshot of an Detached Crate's metadata, keeping all data entities [web-based](../data-entities#web-based-data-entities):
-* Crate a new folder as the _RO-Crate Root_, save the _RO-Crate Metadata Document_ as the _RO-Crate Metadata File_ according to [Attached RO-Crate Package](../structure#attached-ro-crate-package) structure
+
+* Create a new folder as the _RO-Crate Root_, save the _RO-Crate Metadata Document_ as the _RO-Crate Metadata File_ according to [Attached RO-Crate Package](../structure#attached-ro-crate-package) structure
 * Copy the absolute `@id` to become an `identifier` according to recommendations for [Root Data Entity identifier](../root-data-entity#root-data-entity-identifier)
 * Optional: Change the `@id` of the Root Data Entity to `./` and update all references to it, including from the [Metadata Descriptor](../root-data-entity#ro-crate-metadata-descriptor)
 
 If the new Attached Crate is intended as a _fork_ that will evolve independently of the Detached Crate, then:
+
 * Delete the `identifier`, add the previous `@id` as `isBasedOn`
 * Delete/update `datePublished` and `publisher`
 * Add yourself as `author` or `contributor` to the Root Data Entity
@@ -444,7 +446,7 @@ WHERE {
 }
 ```
 
-{% include callout.html type="note" content='The query above will find _all_ Root Data Entities in the RDF graph. This is useful when querying RDF triple stores which contain many RO-Crates, but it also means that multiple results could be returned when the query is used on single RO-Crates which contain other [nested or referenced RO-Crates](https://www.researchobject.org/ro-crate/specification/1.2-DRAFT/data-entities.html#referencing-other-ro-crates).' %}
+{% include callout.html type="note" content="The query above will find _all_ Root Data Entities in the RDF graph. This is useful when querying RDF triple stores which contain many RO-Crates, but it also means that multiple results could be returned when the query is used on single RO-Crates which contain other [nested or referenced RO-Crates](https://www.researchobject.org/ro-crate/specification/1.2-DRAFT/data-entities.html#referencing-other-ro-crates)." %}
 
 
 ## Parsing as RDF with a different RO-Crate Root

docs/_specification/1.2-DRAFT/contextual-entities.md

@@ -505,9 +505,9 @@ This example shows how to define a place, using a [geonames] ID:
 }
 ```
 
-{% include callout.html type="tip" content='To find the `@id` and `identifier` corresponding to a GeoNames HTML page like <https://www.geonames.org/8152662/catalina-park.html>, click its `.rdf` button to download the RDF metadata (<https://sws.geonames.org/8152662/about.rdf>). In the RDF metadata, find the line that looks like the following: 
-`<gn:Feature rdf:about="http://sws.geonames.org/8152662/">`. The part in the quotes is the identifier (in this case, <http://sws.geonames.org/8152662/>) .
-' %}
+{% include callout.html type="tip" content="To find the `@id` and `identifier` corresponding to a GeoNames HTML page like <https://www.geonames.org/8152662/catalina-park.html>, click its `.rdf` button to download the RDF metadata (<https://sws.geonames.org/8152662/about.rdf>). In the RDF metadata, find the line that looks like the following: 
+`<gn:Feature rdf:about=\"http://sws.geonames.org/8152662/\">`. The part in the quotes is the identifier (in this case, <http://sws.geonames.org/8152662/>)."
+%}
 
 {% include callout.html type="tip" content="Note the use of a JSON-LD [blank node](https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node) identifier here (starting with `_:`) - this indicates to an RO-Crate presentation application that the entity does not stand in its own right, and may be displayed inline (in this case as a map)." %}
 

docs/_specification/1.2-DRAFT/crate-focus.md

@@ -151,6 +151,7 @@ For example, RO-Crates can be used as containers for Schema.org-style vocabulari
 
 
 The following example shows how both `mainEntity` and `mentions` can be used together, in this case to describe a workflow with a test suite:
+
   * the `mainEntity` is the workflow file, a _Data Entity_
   * the test suite `#test1` is a _Contextual Entity_ highlighted using `mentions`.
 

docs/_specification/1.2-DRAFT/data-entities.md

@@ -38,6 +38,7 @@ The primary purpose for RO-Crate is to gather and describe a set of _Data Entiti
 * Folders (or directories) of files -- represented using the type `Dataset`.
 
 An entity which has `File` or `Dataset` as one of its `@type` values:
+
 * Is considered to be a _Data Entity_ if its `@id` is an absolute URI or a relative URI.
 * MAY have an `@id` which is a local identifier beginning with a `#`, in which case it is **not** considered to be a `Data Entity`.
 
@@ -50,6 +51,7 @@ The Data Entities can be further described by referencing [contextual entities](
 Where files and folders are represented as _Data Entities_ in the RO-Crate JSON-LD, these MUST be linked to, either directly or indirectly, from the [Root Data Entity](root-data-entity) using the [hasPart] property. Directory hierarchies MAY be represented with nested [Dataset] _Data Entities_, or the Root Data Entity MAY refer to files anywhere in the hierarchy using [hasPart].
 
 _Data Entities_ representing files MUST have `"File"` as a value for `@type`. `File` is an RO-Crate alias for <http://schema.org/MediaObject>. The term _File_ includes:
+
 -  Resources which are available locally (applicable only in the context of _Attached RO-Crate Packages_) and
 -  [Web-based Data Entities](#web-based-data-entities) which can be downloaded and saved as a file. 
 
@@ -178,7 +180,7 @@ RO-Crate's `File` is an alias for schema.org type [MediaObject], any of its prop
 
 A `File` entity MAY have an `@id` that is a local identifier beginning with `#`, in which case it is **not** considered to be a Data Entity, though it MAY still be linked to the _Root Data Entity_ via [hasPart]. This is useful for describing physical files which are deliberately not present, for example if they are expected to be created by running a process. In this case, the `localPath` property SHOULD be used to indicate that a `File` could be found at that path in some circumstances.
 
-{% include callout.html type="note" content='It is up to implementers to decide whether to offer some form of URL "link checker" service for [Web-based Data Entities](#web-based-data-entities) for both attached and detached RO-Crate Packages. If `contentUrl` has more than one value, then a checker service SHOULD try each provided value until one resolves and returns a correct [contentSize].' %}
+{% include callout.html type="note" content="It is up to implementers to decide whether to offer some form of URL \"link checker\" service for [Web-based Data Entities](#web-based-data-entities) for both attached and detached RO-Crate Packages. If `contentUrl` has more than one value, then a checker service SHOULD try each provided value until one resolves and returns a correct [contentSize]." %}
 
 
 
@@ -315,7 +317,8 @@ Web-based entities MAY use the property [localPath] to indicate a path that can
 
 
 
-{% include callout.html type="note" content="Do not use web-based URI identifiers for files which _are_ present in the crate root, see [below](#data-entities-in-an-attached-ro-crate-that-are-also-on-the-web)." %}
+{% include callout.html type="note" content="Do not use web-based URI identifiers for files which _are_ present in the crate root, see [below](#data-entities-in-an-attached-ro-crate-that-are-also-on-the-web)."
+%}
 
 ### Data entities in an _Attached RO-Crate_ that are also on the web
 
@@ -379,7 +382,8 @@ Similarly, the _RO-Crate Root_ entity (or a reference to another RO-Crate as a `
   {
     "@id": "./",
     "@type": "Dataset",
-    "identifier": "https://doi.org/10.48546/workflowhub.workflow.775.1",
+    "identifier": {"@id": "https://doi.org/10.48546/workflowhub.workflow.775.1"},
+    "cite-as": "https://doi.org/10.48546/workflowhub.workflow.775.1",
     "name": "Research Object Crate for Jupyter Notebook Molecular Structure Checking",
     "distribution": {"@id": "https://workflowhub.eu/workflows/775/ro_crate?version=1"},
     "…": ""

docs/_specification/1.2-DRAFT/metadata.md

@@ -130,6 +130,7 @@ From [Dublin Core Terms](http://purl.org/dc/terms/) RO-Crate uses:
 - `Standard` mapped to <http://purl.org/dc/terms/Standard>
 
 From the [IANA link relations] registry:
+
 - `cite-as` mapped to <http://www.iana.org/assignments/relation/cite-as> (defined by [RFC8574])
 
 These terms are being proposed by [Bioschemas profile ComputationalWorkflow 1.0-RELEASE][ComputationalWorkflow profile 1.0] and [FormalParameter 1.0-RELEASE][FormalParameter profile 1.0] to be integrated into Schema.org: 

docs/_specification/1.2-DRAFT/root-data-entity.md

@@ -148,13 +148,15 @@ The _Root Data Entity_'s `@id` SHOULD be either `./` (indicating the directory o
 
 {% include callout.html type="note" content="RO-Crates that have been assigned a _persistent identifier_ (e.g. a DOI) MAY indicate this using [identifier] on the _Root Data Entity_ using the approach set out in the [Science On Schema.org guides], that is through a `PropertyValue` or MAY use a full persistent URL as the `@id` for the _Root Data Entity_." %}
 
-{% include callout.html type="note" content="RO-Crate 1.1 and earlier recommended `identifier` to be plain string URIs. Clients SHOULD be permissive of an RO-Crate `identifier` being a string (which MAY be a URI), or a `@id` reference, which SHOULD be represented as a `PropertyValue` entity which MUST have a human readable `value`, and SHOULD have a `url` if the identifier is Web-resolvable. A citable representation of this persistent identifier MAY be given as a `description` of the `PropertyValue`, but as there are more than 10.000 known [citation styles], no attempt should be made to parse this string."%}
+{% include callout.html type="note" content="RO-Crate 1.1 and earlier recommended `identifier` to be plain string URIs. Clients SHOULD be permissive of an RO-Crate `identifier` being a string (which MAY be a URI), or a `@id` reference, which SHOULD be represented as a `PropertyValue` entity which MUST have a human readable `value`, and SHOULD have a `url` if the identifier is Web-resolvable. A citable representation of this persistent identifier MAY be given as a `description` of the `PropertyValue`, but as there are more than 10.000 known [citation styles], no attempt should be made to parse this string."
+%}
 
 #### Resolvable persistent identifiers and citation text
 
 It is RECOMMENDED that resolving the `identifier` programmatically returns the _RO-Crate Metadata Document_ or an archive (e.g. ZIP) that contains the _RO-Crate Metadata File_, using [content negotiation](data-entities#retrieving-an-ro-crate) and/or [Signposting]. With an RO-Crate identifier that is persistent and resolvable in this way from a URI, the _Root Data Entity_ SHOULD indicate this using the `cite-as` property according to [RFC8574]. Likewise, an HTTP/HTTPS server of the resolved RO-Crate Metadata Document or archive (possibly after redirection) SHOULD indicate that persistent identifier in its [Signposting] headers using `Link rel="cite-as"`. 
 
-{% include callout.html type="tip" content='The above `cite-as` MAY go to a repository landing page, and MAY require authentication, but MUST ultimately have the RO-Crate as a downloadable item, which SHOULD be programmatically accessible through content negotiation or [Signposting] (`Link rel="describedby"` for an _RO-Crate Metadata Document_, or `Link rel="item"` for an archive). To rather associate a textual scholarly citation for a crate (e.g. journal article), indicate instead a [publication via `citation` property](contextual-entities#publications-via-citation-property).' %}
+{% include callout.html type="tip" content="The above `cite-as` MAY go to a repository landing page, and MAY require authentication, but MUST ultimately have the RO-Crate as a downloadable item, which SHOULD be programmatically accessible through content negotiation or [Signposting] (`Link rel=\"describedby\"` for an _RO-Crate Metadata Document_, or `Link rel=\"item\"` for an archive). To rather associate a textual scholarly citation for a crate (e.g. journal article), indicate instead a [publication via `citation` property](contextual-entities#publications-via-citation-property)."
+%}
 
 Any entity which is a subclass of [CreativeWork], including [Dataset]s like the _Root Data Entity_, MAY have a `creditText` property which provides a textual citation for the entity.
 

docs/_specification/1.2-DRAFT/structure.md

@@ -90,6 +90,7 @@ When processing an _Attached RO-Crate Package_ the _RO-Crate Metadata Document_
 
 
 An _Attached RO-Crate Package_ can be stored and published in multiple ways depending on its use:
+
 * On a typical hierarchical _file system_ (e.g. `/files/shared/crates/my-crate-01/`)
 * Exposed as a _Web resource_ within a folder structure (e.g. <https://www.researchobject.org/2021-packaging-research-artefacts-with-ro-crate/>)
 * [_Packaged_](appendix/implementation-notes#combining-with-other-packaging-schemes) within a ZIP file, [BagIt] archive or [OCFL] structure